> ## 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.

# Cards

> What you need in place to accept card payments through Payrails, from provider configuration to the integration that collects card data.

<picture noZoom>
  ![Cards logo](https://assets.payrails.io/img/logos/card/card-logo.svg)
</picture>

## Introduction

Accepting card payments is essential for any online business, as it allows customers to make transactions quickly and securely. Payrails simplifies the process of accepting card payments. This guide will walk you through the steps to integrate card payments into your app or website using Payrails, ensuring a smooth and reliable transaction process.

## Pre-requisites

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

1. Integrate with Payrails using one of our [SDKs](https://docs.payrails.com/docs/sdks/checkout-sdks.md) or [accept payments via API](https://docs.payrails.com/docs/orchestration/accept-payments-via-api.md)
2. Configure a new [integration account](https://docs.payrails.com/docs/integrations/payment-providers) for cards via [Adyen](https://docs.payrails.com/docs/integrations/payment-providers/adyen.md), [AmEx](https://docs.payrails.com/docs/integrations/payment-providers/amex.md), [Checkout.com](https://docs.payrails.com/docs/integrations/payment-providers/checkout-com.md), [dLocal](https://docs.payrails.com/docs/integrations/payment-providers/dlocal.md), [Fawry](https://docs.payrails.com/docs/integrations/payment-methods/fawrypay), [Flutterwave](https://docs.payrails.com/docs/integrations/payment-providers), [Garanti BBVA](https://docs.payrails.com/docs/integrations/payment-providers), [HyperPay](https://docs.payrails.com/docs/integrations/payment-providers), [Lidio](https://docs.payrails.com/docs/integrations/payment-providers), [PayU](https://docs.payrails.com/docs/integrations/payment-providers), [Pine Labs](https://docs.payrails.com/docs/integrations/payment-providers), [Stripe](https://docs.payrails.com/docs/integrations/payment-providers/stripe.md), [Tap](https://docs.payrails.com/docs/integrations/payment-providers), and [Unlimit](https://docs.payrails.com/docs/integrations/payment-providers).
3. Enable cards as a [payment option](https://docs.payrails.com/docs/integrations/payment-methods/set-up-payment-methods.md).
4. Make sure you're sending the cards-specific meta fields (found under Merchant configurations -> Meta fields on your Payrails dashboard and in the examples below) in your requests.

*Support for Nuvei and WorldPay is coming soon.*

## Ways to integrate cards

Payrails offers two main integration types for accepting card payments, each with its own set of advantages:

### Payrails SDK

Payrails provides a hosted payment page, which is a fully customizable and responsive payment form hosted on our secure servers. This option suits businesses that want to accept card payments without handling sensitive card information directly.

#### Benefits:

* Reduces your PCI-DSS compliance scope.
* Provides a customizable and responsive payment form.
* Minimizes the need for complex front-end development.

#### Integration Steps

1. Configure the hosted payment page settings in your Payrails dashboard.
2. Redirect customers to the hosted payment page URL when they initiate a payment.
3. Handle the response from Payrails after the transaction is completed.

### Server-to-server integration

Payrails also provides an API integration option, which allows you to build a fully custom payment form within your app or website. This option requires a higher level of PCI-DSS compliance but offers more flexibility and control over the payment experience.

#### Benefits:

* Complete control over the payment form's design and functionality.
* Integrates with your existing user interface.
* Provides more flexibility in handling payment-related events and actions.

#### Integration Steps

1. Collect card information from the customer using a secure payment form on your app or website.
2. Tokenize the card data using the Payrails API, which securely sends the data to Payrails and returns a token.
3. Use the token to process the payment through the Payrails API, specifying the desired PSP and transaction details.
4. Handle the response from Payrails to confirm the transaction's success or handle any errors.

Choose the integration type that best suits your business needs and follow the appropriate steps to start accepting card payments with Payrails.

#### Parse card from lookup response

With a server-to-server integration, you can call our [lookup payment options](https://docs.payrails.com/docs/orchestration/payment-acceptance/lookup-payment-options.md) endpoint to get available payment options and relevant configurations for each payment method. As the example below, you can see `genericRedirect` 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.

```json lines theme={null}
{
  "name": "lookup",
  "actionId": "0bb6413e-cabb-4074-99e6-9e815c69f25b",
  "executedAt": "2026-03-26T12:00:00.000000000Z",
  "data": {
    "paymentCompositionOptions": [
      {
        "integrationType": "api",
        "paymentMethodCode": "card",
        "description": "Card"
      }
    ]
  },
  "links": {
    "execution": "https://api.payrails.io/merchant/workflows/payment-acceptance/executions/83c534ac-13b7-43e6-b04b-f3e8b4eb4424",
    "authorize": {
      "method": "POST",
      "href": "https://api.payrails.io/merchant/workflows/payment-acceptance/executions/83c534ac-13b7-43e6-b04b-f3e8b4eb4424/authorize"
    }
  }
}
```

#### Pass card payment method in request to authorize payment with Payrails

You can then make a request to our [authorize a payment endpoint](https://docs.payrails.com/reference/authorizeaction.md) with `card` as the `paymentMethodCode`. See an example below:

```json lines theme={null}
{
  "executionId": "c0fd1c51-e709-47e5-bfd1-5d1c98f7d990",
  "amount": {
    "value": "100",
    "currency": "USD"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "card",
      "amount": {
        "value": "100",
        "currency": "USD"
      }
    }
  ],
  "meta": {
    "order": {
      "lines": [
        {
          "id": "UUID",
          "name": "Order Name",
          "quantity": 1,
          "unitPrice": {
            "currency": "USD",
            "value": "100"
          }
        }
      ]
    }
  },
  "returnInfo": {
    "success": "https://mysuccessurl.com",
    "error": "https://myerrorurl.com"
  }
}
```

## Supported regions / countries

Cards is available to customers based in:

<table>
  <thead>
    <tr><th>Regions</th><th>Countries</th></tr>
  </thead>

  <tbody>
    <tr><td>**Africa**</td><td>🇨🇲 Cameroon🇪🇬 Egypt🇬🇭 Ghana🇰🇪 Kenya🇲🇼 Malawi🇲🇦 Morocco🇳🇬 Nigeria🇷🇼 Rwanda🇸🇳 Senegal🇿🇦 South Africa🇹🇿 Tanzania🇺🇬 Uganda</td></tr>
    <tr><td>**Asia Pacific**</td><td>🇦🇺 Australia🇧🇩 Bangladesh🇨🇳 China🇭🇰 Hong Kong🇮🇳 India🇮🇩 Indonesia🇯🇵 Japan🇲🇾 Malaysia🇲🇻 Maldives🇳🇿 New Zealand🇵🇰 Pakistan🇵🇭 Philippines🇸🇬 Singapore🇰🇷 South Korea🇱🇰 Sri Lanka🇹🇼 Taiwan🇹🇭 Thailand🇻🇳 Vietnam</td></tr>
    <tr><td>**Europe**</td><td>🇦🇹 Austria🇧🇪 Belgium🇧🇬 Bulgaria🇭🇷 Croatia🇨🇾 Cyprus🇨🇿 Czech Republic🇩🇰 Denmark🇪🇪 Estonia🇫🇮 Finland🇫🇷 France🇩🇪 Germany🇬🇮 Gibraltar🇬🇷 Greece🇭🇺 Hungary🇮🇸 Iceland🇮🇪 Ireland🇮🇹 Italy🇱🇻 Latvia🇱🇮 Liechtenstein🇱🇹 Lithuania🇱🇺 Luxembourg🇲🇹 Malta🇳🇱 Netherlands🇳🇴 Norway🇵🇱 Poland🇵🇹 Portugal🇷🇴 Romania🇸🇰 Slovakia🇸🇮 Slovenia🇪🇸 Spain🇸🇪 Sweden🇨🇭 Switzerland🇹🇷 Turkey🇬🇧 United Kingdom</td></tr>
    <tr><td>**Latin America**</td><td>🇦🇷 Argentina🇧🇴 Bolivia🇧🇷 Brazil🇨🇱 Chile🇨🇴 Colombia🇨🇷 Costa Rica🇩🇴 Dominican Republic🇪🇨 Ecuador🇸🇻 El Salvador🇬🇹 Guatemala🇭🇳 Honduras🇲🇽 Mexico🇳🇮 Nicaragua🇵🇦 Panama🇵🇾 Paraguay🇵🇪 Peru🇵🇷 Puerto Rico🇺🇾 Uruguay</td></tr>
    <tr><td>**Middle East**</td><td>🇧🇭 Bahrain🇮🇶 Iraq🇮🇱 Israel🇯🇴 Jordan🇰🇼 Kuwait🇴🇲 Oman🇸🇦 Saudi Arabia🇦🇪 United Arab Emirates</td></tr>
    <tr><td>**North America**</td><td>🇨🇦 Canada🇺🇸 United States</td></tr>
  </tbody>
</table>

Cards payments may be available in additional countries based on the status of their integrations and each provider's technology rollout.

## Supported workflows and services

<table>
  <thead>
    <tr><th>Workflow</th><th>Supported</th></tr>
  </thead>

  <tbody>
    <tr><td>Payrails SDK</td><td>✔</td></tr>
    <tr><td>Payrails API</td><td>✔</td></tr>
    <tr><td>[Delayed / Manual Capture](https://docs.payrails.com/docs/orchestration/payment-acceptance/capture-and-cancel-modes.md#capture-mode)</td><td>✔</td></tr>
    <tr><td>[Instant Capture](https://docs.payrails.com/docs/orchestration/payment-acceptance/capture-and-cancel-modes.md#capture-mode)</td><td>✔</td></tr>
    <tr><td>[Cancel / Void](https://docs.payrails.com/docs/orchestration/payment-acceptance/cancel-a-payment.md)</td><td>✔</td></tr>
    <tr><td>[Refund / Reverse](https://docs.payrails.com/docs/orchestration/payment-acceptance/refund-a-payment.md)</td><td>✔</td></tr>
    <tr><td>[Save Instruments](https://docs.payrails.com/docs/resources/manage-instruments.md)</td><td>✔</td></tr>
    <tr><td>[Merchant Initiated Transaction (MIT)](https://docs.payrails.com/docs/resources/payments/authorization-flags.md)</td><td>✔</td></tr>
    <tr><td>Interoperability</td><td>Vault tokens, PSP tokens, Network tokens</td></tr>
  </tbody>
</table>


## Related topics

- [Cards via Proxy](https://docs.payrails.com/docs/token-vault/vault-proxy/proxy-payment-instruments/cards-via-proxy.md)
- [Korean Local Cards](https://docs.payrails.com/docs/integrations/payment-methods/korean-local-cards.md)
- [Co-branded cards](https://docs.payrails.com/docs/integrations/payment-methods/cards/co-branded-cards.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.