> ## 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 > Accept PayPal via the direct Payrails integration, handle the required redirect action, and create billing agreements for recurring charges. ![PayPal logo](https://assets.payrails.io/img/logos/paypal/logo-full-bleed.svg) ## Introduction PayPal is a global online payment system that allows users to pay for goods and services, send money, and accept payments without revealing their financial details. It's widely accepted around the world and used by millions of businesses and individuals daily. With Payrails' direct PayPal integration you can accept payments, create billing agreements with PayPal and charge customers for recurring payments, and implement PayPal either using our SDKs or with a server-to-server integration. ### PayPal via Braintree You can also process PayPal through Braintree. To set it up, follow the [PayPal via Braintree](https://docs.payrails.com/docs/integrations/payment-methods/paypal/braintree.md) guide. ## Pre-requisites In order to use Payrails' PayPal integration, you need to grant us permission to make requests on behalf of your PayPal merchant account. In order to initiate this process, please contact your Payrails account representative. We will send you a link to a PayPal onboarding page where you can grant us access to make calls on your behalf. Please note that you have to separately connect your sandbox PayPal account and your production account. Before you start accepting PayPal 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 PayPal via [PayPal](https://docs.payrails.com/docs/integrations/payment-providers/paypal.md). 3. Enable PayPal as a [payment option](https://docs.payrails.com/docs/integrations/payment-methods/set-up-payment-methods.md). 4. Make sure you're sending the PayPal-specific meta fields (found under Merchant configurations -> Meta fields on your Payrails dashboard and in the examples below) in your requests. ## Ways to integrate ### Payrails SDK The simplest way to use PayPal with Payrails is to use our [drop-in](https://docs.payrails.com/docs/sdks/web.md#drop-in) in your checkout flow. With this integration type, no additional development work is required to accept payments with PayPal. ### Server-to-server integration The simplest way to use PayPal is by completely managing your own client-side implementation, and using Payrails APIs with a server-to-server integration to process payments with PayPal. With this approach, follow the documentation below to build PayPal into your applications: #### Parse PayPal 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 `payPal` 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": "payPal", "description": "PayPal" } ] }, "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 PayPal 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 `payPal` 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": "payPal", "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" } } ``` #### Complete the Payment Flow After initiating the authorization, use the [Get an execution by ID endpoint](https://docs.payrails.com/reference/getexecution.md) to fetch the execution details. In the API response, locate the `requiredAction` object (see example below). If present, this indicates that user interaction is required. Extract the `requiredAction.href` URL from this object. ```json theme={null} { "id": "c0fd1c51-e709-47e5-bfd1-5d1c98f7d990", "status": [ { "code": "authorizePending", "time": "2024-05-08T12:33:25.362443Z" }, { "code": "created", "time": "2024-05-08T12:33:21.758224Z" }, { "code": "authorizeRequested", "time": "2024-05-08T12:33:23.401641Z" } ], "createdAt": "2024-05-08T12:33:21.758224Z", "merchantReference": "a85d6211-26d0-4a12-ae85-4d576a700922", "holderId": "5fc2d688-c19c-45c5-9c38-57072fcda416", "workspaceId": "7f9f1882-a103-408d-ac96-46a7021e537a", "holderReference": "9d42ef80-3aa4-4485-895e-4207bc97a966", "amount": { "value": "100.00", "currency": "USD" }, "paymentComposition": [ { "integrationType": "api", "paymentMethodCode": "payPal", "amount": { "value": "100.00", "currency": "USD" } } ], "workflow": { "code": "payment-acceptance", "version": 4 }, "meta": { "CIT": true, "order": { "lines": [ { "id": "c5f19f65-48d5-4449-8d60-b9c01547ca8e", "name": "Order Name", "quantity": 1, "unitPrice": { "currency": "USD", "value": "100" } } ] }, "risk": { "sessionId": "69eb6092-9fbd-47bb-8016-7360f7786215" } }, "returnInfo": { "success": "https://mysuccessurl.com", "error": "https://myerrorurl.com" }, "links": { "self": "https://api.eu.staging.payrails.io/merchant/workflows/payment-acceptance/executions/c0fd1c51-e709-47e5-bfd1-5d1c98f7d990", "redirect": "https://api.eu.staging.payrails.io/public/redirect/merchant/payment-acceptance/c0fd1c51-e709-47e5-bfd1-5d1c98f7d990/ixBNaQZD5v5FqfswOlKRqOD0QpIqBIsbqB_s5yGMy_OfAhF7MDAwMA==", "confirm": { "method": "POST", "href": "https://api.eu.staging.payrails.io/merchant/workflows/payment-acceptance/executions/c0fd1c51-e709-47e5-bfd1-5d1c98f7d990/confirm", "action": { "type": "confirm", "redirectUrl": "https://www.sandbox.paypal.com/agreements/approve?ba_token=BA-2RN64831HG685960Y", "redirectMethod": "GET", "parameters": { "tokenId": "BA-2RN64831HG685960Y" } } } }, "actionRequired": "redirect", "requiredAction": { "method": "GET", "href": "https://api.eu.staging.payrails.io/public/redirect/merchant/payment-acceptance/c0fd1c51-e709-47e5-bfd1-5d1c98f7d990/ixBNaQZD5v5FqfswOlKRqOD0QpIqBIsbqB_s5yGMy_OfAhF7MDAwMA==", "type": "redirect", "subType": "client" } } ``` Redirect the customer to the `requiredAction.href` URL. They will be taken to the PayPal login page to complete the payment. After the customer completes the payment, Payrails will send a server-to-server notification to your configured webhook endpoint. This payload will contain the `holderReference`and `paymentInstrumentId` required for performing future recurring (MIT) payments. ## Supported regions / countries PayPal is available to customers based in:
RegionsCountries
**Africa**🇩🇿 Algeria🇦🇴 Angola🇧🇯 Benin🇧🇼 Botswana🇧🇫 Burkina Faso🇧🇮 Burundi🇨🇲 Cameroon🇨🇻 Cape Verde🇹🇩 Chad🇰🇲 Comoros🇨🇬 Congo🇩🇯 Djibouti🇨🇩 DR Congo🇪🇬 Egypt🇪🇷 Eritrea🇸🇿 Eswatini🇪🇹 Ethiopia🇬🇦 Gabon🇬🇲 Gambia🇬🇳 Guinea🇬🇼 Guinea-Bissau🇨🇮 Ivory Coast🇰🇪 Kenya🇱🇸 Lesotho🇲🇬 Madagascar🇲🇼 Malawi🇲🇱 Mali🇲🇷 Mauritania🇲🇺 Mauritius🇲🇦 Morocco🇲🇿 Mozambique🇳🇦 Namibia🇳🇪 Niger🇳🇬 Nigeria🇷🇼 Rwanda🇸🇹 Sao Tome and Principe🇸🇳 Senegal🇸🇨 Seychelles🇸🇱 Sierra Leone🇸🇴 Somalia🇿🇦 South Africa🇸🇭 St Helena🇹🇿 Tanzania🇹🇬 Togo🇹🇳 Tunisia🇺🇬 Uganda🇿🇲 Zambia🇿🇼 Zimbabwe
**Asia Pacific**🇦🇺 Australia🇧🇹 Bhutan🇧🇳 Brunei🇰🇭 Cambodia🇨🇳 China🇨🇰 Cook Islands🇫🇯 Fiji🇵🇫 French Polynesia🇭🇰 Hong Kong🇮🇳 India🇮🇩 Indonesia🇯🇵 Japan🇰🇿 Kazakhstan🇰🇮 Kiribati🇰🇬 Kyrgyzstan🇱🇦 Laos🇲🇾 Malaysia🇲🇻 Maldives🇲🇭 Marshall Islands🇫🇲 Micronesia🇲🇳 Mongolia🇳🇷 Nauru🇳🇵 Nepal🇳🇨 New Caledonia🇳🇿 New Zealand🇳🇺 Niue🇳🇫 Norfolk Islands🇵🇼 Palau🇵🇬 Papua New Guinea🇵🇭 Philippines🇵🇳 Pitcairn Islands🇼🇸 Samoa🇸🇬 Singapore🇸🇧 Solomon Islands🇰🇷 South Korea🇱🇰 Sri Lanka🇹🇼 Taiwan🇹🇯 Tajikistan🇹🇭 Thailand🇹🇴 Tonga🇹🇲 Turkmenistan🇹🇻 Tuvalu🇻🇺 Vanuatu🇻🇳 Vietnam
**Europe**🇦🇱 Albania🇦🇩 Andorra🇦🇹 Austria🇧🇾 Belarus🇧🇪 Belgium🇧🇦 Bosnia and Herzegovina🇧🇬 Bulgaria🇭🇷 Croatia🇨🇾 Cyprus🇨🇿 Czech Republic🇩🇰 Denmark🇪🇪 Estonia🇫🇴 Faroe Islands🇫🇮 Finland🇫🇷 France🇩🇪 Germany🇬🇷 Greece🇭🇺 Hungary🇮🇸 Iceland🇮🇪 Ireland🇮🇹 Italy🇱🇻 Latvia🇱🇮 Liechtenstein🇱🇹 Lithuania🇱🇺 Luxembourg🇲🇹 Malta🇲🇩 Moldova🇲🇨 Monaco🇲🇪 Montenegro🇳🇱 Netherlands🇲🇰 North Macedonia🇳🇴 Norway🇵🇱 Poland🇵🇹 Portugal🇷🇴 Romania🇷🇺 Russia🇸🇲 San Marino🇷🇸 Serbia🇸🇰 Slovakia🇸🇮 Slovenia🇪🇸 Spain🇸🇪 Sweden🇨🇭 Switzerland🇺🇦 Ukraine🇬🇧 United Kingdom🇻🇦 Vatican City
**Latin America**🇦🇮 Anguilla🇦🇬 Antigua and Barbuda🇦🇷 Argentina🇦🇼 Aruba🇧🇸 Bahamas🇧🇧 Barbados🇧🇿 Belize🇧🇴 Bolivia🇧🇷 Brazil🇻🇬 British Virgin Islands🇰🇾 Cayman Islands🇨🇱 Chile🇨🇴 Colombia🇨🇷 Costa Rica🇩🇲 Dominica🇩🇴 Dominican Republic🇪🇨 Ecuador🇸🇻 El Salvador🇫🇰 Falkland Islands🇬🇩 Grenada🇬🇹 Guatemala🇬🇾 Guyana🇭🇳 Honduras🇯🇲 Jamaica🇲🇽 Mexico🇲🇸 Montserrat🇳🇮 Nicaragua🇵🇦 Panama🇵🇾 Paraguay🇵🇪 Peru🇱🇨 St Lucia🇸🇷 Suriname🇹🇨 Turks and Caicos🇺🇾 Uruguay🇻🇪 Venezuela
**Middle East**🇦🇲 Armenia🇦🇿 Azerbaijan🇧🇭 Bahrain🇬🇪 Georgia🇮🇱 Israel🇯🇴 Jordan🇰🇼 Kuwait🇴🇲 Oman🇶🇦 Qatar🇸🇦 Saudi Arabia🇦🇪 United Arab Emirates🇾🇪 Yemen
**North America**🇧🇲 Bermuda🇨🇦 Canada🇬🇱 Greenland🇺🇸 United States
## Supported workflows and services
WorkflowSupported
Payrails SDK✔
Payrails API✔
[Delayed / Manual Capture](https://docs.payrails.com/docs/orchestration/payment-acceptance/capture-and-cancel-modes.md#capture-mode)✖
[Instant Capture](https://docs.payrails.com/docs/orchestration/payment-acceptance/capture-and-cancel-modes.md#capture-mode)✔
[Cancel / Void](https://docs.payrails.com/docs/orchestration/payment-acceptance/cancel-a-payment.md)✔
[Refund / Reverse](https://docs.payrails.com/docs/orchestration/payment-acceptance/refund-a-payment.md)✔
[Save Instruments](https://docs.payrails.com/docs/resources/manage-instruments.md)✔
[Merchant Initiated Transaction (MIT)](https://docs.payrails.com/docs/resources/payments/authorization-flags.md)✔
InteroperabilityPSP tokens
## PayPal billing agreement * Fraud SDKs ## Related topics - [PayPal](https://docs.payrails.com/docs/integrations/payment-providers/paypal.md) - [React Native SDK API Reference](https://docs.payrails.com/docs/sdks/react-native/api-references.md) - [PayPal Express](https://docs.payrails.com/docs/integrations/payment-methods/paypal/paypal-express-flow.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.