Skip to main content

The Payment API

The Payment API is your starting point to every payment you accept on your platform. It allows you to build you custom checkout experience and it is the means to initiate the Rootline Checkout. In this section, we'll explain the need-to-knows about the Payments API.

Overview​

The Payment API guides you through three main steps within the checkout flow:

  1. Create a payment;
  2. Monitor the checkout_status for the payment's result;
  3. Handle required actions, which may include:
    • Payment method selection;
    • Collection of payment account details (bank account, credit card);
    • Managing redirects and authentication (e.g. 3D Secure).

Create a payment​

All payments are created through the Payments API. Depending on the parameters you send in, you will be prompted to follow any of the below flows:

  • Create a payment with only the basic details to initiate the Rootline Checkout. Let Rootline handle the Checkout steps to convert the payment;
  • Create a payment and skip the Rootline Checkout by providing all relevant parameters if the payment method allows this flow.
note

To illustrate, we use a simple payment request to your platform account. Splitting and routing payments to the sellers on your platform is explained in Split a payment to a seller

POST /payments
curl 'http://payment-api.staging.rootline.com/v1/payments' \
  --request POST \
  --header 'content-type: application/json' \
  --header 'x-api-key: [paste-your-api-key]' \
  --header 'rootline-version: 2024-04-23' \
  --data '{
    "account_id": "[platform-account-id]",
    "reference": "your-reference",
    "amount": {
        "currency": "EUR",
        "quantity": "10.00"
    },
    "payment_rails":{
        "payment_method":"ideal"
    },
    "return_url": "https://rootline.com/[PAYMENT_ID]"
}'

Handle required actions​

An open checkout_status indicates that an action needs to be taken. The next_action object contains information about what your next action should be.

checkout_statusnext_action.checkout_urlrequired action
openends with /checkoutRedirect your customer to the Rootline Checkout for payment method selection or next steps
openends with /redirectRedirect your customer to an external page through the provided Checkout URL
openends with /redirect3dsRedirect your customer through the provided URL to perform 3D Secure

Utilize the return_url​

For optimal user experience, include a return_url in every payment request. After payment completion, customers will be redirected to this URL. You can include a [PAYMENT_ID] template string that Rootline will replace with the actual payment ID for status retrieval. If not provided, Rootline uses the account's default return_url.

Monitor the outcome of the payment​

GET the payment​

To fetch the payment status after a redirect, you use our GET /payments/{payment_id} call. This is a mandatory step in a payment process that includes a redirect to an external page. Without this step your customer might not be informed in time. Webhooks are not sufficient as these could be subject to high processing loads and slower turnarounds.

The response to the GET /payment/{payment_id}
{
    "id": "pmt_4ywyzcDHlXkc3xMVOp2Zu4",
    "object": "payment",
    "created_at": "2025-02-14T09:49:53.853335Z",
    "account_id": "acc_5BTNdeSEmsHml77iazsI0r",
    "reference": "your-reference",
    "amount": {
        "currency": "EUR",
        "quantity": "10.00"
    },
    "payment_rails": {
        "payment_method": "ideal"
    },
    "checkout_status": "succeeded",
    "authorizations": [
        {
            "id": "auth_4ywyzcDHlXkc3xMVOp2Zu6",
            "object": "authorization",
            "created_at": "2025-02-17T12:24:22.006529Z",
            "amount": {
                "currency": "EUR",
                "quantity": "10.00"
            },
            "status": "approved",
            "payment_rails": {
                "payment_method": "ideal"
            },
            "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/133.0.6943.84 Mobile/15E148 Safari/604.1"
        }
    ],
    "return_url": "https://rootline.com/pmt_4ywyzcDHlXkc3xMVOp2Zu4",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/133.0.6943.84 Mobile/15E148 Safari/604.1"
}

Listen to webhook events​

Rootline sends you webhook events to inform you about the outcome of a payment. You can receive webhook events for any status change mentioned here. To learn more about our webhook events, please read our section about webhooks.

Webhook event for a succeeded payment
{
    "object": "event",
    "webhook_endpoint_id": "webh_4WxqjT0YfsxXDeKPRiebwE",
    "event_type": "payment.succeeded",
    "event_time": "2025-02-14T09:49:52.123235Z",
    "livemode": false,
    "api_version": "2024-04-23",
    "payment":
    {
        "id": "pmt_4ywyzcDHlXkc3xMVOp2Zu4",
        "object": "payment",
        "created_at": "2025-02-14T09:49:52.123235Z",
        "account_id": "your-platform-account-id",
        "reference": "your-reference",
        "amount":
        {
            "currency": "EUR",
            "quantity": "10.00"
        },
        "payment_rails":
        {
            "payment_method": "ideal"
        },
        "checkout_status": "succeeded",
        "return_url": "https://www.example.com/pmt_4ywyzcDHlXkc3xMVOp2Zu4",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36"
    }
}

When the checkout_status returns a succeeded or failed response, you can inform your customer about the final result of the payment. Read Payment statuses for more detailed information on possible payment outcomes.

Alternative or in addition to using the webhook events, you can make a GET request on the payment when Rootline returns your customer to your website.