Cards

Rootline enables you to accept Mastercard and Visa card payments.
You may opt to use Rootline’s checkout to securely accept card payments, or if you’re PCI level 1 or 2 certified, you may use the Payments API.

Rootline handles the 3D-Secure flow, including orchestrating Strong Customer Authentication (SCA) and the redirect to the customer’s bank for the various authentication challenges that a customer’s bank may pose to the customer, think biometric verification or a one-time password.
SCA might not be required, in which case Rootline handles the payment without challenge, a so-called frictionless flow.

A card payment requires a capture call to collect the authorized amount from the customer’s card.

Seamless redirect from your website to collect card details

Redirect the customer directly to Rootline and let Rootline collect the card details. To only display the card component in the Rootline checkout you will need to provide the display_payment_methods field in the payments request and set it to ["mastercard", "visa"]. If display_payment_methods is not set, all payment methods will be shown.

Example request:

{
  "account_id": "acc_12347Sifdo36cdycbsw4Pum",
  "amount": {
    "currency": "EUR",
    "quantity": "20.00"
  },
  "reference": "test_reference",
  "statement_descriptor":"Bank statement text",
  "return_url":"https://www.my_return_url.com",
  "display_payment_methods" : ["mastercard", "visa"]
}

The API will return a next_action object with a checkout_url.

{
    "payment_id": "pmt_UXRFkdU6kdAtO6ceGdxmW",
    "created_at": "2023-09-12T08:22:25.864452Z",
    "account_id": "acc_12347Sifdo36cdycbsw4Pum",
    "reference": "test_reference",
    "amount": {
        "currency": "EUR",
        "quantity": "20.00"
    },
    "checkout_status": "open",
    "authorizations": [],
    "authentications": [],
    "next_action": {
        "checkout_url": "http://payment-api.rootline.com/payments/pmt_UXRFkdU6kdAtO6ceGdxmW/checkout"
    },
	  "statement_descriptor":"Bank statement text",  
    "return_url": "https://www.my_return_url.com",
    "display_payment_methods" : ["mastercard", "visa"]
}

Redirect the customer to the checkout_url that Rootline provides.

Capture a card payment

When a card payment has succeeded, you now have an authorized or reserved amount on the customer’s card. To collect the authorized funds from your customer’s bank account you need to capture the payment. We suggest that you capture the payment when the service has rendered or the goods have been shipped.

To capture the payment you need to send a request to the Payments API /payments/{payment_id}/capture

{
    "reference": "your_reference"
}

The API response will give you a capture ID.

{  
   "id": "cap_XRhfaT3KvQoUR9D4BevMU",  
   "object": "capture",  
   "created_at": "2024-10-21T14:43:10.258222Z",  
   "reference": "your_reference"  
}

Rootline will schedule the capture. Once the capture is successfully scheduled, you will receive the capture.scheduled webhook with the capture ID from the API response. You can consider the capture request to be successful at this point, and Rootline will send the request through the network to the customer’s bank.

Cancel and refunds

A payment can be canceled when the payment succeeded with an approved authorization attempt, and when it has not been captured yet.
After the payment is captured, the funds will be transferred out of the customer’s account. To reverse that, you will need to make a refund call on the payment.

Cancel a card payment

You can cancel a card payment in case the service or goods can’t be fulfilled and the payment has not been captured yet.

To cancel the payment you need to send a request to the Payments API /payments/{payment_id}/cancel

{
    "reference": "your_reference"
}

The API response will give you a cancel ID.

{
   "id": "can_XRhfaT3KvQoUR9D4BevMU",
   "object": "cancel",
   "created_at": "2024-10-21T14:43:10.258222Z",
   "reference": "your_reference"
}

Rootline will schedule the cancel request. Once Rootline scheduled the cancel successfully you will receive the cancel.scheduled webhook with the cancel ID from the API response.

Refund a card payment

Once a payment is captured and you need to refund the payment you will be able to do so using the Payments API /payments/{payment_id}/refund

{
    "reference": "your_reference"
}

The API response will give you a refund ID.

{
   "id": "ref_XRhfaT3KvQoUR9D4BevMV",
   "object": "refund",
   "created_at": "2024-10-21T15:05:04.836408Z",
   "reference": "your_reference"
}

Rootline will schedule the refund request. Once Rootline scheduled the refund successfully you will receive the refund.scheduled webhook with the refund ID from the API response.

Statement descriptor

The statement descriptor for Mastercard and Visa support different lengths, Mastercard supports 22 characters and Visa 25.
The statement descriptor starts with “RTL*” followed by your merchant name and the statement descriptor you can provide with the payment request. Characters exceeding the character limit will not be shown on the customer's statement.

Example of a Statement descriptor:
RTL_MerchantName MyStatementDescriptor has a length of 38 characters.
On Visa the customer will see RTL_MerchantName MyStatem and on Mastercard RTL\*MerchantName MySta on their statement.

Additional Card Information

Rootline is able to handle any card type from the networks Visa or Mastercard. However, not every card from a particular network is the same. Therefore, Rootline returns information about the type of card that was processed in the API response and Webhooks. This card information is provided in the card_summary and provides you insights in the type of card that you have processed, and can help you to determine specific pricing for the type of card that was processed.

bin: The bank identification number (BIN) or sometimes referred to as the issuer identification number (IIN) is the first six digits of the card number used. This number helps to identify the issuer of the card.
last_four_digits: The last four digits of the card number, which helps to differentiate between shoppers.
funding_type: The type of funding a card uses, which can be debit or credit.
card_category: The type of card used, which can be either consumer or commercial.
regionalities [list]: This field specifies the regionality of the transaction, which is determined by the country where the card is accepted (the merchant location) and the country where the card is issued (the issuer location). The regionality is determined by selecting the most granular applicable category. The following categories are possible (in order of granularity):
- domestic: Both the merchant and card issuer are in the same country. For example a German card is used in the Germany.
- intra_EEA: Both the merchant and card issuer are in the EEA (European Economic Area plus Iceland, Liechtenstein and Norway). For example a German card is used in the Netherlands.
- intra_regional: Both the merchant and card issuer are within the same region (as defined by the card networks, which have their own definition of which countries belong to a region). For example a Swiss card is used in the Netherlands.
- inter_regional: Both the merchant and card issuer are in different regions. For example an US card is used in the Netherlands.
issuing_country_code: The country code of the issuer following the ISO 3166-1 alpha-2 standard. For example NL.

Test cards

To test card payments on our staging environment, you will need test cards with test card numbers:

payment_method	simulation	Test card number
`mastercard`	payment succeeded	`5507204133306478`
`visa`	payment succeeded	`4020441326375156`
`mastercard`	authentication succeeded, authorization declined	`5560044923274823`
`visa`	authentication succeeded, authorization declined	`4126248584142928`
`mastercard`	authentication failed	`5511176306038068`
`visa`	authentication failed	`4071324252083762`

You can choose any card holder name, future date for the expiry date, as as well as cvc.