> ## 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.
> PayPal is an alternative payment method around the globe. With PayPal, customers can enjoy a seamless checkout experience, with a choice of fulfilling their payments with their wallet balance or any payment method that is linked to their account, e.g saved cards, bank accounts, e-wallets, etc.. Via PayPal, customers can also use a BNPL payment scheme and install the purchase amount directly to PayPal.
# PayPal
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 ServerToServerIntro = ({method}) =>
The simplest way to use {method} is by completely managing your own client-side implementation, and using
Payrails APIs with a server-to-server integration to process payments with {method}. With this approach, follow
the documentation below to build {method} into your applications:
;
export const PayrailsSDKIntro = ({method, element}) =>
The simplest way to use {method} 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 {method}.
{element ? <>
{" "}
For a more flexible implementation using our SDK, you can use our {element} element.
: null}
;
export const Prerequisites = ({method, providers = [], configureInDashboard = false, extraSteps = []}) => {
const providerLinks = providers.flatMap((p, i) => {
const link = p.href ?
{p.name}
: {p.name};
if (i === 0) {
return [link];
}
const isLast = i === providers.length - 1;
const separator = isLast && providers.length > 2 ? ", and " : isLast ? " and " : ", ";
return [{separator}, link];
});
return
-
Integrate with Payrails using one of our{" "}
SDKs or our{" "}
API
-
Configure a new integration account for{" "}
{method} via {providerLinks.length > 0 ? providerLinks : "your Payment Service Provider"}.
{providers.length === 1 && providers[0].setupGuideHref ? <>
{" "}
If you do not have a {providers[0].name} integration already configured in your workspace, please
follow the{" "}
{providers[0].name} integration setup guide first.
: null}
{configureInDashboard && providers[0] && -
Enable {method} as a payment method in your {providers[0].name} integration configuration. In the
Payrails portal, navigate to Settings → Integrations, select your {providers[0].name}{" "}
integration instance, and enable the {method} checkbox under Payment methods, then save
the account.
}
-
Enable {method} as a payment option.
{extraSteps.map((step, i) => - {step}
)}
-
Make sure you're sending the {method}-specific meta fields (found under Merchant configurations -> Meta
fields on your Payrails dashboard and in the examples below) in your requests.
;
};
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}
)}
|
)}