> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.
# Direct Carrier Billing
> Direct Carrier Billing (DCB) is an alternative payment method which enables customers enjoy a seamless checkout experience, with a choice of fulfilling their payments as a surcharge to their phone bill at the end of every cycle (usually monthly) without the use of any payment instruments. For customers who uses a prepaid sim card, the amount will be deducted from their current balance.
export const AuthorizeRequestExample = ({paymentMethodCode, integrationType = "api", amount = "1000", currency = "USD", executionId = "c0fd1c51-e709-47e5-bfd1-5d1c98f7d990", orderLine, meta, paymentComposition, request, returnInfo = {
success: "https://mysuccessurl.com",
error: "https://myerrorurl.com"
}}) => {
const line = orderLine || ({
id: "UUID",
name: "Order Name",
quantity: 1,
unitPrice: {
currency,
value: amount
}
});
const composition = paymentComposition || [{
integrationType,
paymentMethodCode,
amount: {
value: amount,
currency
}
}];
const defaultRequest = {
executionId,
amount: {
value: amount,
currency
},
paymentComposition: composition,
meta: meta || ({
order: {
lines: [line]
}
}),
returnInfo: returnInfo === null ? undefined : returnInfo
};
const output = request || defaultRequest;
return
{JSON.stringify(output, null, 2)}
;
};
export const LookupResponseExample = ({paymentMethodCode, description, integrationType = "api", options, actionId = "0bb6413e-cabb-4074-99e6-9e815c69f25b", executedAt = "2026-03-26T12:00:00.000000000Z", executionId = "83c534ac-13b7-43e6-b04b-f3e8b4eb4424", response}) => {
const paymentCompositionOptions = options || [{
integrationType,
paymentMethodCode,
description: description || paymentMethodCode
}];
const executionUrl = `https://api.payrails.io/merchant/workflows/payment-acceptance/executions/${executionId}`;
const output = response || ({
name: "lookup",
actionId,
executedAt,
data: {
paymentCompositionOptions
},
links: {
execution: executionUrl,
authorize: {
method: "POST",
href: `${executionUrl}/authorize`
}
}
});
return
{JSON.stringify(output, null, 2)}
;
};
export const AuthorizeRequestIntro = ({method, paymentMethodCode}) =>
You can then make a request to our authorize a payment endpoint with{" "}
{paymentMethodCode} as the paymentMethodCode. See an example below:
;
export const LookupResponseIntro = ({method, paymentMethodCode}) =>
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 {paymentMethodCode} 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.
;
export const SupportedWorkflowsTable = ({workflows, workflowKeys}) => {
const hideUnsupportedWorkflows = ["interoperability"];
if (!workflows) {
return
No workflow data configured for this method yet — add an
entry to snippets/payment-methods/data.mdx.
;
}
return
| Workflow |
Supported |
{workflowKeys.filter(w => workflows[w.key] !== false || !hideUnsupportedWorkflows.includes(w.key.toLowerCase())).map(w => {
const value = workflows[w.key];
const display = value === true ? "✔" : value === false ? "✖" : value === "pending" ? "⏳" : value === null ? "N/A" : value;
return
|
{w.href ? {w.label} : w.label}
|
{display} |
;
})}
;
};
export const SupportedCountriesTable = ({countries, continents, method, merchant = false}) => {
const flagFor = code => code.toUpperCase().replace(/./g, ch => String.fromCodePoint(ch.charCodeAt(0) + 127397));
if (!countries || countries.length === 0) {
return
No countries configured for this method yet — add an entry
to snippets/payment-methods/data.mdx.
;
}
const byContinent = {};
for (const continent of continents) {
byContinent[continent] = [];
}
for (const country of countries) {
if (!byContinent[country.continent]) {
byContinent[country.continent] = [];
}
byContinent[country.continent].push(country);
}
const rows = continents.map(continent => ({
continent,
list: (byContinent[continent] || []).slice().sort((a, b) => a.name.localeCompare(b.name))
})).filter(row => row.list.length > 0);
const description = merchant ? `Merchants based in the following regions can accept ${method} payments:` : `${method} is available to customers based in:`;
return
{method &&
{description}
}
| Region(s) |
Countries |
{rows.map(row =>
|
{row.continent}
|
{row.list.map(c =>
{flagFor(c.code)} {c.name}
)}
|
)}
#### Parse DCB from lookup response
#### Pass DCB payment method in request to authorize payment with Payrails
#### 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](/reference/confirmaction) 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:
```json theme={null}
{
"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 regions / countries
## Supported workflows and services
## Related topics
- [Billing](/docs/use-cases/billing-use-cases.md)
- [Stripe](/docs/orchestration/integrations/stripe.md)
- [PayPal](/docs/orchestration/payment-methods/paypal/index.md)