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 are 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, such as a biometric verification or a one-time password (OTP). Not every payment will be challenged by the Issuer, 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.

Payment method details

Currency	EUR
Countries	Global
Minimum transaction value	0.01
Maximum transaction value	N/a
Capture	Supported
Cancel	Supported
Refund	Full and (multiple) partial refunds are supported.
Disputes	Supported
Statement descriptor	Mastercard supports 22 characters and Visa 25 Characters. 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.

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.

Important

When an online card transaction is authorized a reservation is placed on the card holders account. This reservation is usually valid for 7 days after which it will expire. Unless you or your shopper wishes to cancel a service or product, a transaction needs to be captured in order to initiate the funds transfer from the Issuer to the Merchant's bank. We advice to capture as soon as services or products are delivered. After a capture is initiated on a transaction, a cancel operation is no longer available. If you wish to undo (of reverse) the transaction, you can do so by refunding (/payments/id/refund) the payment.

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	country	card category	funding type
mastercard	payment succeeded	5507204133306478	NL	consumer	credit
visa	payment succeeded	4020441326375156	NL	consumer	credit
mastercard	authentication succeeded, authorization declined	5560044923274823	NL	consumer	credit
visa	authentication succeeded, authorization declined	4126248584142928	NL	consumer	credit
mastercard	authentication failed	5511176306038068	NL	consumer	credit
visa	authentication failed	4071324252083762	NL	consumer	credit
mastercard	authentication failed	5100000000000005	NL	consumer	credit
visa	Frictionless authorization approved	4242424242424243	NL	consumer	credit
mastercard	Frictionless authorization approved	5874545485397860	NL	consumer	credit
visa	Frictionless authorization declined	4444333322221112	NL	consumer	credit
mastercard	Frictionless authorization declined	5405395542826412	NL	consumer	credit
visa	Authentication required, authorization approved	4669067104353812	DE	consumer	credit
visa	Authentication required, authorization approved	4637677687461631	US	consumer	credit
visa	Authentication required, authorization approved	4075695062946926	GL	consumer	credit
visa	Authentication required, authorization declined	4675188598939213	NL	consumer	credit
mastercard	Authentication required, authorization declined	5845831380539418	NL	consumer	credit
visa	Frictionless authorization approved	4006653455314578	NL	consumer	debit
visa	Frictionless authorization approved	4319123467890124	ES	consumer	credit
mastercard	Frictionless authorization approved	5400000000000006	ES	consumer	credit
visa	Frictionless authorization approved	4532789012345672	DE	consumer	debit
mastercard	Frictionless authorization approved	5209888888888887	DE	consumer	debit
visa	Frictionless authorization approved	4532956789012344	GB	commercial	credit
mastercard	Frictionless authorization approved	5500999999999996	GB	commercial	credit
visa	Frictionless authorization approved	4798567890123455	SG	commercial	credit
mastercard	Frictionless authorization approved	5355888888888889	SG	commercial	credit
visa	Frictionless authorization approved	4929845678901231	US	commercial	credit
mastercard	Frictionless authorization approved	5533666666666668	US	commercial	credit
visa	Frictionless authorization approved	4789567890123456	NL	commercial	credit
mastercard	Frictionless authorization approved	5200000000000008	NL	commercial	debit
visa	Frictionless authentication failed	4222222222222239	NL	commercial	debit
mastercard	Frictionless authentication failed	5100000000000009	NL	consumer	credit
visa	Frictionless authorization declined	4273374017262280	NL	consumer	credit
mastercard	Frictionless authorization declined	5500000000000005	NL	consumer	debit

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