A quick integration

If you want Rootline to do the heavy lifting of the payment authorization flow, you may opt to make a quick integration and leverage Rootline's checkout pages to convert payments.

A quick integration only involves three steps:

• 1: Create a payment with basic payment details through the Payment API
• 2: Read the response and redirect your customer to Rootline's checkout pages
• 3: Wait for Rootline's webhook that informs you about the outcome of the payment.

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

A payment can be created with the most basic details, like in the example below. If you do want to send over more information, we advise you to do so, as it will potentially help making decisions in the payment authorization process.

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.

JSON

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

2: Read the response and do a redirect

Your response will come back like this, and will contain in the next_action object a checkout_url:

JSON

{
    "id": "pmt_27F2oLP8TAAwid1wQJUGK",
    "created_at": "2023-09-12T09:07:31.905766Z",
    "account_id": "acc_12347Sifdo36cdycbsw4Pum",
    "reference": "ef5bc3e2-dfc9-491c-89ac-c143dd34f3d0",
    "amount": {
        "currency": "EUR",
        "quantity": "20.00"
    },
    "checkout_status": "open",
    "next_action": {
        "checkout_url": "https://checkout.rootline.com/payments/pmt_27F2oLP8TAAwid1wQJUGK/checkout"
    },
    "return_url": "https://www.your-url.com/completePayment/pmt_27F2oLP8TAAwid1wQJUGK"
}

The value from the next_action.checkout_url is the page that your customer should be redirected to.

3: Processing the Return URL Redirect

When a payment completes, customers are automatically redirected to your specified return_url. To determine the payment outcome:

1. Retrieve the payment_id from the return URL parameters
2. Call GET /payments/{payment_id} to fetch the payment status
3. Check the checkout_status field in the response to determine the final payment result.

Display the payment status to the customer based on the checkout_status.

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.

4: Receive Rootline's webhook

Your last step is to receive Rootline's webhook to be informed about the result of the payment. In particular, the payment.succeeded event tells you that your payment was converted successfully. Here is an example of such webhook event:

JSON

{
  "object": "event",
  "event_type": "payment.succeeded",
  "event_time": "2023-12-14T12:12:56.185220Z",
  "livemode": false,
  "api_version": "2023-07-19",
  "payment": {
    "id": "pmt_27F2oLP8TAAwid1wQJUGK",
    "object": "payment",
    "created_at": "2023-12-14T11:53:59.786633Z",
    "account_id": "acc_12347Sifdo36cdycbsw4Pum",
    "reference": "test_reference",
    "amount": {
      "currency": "EUR",
      "quantity": "20.00"
    },
    "checkout_status": "succeeded",
    "return_url": "https://www.your-url.com"
  }
}

You will also want to configure other event types in case the payment was not successfully converted. To learn more about webhooks, please refer to our Webhooks documentation.