Introduction

Direct Carrier Billing (DCB) is an alternative payment method widely used globally that offers a convenient way for customers to pay for goods and services. Integrating DCB via Payrails allows you to provide a fast, easy-to-use payment option for your customers while leveraging our platform to route the payment to any Payment Service Provider (PSP). This guide will explain the process of integrating DCB into your app or website using Payrails.

Pre-requisites

Before you start accepting DCB payments with Payrails, there are a few requirements you must meet:

1. Integrate with Payrails using one of our SDKs (coming soon) or our API
2. Configure a new integration account for DCB via one of the following Payment Service Providers:
   Boku.
3. Enable DCB as a payment option.
4. Make sure you're sending the DCB specific meta fields (found under Merchant configurations -> Meta fields on your Payrails dashboard and in the examples below) in your requests.

Ways to integrate DCB

Payrails SDK

(Coming soon for DCB) The simplest way to use DCB with Payrails is to use our drop-in in your checkout flow. With this integration type, no additional development work is required to accept payments with DCB.

Server-to-server integration

You can integrate DCB by completely managing your own client-side implementation, and use Payrails APIs with a server-to-server integration to process DCB payments. With this approach, follow the documentation below to build DCB into your applications:

Parse DCB from lookup response

With a server-to-server integration, you can call our lookup payment options endpoint to get available payment options and relevant configurations for each payment method. As the example below, you can see dcb returned as an option of the paymentCompositionOptions. You can use this value later to authorize payments with Payrails as you can see in the next sections.

{
    "name": "lookup",
    "actionId": "0bb6413e-cabb-4074-99e6-9e815c69f25b",
    "executedAt": "2024-05-08T12:33:21.527395295Z",
    "data": {
        "paymentCompositionOptions": [
            {
                "integrationType": "api",
                "paymentMethodCode": "dcb",
                "description": "DirectCarrierBilling"
            }
        ]
    },
    "links": {
        "execution": "http://payrails-api.staging.payrails.io/merchant/workflows/payment-acceptance/executions/83c534ac-13b7-43e6-b04b-f3e8b4eb4424",
        "authorize": {
            "method": "POST",
            "href": "http://payrails-api.staging.payrails.io/merchant/workflows/payment-acceptance/executions/83c534ac-13b7-43e6-b04b-f3e8b4eb4424/authorize"
        }
    }
}

Pass DCB payment method in request to authorize payment with Payrails

You can then make a request to our authorize a payment endpoint with dcb as the paymentMethodCode. See an example below:

{
  "executionId": "c0fd1c51-e709-47e5-bfd1-5d1c98f7d990",
  "amount": {
    "value": "10",
    "currency": "AED"
  },
  "paymentComposition": [{
    "integrationType": "api",
    "paymentMethodCode": "dcb",
    "storeInstrument": true, // this is a mandatory field if you're planning to do subsequent subscriptions
    "amount": {
      "value": "10",
      "currency": "AED"
    }
  }],
  "meta": {
    "customer": {
      "country": {
        "code": "AE"
      }
    },
    "order": {
      "processingType": "Regular", // change this to "Subscription" in case of a subsequent subscription
      "lines": [{
        	"description": "This is an order description sample"
        }]
    }
  },
  "returnInfo": {
    "success": "https://mysuccessurl.com",
    "error": "https://myerrorurl.com"
  }
}

Complete DCB payments optin flow to authorize first payment with Payrails

The flow above explains the initial common steps between the initial payment (the optin flow) and the subsequent payments. For the initial payment, a crucial step remains to complete the consent collection from the user, which is the authentication step.

Upon receiving the successful response of the authorize action, you should then make a request to our confirm a payment endpoint with the One-Time Pin (OTP) collected from the user sent to Payrails to complete the authentication flow with the provider. The OTP is sent as data.otp. See an example below:

{
  "executionId": "c0fd1c51-e709-47e5-bfd1-5d1c98f7d990",
  "data": {
    "otp": "123456"
  },
  "amount": {
    "value": "10",
    "currency": "AED"
  },
  "paymentComposition": [{
    "integrationType": "api",
    "paymentMethodCode": "dcb",
    "amount": {
      "value": "10",
      "currency": "AED"
    }
  }],
  "returnInfo": {
    "success": "https://mysuccessurl.com",
    "error": "https://myerrorurl.com"
  }
}

After confirming the initial payment, you'll receive a successful response. You can then after every cycle create a new payment directly as the first two steps above without having to collect any further authentication methods, like OTP.

For subsequent payments with the same holderReference in the lookup call, Payrails will return the saved consent in an instrumentId that you can use in the authorize call. You may also store the instrumentId on your end to skip the lookup call for the subsequent payments and authorize directly. Payrails will dynamically pass the payment to the provider supported with the consent associated with the instrumentId to ensure a frictionless flow. In this flow make sure to also include meta.order.processingType and pass the value "Subscription" to complete a subsequent subscription payment.

Supported regions / countries

Supported workflows and services