PayPal for Payments Setup API

Last updated: March 18, 2026

To accept PayPal payments, you must:

Create a payment setup.
Update the payment setup and initialize PayPal as a payment method.
Configure the PayPal SDK.
Verify payment authorization.
Confirm the payment.

Call the Create a payment setup endpoint.

Information

The Payment Setup API supports idempotency. 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.

post

https://{prefix}.api.checkout.com/payment-contexts


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "GBP",
4  "amount": 50,
5  "reference": "ORDER_01234",
6  "description": "PayPal payment",
7  "payment_type": "Regular",
8  "settings": {
9    "success_url": "https://example.com/success",
10    "failure_url": "https://example.com/failure"
11  },
12  "customer": {
13    "email": {
14      "address": "hannah.bret@example.com"
15    },
16    "phone": {
17      "country_code": "+44",
18      "number": "1234567890"
19    },
20    "device": {
21      "locale": "en-GB"
22    }
23  },
24  "order": {
25    "shipping": {
26      "address": {
27        "address_line1": "123 High St.",
28        "city": "London",
29        "zip": "SW1A 1AA",
30        "country": "GB"
31      },
32      "method": "string"
33    },
34    "items": [
35      {
36        "name": "Test Product",
37        "quantity": 1,
38        "unit_price": 5000,
39        "total_amount": 5000,
40        "reference": "ITEM-001"
41      }
42    ]
43  }
44}

In the request body, provide the following:

processing_channel_id – The processing channel's unique identifier
amount – The payment amount
currency – The payment currency


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 50,
5  "currency": "GBP",
6  "payment_type": "Regular",
7  "reference": "ORDER_01234",
8  "description": "PayPal payment",
9  "payment_methods": {
10    "paypal": {
11      "initialization": "disabled",
12      "status": "available",
13      "flags": [
14        "initialization_not_enabled"
15      ]
16    }
17  },
18  "available_payment_methods": [
19    "paypal"
20  ],
21  "settings": {
22    "success_url": "https://example.com/success",
23    "failure_url": "https://example.com/failure"
24  },
25  "customer": {
26    "email": {
27      "address": "hannah.bret@example.com"
28    },
29    "phone": {
30      "country_code": "+44",
31      "number": "1234567890"
32    },
33    "device": {
34      "locale": "en-GB"
35    }
36  },
37  "order": {
38    "shipping": {
39      "address": {
40        "address_line1": "123 High St.",
41        "city": "London",
42        "zip": "SW1A 1AA",
43        "country": "GB"
44      },
45      "method": "string"
46    },
47    "items": [
48      {
49        "name": "Test Product",
50        "quantity": 1,
51        "unit_price": 5000,
52        "total_amount": 5000,
53        "reference": "ITEM-001"
54      }
55    ]
56  }
57}

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.
flags - An array of error codes or indicators that highlight missing or invalid information.

When the customer selects PayPal as the payment method on the checkout page, you must update the payment setup to:

Initialize the payment method.
Provide PayPal-specific configuration values.

Call the Update a payment setup endpoint, setting payment_methods.paypal.initialization to enabled.

Additionally, provide the following fields:

Field Description

Field	Description
`amount` number	The payment amount, in the minor currency unit. Minimum: 1 Required
`currency` string	Three-letter ISO 4217 currency code. 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

amount

number

The payment amount, in the minor currency unit.
Minimum: 1
Required

currency

string

Three-letter ISO 4217 currency code.
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:

industry.airline_data[].flight_leg_details[].fare_basis_code

string

The fare basis code of that leg.
Min length: 1
Max length: 15


