A custom integration

Use the Payment API to fully control the look-and-feel of your checkout. Do the payment method selection and collect all required payment details until you can complete the payment.

The Payment API helps you design the checkout process. With the Payment API you:

• 1: Create a payment
• 2: Follow up on any required actions, which may vary or be a combination of various sub-steps:
  • Choose your customer's payment method of choice
  • Collect your customer's payment account details, such as their bank account or credit card
  • Handle redirects and authentication, such as Strong Customer Authentication for 3D Secure
• 3: Read the checkout_status to learn about the result of the payment. For asynchronous authorization processes, you will rely on the webhook that we send, for instance the payment.succeeded or payment.failed event.

Here are the steps in more detail.

The Payment API endpoint

Staging

https://payment-api.staging.rootline.com/v1/payments

Production

https://payment-api.rootline.com/v1/payments

1: Create a payment

The first step is to create a payment. You are expected to collect all relevant payment details at once in your /POST /payments to Rootline.

We recommend that you send in the return_url with every payment request. When the payment is completed, your customer will be automatically returned to the return_url that you provided in the payment request. In the return_url you can provide a template string [PAYMENT_ID] which Rootline will replace with the payment_id of the payment that you can use to retrieve the payment status.
If you don't provide a return_url in the payment request we use the return_url configured on the account.

Provide a payment method

JSON

{
    "account_id": "acc_12347Sifdo36cdycbsw4Pum",
    "amount": {
        "currency": "EUR",
        "quantity": "20.00"
    },
    "reference": "ef5bc3e2-dfc9-491c-89ac-c143dd34f3d0",
    "payment_rails": {
        "payment_method": "ideal"
    },
    "description": "Test description",
    "return_url": "https://www.your-url.com/completePayment/[PAYMENT_ID]"
}

2: Follow up on the expected actions

When the payment is open, you may be prompted to complete actions. For instance, you may be asked to initiate a redirect through the provided checkout_url. If the checkout_url ends with /redirect, you are asked to redirect the customer to this endpoint.

🚧

We are working on adding more details to the next_action object.

Redirect your customer to an external page

Some payment methods or flows may require a redirect to the page of the acquiring payment method, for instance, for ideal. Here's an example of a response you can get.

JSON

{
    "payment_id": "pmt_4gfELagpJ132Gz4KsWEAGS",
    "object": "payment",
    "created_at": "2023-11-11T18:58:56.013066Z",
    "account_id": "acc_12347Sifdo36cdycbsw4Pum",
    "reference": "ef5bc3e2-dfc9-491c-89ac-c143dd34f3d0",
    "amount": {
        "currency": "EUR",
        "quantity": "20.00"
    },
    "payment_rails": {
        "payment_method": "ideal"
    },
    "checkout_status": "open",
    "authorizations": [],
    "authentications": [],
    "next_action": {
        "checkout_url": "https://checkout.staging.rootline.com/payments/pmt_4gfELagpJ3tWGz4KsWEAGS/redirect"
    },
    "return_url": "https://your-url.com/"
}

3: After completion, read the payment status and ship your product or service

Once the payment is successfully completed, the checkout_status succeeded will be returned, and the rendering of the service or delivery of the goods may be initiated. Your customer will be returned to the return_url you provided in the payment request.

If your payment came back as failed, it can mean that the authorization attempt was declined, or an error occurred in the authorization process. You're asked to initiate a new attempt by creating a new payment.

If you want to retrieve more details around why the payment failed, you are asked to go a level deeper and look at the authorization details, in particular the decline_details.

You are advised to configure webhooks to inform your system about the outcome of the payment. Please find more details about webhooks in our Webhooks documentation.