# PayPal for Payment Setup API
To accept PayPal payments, you must:
1. Create a payment setup.
2. Update the payment setup and initialize PayPal as a payment method.
3. Configure the PayPal SDK.
4. Verify payment authorization.
5. Confirm the payment.
---
## Create a payment setup
Call the [Create a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/createAPaymentSetup) endpoint.
> **Information**
>
> The Payment Setup API supports [idempotency](https://www.checkout.com/docs/developer-resources/api/idempotency.md). You can safely retry API requests without the risk of duplicate requests.
> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Live**
`POST` `https://{prefix}.api.checkout.com/payments/setups`
**Sandbox**
`POST` `https://{prefix}.api.sandbox.checkout.com/payments/setups`
### Request example
```json
{
"processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
"currency": "GBP",
"amount": 50,
"reference": "ORDER_01234",
"description": "PayPal payment",
"payment_type": "Regular",
"settings": {
"success_url": "https://example.com/success",
"failure_url": "https://example.com/failure"
},
"customer": {
"email": {
"address": "hannah.bret@example.com"
},
"phone": {
"country_code": "+44",
"number": "1234567890"
},
"device": {
"locale": "en-GB"
}
},
"order": {
"shipping": {
"address": {
"address_line1": "123 High St.",
"city": "London",
"zip": "SW1A 1AA",
"country": "GB"
},
"method": "string"
},
"items": [
{
"name": "Test Product",
"quantity": 1,
"unit_price": 5000,
"total_amount": 5000,
"reference": "ITEM-001"
}
]
}
}
```
In the request body, provide the following:
- `processing_channel_id` – The [processing channel's](https://www.checkout.com/docs/business-operations/use-the-dashboard/manage-processing-channels.md) unique identifier
- `amount` – The payment amount
- `currency` – The payment currency
### Response example
```json
{
"id": "set_rcmepwrchqab2wsergcafvijfy",
"processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
"amount": 50,
"currency": "GBP",
"payment_type": "Regular",
"reference": "ORDER_01234",
"description": "PayPal payment",
"payment_methods": {
"paypal": {
"initialization": "disabled",
"status": "initialization_required",
"flags": []
}
},
"available_payment_methods": [
"paypal"
],
"settings": {
"success_url": "https://example.com/success",
"failure_url": "https://example.com/failure"
},
"customer": {
"email": {
"address": "hannah.bret@example.com"
},
"phone": {
"country_code": "+44",
"number": "1234567890"
},
"device": {
"locale": "en-GB"
}
},
"order": {
"shipping": {
"address": {
"address_line1": "123 High St.",
"city": "London",
"zip": "SW1A 1AA",
"country": "GB"
},
"method": "string"
},
"items": [
{
"name": "Test Product",
"quantity": 1,
"unit_price": 5000,
"total_amount": 5000,
"reference": "ITEM-001"
}
]
}
}
```
The response returns a `payment_methods` object, which contains the payment methods enabled on your account.
For PayPal, `payment_methods` contains the following fields:
- `initialization` - The initialization status of the payment method, which can be either `enabled` or `disabled`.
- `status` - The [status of the payment method](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payment-setup-api#Payment_method_status).
- `flags` - An array of error codes or indicators that highlight missing or invalid information.
---
## Update the payment setup
When the customer selects PayPal as the payment method on the checkout page, you must update the payment setup to:
1. Initialize the payment method.
2. Provide PayPal-specific configuration values.
Call the [Update a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/updateAPaymentSetup) endpoint, setting `payment_methods.paypal.initialization` to `enabled`.
Additionally, provide the following fields:
| Field | Description |
| --- | --- |
| `amount`
`number` | The payment amount, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value).
Minimum: 1
**Required** |
| `currency`
`string` | Three-letter ISO 4217 [currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes.md).
**Required** |
| `reference`
`string` | The payment reference.
Max length: 80 characters |
| `settings.success_url`
`string` | The URL to redirect the customer after a successful authorization.
Format: uri
**Required** |
| `settings.failure_url`
`string` | The URL to redirect the customer after a failed authorization.
Format: uri
**Required** |
| `customer.device.locale`
`string` | The customer locale.
Min length: 2
Max length: 10
Pattern: `^[a-z]{2}(?:-[A-Z]{3})?(?:-(?:[A-Z]{2}))?$`
For example: `en-GB` |
| `order.invoice_id`
`string` | The invoice ID.
Max length: 127 |
| `order.items[]`
`array[object]` | An array of order line items.
Min items: 1
**Required** |
| `order.items[].name`
`string` | The descriptive item name.
Min length: 1, Max length: 127
**Required** |
| `order.items[].unit_price`
`number` | The item unit price.
Minimum: 0
**Required** |
| `order.items[].quantity`
`integer` | The item quantity.
Minimum: 0, Maximum: 999
**Required** |
| `order.shipping`
`object` | The shipping object.
`order.shipping.address` is required when the order is sent. |
| `order.shipping.first_name`
`string` | The recipient first name.
Max length: 300 |
| `order.shipping.last_name`
`string` | The recipient last name.
Max length: 300 |
| `order.shipping.amount`
`number` | The shipping amount. |
| `order.shipping.address.address_line1`
`string` | Required when `order.shipping.address` is provided.
Min length: 1
Max length: 300
**Conditional** |
| `order.shipping.address.address_line2`
`string` | And additional address line, if necessary.
Max length: 300 |
| `order.shipping.address.city`
`string` | The shipping city.
Max length: 120 |
| `order.shipping.address.state`
`string` | The shipping state or region.
Max length: 300 |
| `order.shipping.address.zip`
`string` | The shipping postal code.
Max length: 60 |
| `order.shipping.address.country`
`string` | Required when `order.shipping.address` is provided.
Min length: 2, Max length: 2
Pattern: `^[A-Z]{2}$`
**Conditional** |
| `payment_methods.paypal.initialization`
`string` | Set to `enabled` to initialize PayPal.
**Required** |
| `payment_methods.paypal.user_action`
`string` | Supported values:
- `pay_now` – for the Pay Now checkout experience
- `continue` – for the Continue checkout experience |
| `payment_methods.paypal.brand_name`
`string` | The brand name shown in the PayPal checkout experience.
Max length: 127 |
| `payment_methods.paypal.shipping_preference`
`string` | Supported values:
-`no_shipping`
- `get_from_file`
- `set_provided_address` |
| `industry.airline_data[]`
`array[object]` | The airline specific data, if applicable. |
| `industry.airline_data[].ticket.number`
`string` | The ticket number, if applicable.
Min length: 1
Max length: 16 |
| `industry.airline_data[].ticket.issue_date`
`string` | The airline ticket issue date, if applicable.
Format: date |
| `industry.airline_data[].ticket.issuing_carrier_code`
`string` | The airline issuing carrier code, if applicable.
Min length: 2
Max length: 2
Pattern: `^[A-Z0-9]{2}$` |
| `industry.airline_data[].ticket.travel_agency_name`
`string` | The airline travel agency name, if applicable.
Min length: 1
Max length: 25 |
| `industry.airline_data[].ticket.travel_agency_code`
`string` | The airline travel agency code, if applicable.
Min length: 1
Max length: 8 |
| `industry.airline_data[].passenger[]`
`array[object]` | The passenger object. Required for each passenger.
Min items: 1 |
| `industry.airline_data[].passenger[].first_name`
`string` | The passenger first name.
Min length: 1, Max length: 300
**Conditional** |
| `industry.airline_data[].passenger[].last_name`
`string` | The passenger last name.
Min length: 1, Max length: 300
**Conditional** |
| `industry.airline_data[].passenger[].date_of_birth`
`string` | The passenger date of birth.
Format: date |
| `industry.airline_data[].passenger[].address.country`
`string` | The passenger's country.
Pattern: `^([A-Z]{2}\|C2)$` |
| `industry.airline_data[].flight_leg_details[]`
`array[object]` | The flight leg details object. Required for each leg of the journey.
Min items: 1 |
| `industry.airline_data[].flight_leg_details[].flight_number`
`integer` | The flight number of that leg. |
| `industry.airline_data[].flight_leg_details[].carrier_code`
`string` | The carrier code of that leg.
Min length: 2, Max length: 2
Pattern: `^[A-Z0-9]{2}$` |
| `industry.airline_data[].flight_leg_details[].class_of_travelling`
`string` | The class of travelling of that leg.
Min length: 1
Max length: 1
Pattern: `^[A-Z]{1}$` |
| `industry.airline_data[].flight_leg_details[].departure_date`
`string` | The flight departure date of that leg.
Format: date |
| `industry.airline_data[].flight_leg_details[].departure_time`
`string` | The flight departure time of that leg.
Min length: 5
Max length: 5
Pattern: `^\\d{2}:\\d{2}$` |
| `industry.airline_data[].flight_leg_details[].departure_airport`
`string` | The departure airport of that leg.
Min length: 3, Max length: 4
Pattern: `^[A-Z]{3,4}$`
**Conditional** |
| `industry.airline_data[].flight_leg_details[].arrival_airport`
`string` | The flight arrival airport of that leg.
Min length: 3, Max length: 4
Pattern: `^[A-Z]{3,4}$`
**Conditional** |
| `industry.airline_data[].flight_leg_details[].stop_over_code`
`string` | The stop over code of that leg.
Supported values:
- `O`
- `X` |
| `industry.airline_data[].flight_leg_details[].fare_basis_code`
`string` | The fare basis code of that leg.
Min length: 1
Max length: 15 |
### Request example
```json
{
"processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
"currency": "GBP",
"amount": 50,
"description": "PayPal payment",
"reference": "ORDER_01234",
"payment_type": "Regular",
"settings": {
"success_url": "https://example.com/success",
"failure_url": "https://example.com/failure"
},
"payment_methods": {
"paypal": {
"initialization": "enabled",
"user_action": "pay_now",
"brand_name": "Test Store",
"shipping_preference": "no_shipping"
}
},
"customer": {
"email": {
"address": "hannah.bret@example.com"
},
"phone": {
"country_code": "+44",
"number": "1234567890"
},
"device": {
"locale": "en-GB"
}
},
"order": {
"shipping": {
"address": {
"address_line1": "123 High St.",
"city": "London",
"zip": "SW1A 1AA",
"country": "GB"
},
"method": "string"
},
"items": [
{
"name": "Test Product",
"quantity": 1,
"unit_price": 5000,
"total_amount": 5000,
"reference": "ITEM-001"
}
]
}
}
```
### Response example
```json
{
"id": "set_rcmepwrchqab2wsergcafvijfy",
"processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
"amount": 50,
"currency": "GBP",
"payment_type": "Regular",
"reference": "ORDER_01234",
"description": "PayPal payment",
"payment_methods": {
"paypal": {
"initialization": "enabled",
"user_action": "pay_now",
"brand_name": "Test Store",
"shipping_preference": "no_shipping",
"action": {
"type": "sdk",
"order_id": "63P225977L978682N"
},
"status": "action_required",
"flags": []
}
},
"available_payment_methods": [
"paypal"
],
"settings": {
"success_url": "https://example.com/success",
"failure_url": "https://example.com/failure"
},
"customer": {
"email": {
"address": "test@example.com"
},
"phone": {
"country_code": "+44",
"number": "1234567890"
},
"device": {
"locale": "en-GB"
}
},
"order": {
"shipping": {
"address": {
"address_line1": "123 High St.",
"city": "London",
"zip": "SW1A 1AA",
"country": "GB"
},
"method": "string"
},
"items": [
{
"name": "Test Product",
"quantity": 1,
"unit_price": 5000,
"total_amount": 5000,
"reference": "ITEM-001"
}
]
}
}
```
The response indicates an `action_required` status and returns `payment_methods.paypal.action.order_id`, which you use in the PayPal SDK.
---
## Configure the PayPal SDK
Use `payment_methods.paypal.action.order_id` from the update response to initialize and render PayPal in your checkout page. Then, the customer confirms the payment using the PayPal widget.
---
## Verify payment authorization
After the customer confirms the payment in the PayPal widget, the payment method status changes to `ready`.
Call the [Get a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/getAPaymentSetup) endpoint, setting the `id` of the payment setup as the `id` path parameter, to check the status before confirming.
**Live**
`POST` `https://{prefix}.api.checkout.com/payments/setups/{id}`
**Sandbox**
`POST` `https://{prefix}.api.sandbox.checkout.com/payments/setups/{id}`
### Response example
```json
{
"id": "set_rcmepwrchqab2wsergcafvijfy",
"processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
"amount": 50,
"currency": "GBP",
"payment_type": "Regular",
"reference": "ORDER_01234",
"description": "PayPal payment",
"payment_methods": {
"paypal": {
"initialization": "enabled",
"user_action": "pay_now",
"brand_name": "Test Store",
"shipping_preference": "no_shipping",
"status": "ready",
"flags": []
}
},
"available_payment_methods": [
"paypal"
],
"settings": {
"success_url": "https://example.com/success",
"failure_url": "https://example.com/failure"
},
"customer": {
"email": {
"address": "hannah.bret@example.com"
},
"phone": {
"country_code": "+44",
"number": "1234567890"
},
"device": {
"locale": "en-GB"
}
},
"order": {
"shipping": {
"address": {
"address_line1": "123 High St.",
"city": "London",
"zip": "SW1A 1AA",
"country": "GB"
},
"method": "string"
},
"items": [
{
"name": "Test Product",
"quantity": 1,
"unit_price": 5000,
"total_amount": 5000,
"reference": "ITEM-001"
}
]
}
}
```
---
When the payment status changes to `ready`, confirm the payment by calling the [Confirm a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/confirmAPaymentSetup) endpoint and provide:
- The payment setup `id` as the `{id}` path parameter.
- `paypal` as the `{payment_method_name}` path parameter.
**Live**
`POST` `https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/paypal`
**Sandbox**
`POST` `https://{prefix}.api.sandbox.checkout.com/payments/setups/{id}/confirm/paypal`