1{
2  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
3  "currency": "GBP",
4  "amount": 50,
5  "description": "PayPal payment",
6  "reference": "ORDER_01234",
7  "payment_type": "Regular",
8  "settings": {
9    "success_url": "https://example.com/success",
10    "failure_url": "https://example.com/failure"
11  },
12  "payment_methods": {
13    "paypal": {
14      "initialization": "enabled",
15      "user_action": "pay_now",
16      "brand_name": "Test Store",
17      "shipping_preference": "no_shipping"
18    }
19  },
20  "customer": {
21    "email": {
22      "address": "hannah.bret@example.com"
23    },
24    "phone": {
25      "country_code": "+44",
26      "number": "1234567890"
27    },
28    "device": {
29      "locale": "en-GB"
30    }
31  },
32  "order": {
33    "shipping": {
34      "address": {
35        "address_line1": "123 High St.",
36        "city": "London",
37        "zip": "SW1A 1AA",
38        "country": "GB"
39      },
40      "method": "string"
41    },
42    "items": [
43      {
44        "name": "Test Product",
45        "quantity": 1,
46        "unit_price": 5000,
47        "total_amount": 5000,
48        "reference": "ITEM-001"
49      }
50    ]
51  }
52}


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 50,
5  "currency": "GBP",
6  "payment_type": "Regular",
7  "reference": "ORDER_01234",
8  "description": "PayPal payment",
9  "payment_methods": {
10    "paypal": {
11      "initialization": "enabled",
12      "user_action": "pay_now",
13      "brand_name": "Test Store",
14      "shipping_preference": "no_shipping",
15      "action": {
16        "type": "sdk",
17        "order_id": "63P225977L978682N"
18      },
19      "status": "action_required",
20      "flags": []
21    }
22  },
23  "available_payment_methods": [
24    "paypal"
25  ],
26  "settings": {
27    "success_url": "https://example.com/success",
28    "failure_url": "https://example.com/failure"
29  },
30  "customer": {
31    "email": {
32      "address": "test@example.com"
33    },
34    "phone": {
35      "country_code": "+44",
36      "number": "1234567890"
37    },
38    "device": {
39      "locale": "en-GB"
40    }
41  },
42  "order": {
43    "shipping": {
44      "address": {
45        "address_line1": "123 High St.",
46        "city": "London",
47        "zip": "SW1A 1AA",
48        "country": "GB"
49      },
50      "method": "string"
51    },
52    "items": [
53      {
54        "name": "Test Product",
55        "quantity": 1,
56        "unit_price": 5000,
57        "total_amount": 5000,
58        "reference": "ITEM-001"
59      }
60    ]
61  }
62}

The response indicates an action_required status and returns payment_methods.paypal.action.order_id, which you use in 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.

After the customer confirms the payment in the PayPal widget, the payment method status changes to ready.

Call the Get a payment setup endpoint, setting the id of the payment setup as the id path parameter, to check the status before confirming.

post

https://{prefix}.api.checkout.com/payments/setups/{id}


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 50,
5  "currency": "GBP",
6  "payment_type": "Regular",
7  "reference": "ORDER_01234",
8  "description": "PayPal payment",
9  "payment_methods": {
10    "paypal": {
11      "initialization": "enabled",
12      "user_action": "pay_now",
13      "brand_name": "Test Store",
14      "shipping_preference": "no_shipping",
15      "status": "ready",
16      "flags": []
17    }
18  },
19  "available_payment_methods": [
20    "paypal"
21  ],
22  "settings": {
23    "success_url": "https://example.com/success",
24    "failure_url": "https://example.com/failure"
25  },
26  "customer": {
27    "email": {
28      "address": "hannah.bret@example.com"
29    },
30    "phone": {
31      "country_code": "+44",
32      "number": "1234567890"
33    },
34    "device": {
35      "locale": "en-GB"
36    }
37  },
38  "order": {
39    "shipping": {
40      "address": {
41        "address_line1": "123 High St.",
42        "city": "London",
43        "zip": "SW1A 1AA",
44        "country": "GB"
45      },
46      "method": "string"
47    },
48    "items": [
49      {
50        "name": "Test Product",
51        "quantity": 1,
52        "unit_price": 5000,
53        "total_amount": 5000,
54        "reference": "ITEM-001"
55      }
56    ]
57  }
58}

When the payment status changes to ready, confirm the payment by calling the Confirm a payment setup endpoint and provide:

The payment setup id as the {id} path parameter.
paypal as the payment method name.

post

https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/paypal

PayPal for Payments Setup API

Create a payment setup

Information

Information

Request example

Response example

Update the payment setup

Request example

Response example

Configure the PayPal SDK

Verify payment authorization

Response example