> ## 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.
> PagoEfectivo is Peru's leading alternative payment network, allowing customers to pay for online purchases in cash at thousands of payment points across the country, or through their bank's online or mobile banking. It is widely used in Peru as it provides access to e-commerce for customers without credit cards.
# PagoEfectivo
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 RedirectHandlingNote = ({method}) =>
After the customer completes the payment with {method}, they will be redirected back to your{" "}
success or error URL. You should then verify the payment status by checking the
workflow execution status via the Payrails API or by listening to webhook notifications.
;
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}
)}
|
)}