PayPal
Beta

Last updated: July 20, 2022

Start accepting PayPal payments. Our solution supports 2 integration types depending on the channel used:

Redirect payment flow
PayPal Smart Payment Button that you can include in your payment form. It is available in all countries and on all web browsers supported by PayPal.

Information

To start accepting PayPal payments, please contact your Customer Success Manager.

Model	Gateway
Payment flow	Redirect and Direct
Payment method type	Wallet
One-step payment
Separate capture	Payments are captured immediately after authorization by default.
Refund
Partial refund
Disputes	All disputes are handled directly via PayPal.
Chargeback	All chargebacks are handled directly via PayPal.
Recurring payment

The PayPal redirect payment flow follows a two-step process:

Use the details below to set up your request. To get a detailed view of all required and optional fields, see our API reference.

post

https://api.checkout.com/payments


1{
2  "source": {
3    "type": "paypal"
4  },
5  "currency": "USD",
6  "amount": 2000,
7  "items": [
8    {
9      "name": "laptop",
10      "unit_price": 2000,
11      "quantity": 1
12    }
13  ],
14  "processing_channel_id": "{{NAS-processingChannel-personal}}",
15  "success_url": "https://example.com/payments/success",
16  "failure_url": "https://example.com/payments/failure"
17}

If you receive a 202 Accepted response with a status field set to Pending, your request was successful.


1{
2  "id": "pay_wppxkyg3hx4ujguxecqg2qdsoi",
3  "status": "Pending",
4  "processing": {
5    "order_id": "5PW63543DN0351914"
6  },
7  "_links": {
8    "self": {
9      "href": "https://api.sandbox.checkout.com/payments/pay_wppxkyg3hx4ujguxecqg2qdsoi"
10    },
11    "redirect": {
12      "href": "https://www.sandbox.paypal.com/checkoutnow?token=5PW63543DN0351914"
13    }
14  }
15}

Redirect your customer to the link under redirect in the response. The customer is redirected to a PayPal page where they can authorize the payment. They are then transferred to your predefined success or failure URL.

PayPal Smart Payment Button requires immediate capture. Before implementing it, you must complete the onboarding to the Checkout.com platform and configure the PayPal checkout feature.

Contact your Customer Success Manager to receive the client ID (client_id) required in the request headers. You can find more information in the PayPal JavaScript configuration guide.

The PayPal Smart Payment Button flow follows a 2-step process:

Request a PayPal payment
Pass the order_id in the PayPal JavaScript SDK

Configure and customize your integration by passing query and script parameters in the JavaScript SDK script. These parameters personalize your setup and help PayPal select the optimal funding sources and buttons displayed to your customers.

The PayPal JavaScript SDK is loaded from https://www.paypal.com/sdk/js on the payment page, and no local version is used.

You can customize the layout of the PayPal Smart Payment Buttons. Configure the style element in the PayPal payment method configuration using the available style options.

We currently only support the direct payment experience using the payment button. Support for different payment types such as PayPal Credit will be available soon.

With PayPal Express Checkout, you can speed up the checkout process on your site by prompting customers to log in to their PayPal account to confirm a purchase.

As a merchant, this means that you can authorize the payment to place a hold on the funds before the transaction is finalized, and capture it later.

To get a detailed view of all required and optional fields, see our API reference.

post

https://api.checkout.com/payments/


1{
2  "source": {
3    "type": "paypal"
4  },
5  "currency": "USD",
6  "amount": 2000,
7  "items": [
8    {
9      "name": "laptop",
10      "unit_price": 2000,
11      "quantity": 1
12    }
13  ],
14  "processing_channel_id": "{{NAS-processingChannel-personal}}",
15  "success_url": "https://example.com/payments/success",
16  "failure_url": "https://example.com/payments/failure",
17  "payment_type": "regular",
18  "capture": "false"
19}

If you receive a 202 Success response with a payment id and a status field set to Pending, your request was successful.


1{
2  "id": "pay_rtrxbqyk52sunbxboe5n6sqeya",
3  "status": "Pending",
4  "processing": {
5    "order_id": "94M87628HP693400G"
6  },
7  "_links": {
8    "self": {
9      "href": "http://gwc.ckotech.co/gateway/payments/pay_rtrxbqyk52sunbxboe5n6sqeya"
10    },
11    "redirect": {
12      "href": "https://www.sandbox.paypal.com/checkoutnow?token=94M87628HP693400G"
13    }
14  }
15}

Redirect your customer to the redirect link’s href in the response. This will allow the customer to authorize the payment, before they are transferred to your predefined success or failure URL.

Payment authorization can take up to 10 minutes after the payment is initially accepted.

Once authorized, the payment can be captured.

post

https://api.checkout.com/payments/{id}/captures


1{
2  "source": {
3    "type": "paypal"
4  },
5  "amount": 2000,
6  "capture_type": "final"
7}

If you receive a 202 Success response, your request was successful.


1{
2  "action_id": "act_ffbpdzoo22runamstvrrtvprnu",
3  "_links": {
4    "payment": {
5      "href": "http://gwc.ckotech.co/gateway/payments/pay_3lojq775dp7efhzk4gv7strfz4"
6    }
7  }
8}


1{
2  "source": {
3    "type": "paypal"
4  },
5  "amount": 1000,
6  "capture_type": "NonFinal"
7}

If you receive a 202 Success response, your request was successful.


1{
2  "action_id": "act_kzhwv2qhjaoevgpglevkeiizdq",
3  "_links": {
4    "payment": {
5      "href": "http://gwc.ckotech.co/gateway/payments/pay_klwax7oqjfdu7dnlhfebb66i3y"
6    }
7  }
8}

To request a recurring payment, your payment request should include the following fields.

plan.type set to "MERCHANT_INITIATED_BILLING"
payment_type set to "recurring"

In order to allow recurring payments, there needs to be a billing agreement established with PayPal. We do this by sending an initial request and using the redirect URL provided in the initial response.

To get a detailed view of all required and optional fields, see our API reference.

post

https://api.checkout.com/payments/


1{
2  "source": {
3    "type": "paypal",
4    "plan": {
5      "type": "MERCHANT_INITIATED_BILLING"
6    }
7  },
8  "payment_type": "recurring",
9  "currency": "USD",
10  "amount": 2000,
11  "items": [
12    {
13      "name": "laptop",
14      "unit_price": 2000,
15      "quantity": 1
16    }
17  ],
18  "processing_channel_id": "pc_ekaubqrravqupfxde7kxvd2t3i"
19}

If you receive a 202 Success response with a payment id and a status field set to Pending, your request was successful.


1{
2  "id": "pay_ygiek2asp6dutdk5lzshdsalh4",
3  "status": "Pending",
4  "source": {
5    "id": "src_nblewnknheyxsyspiy4gm6copi",
6    "type": "paypal"
7  },
8  "_links": {
9    "self": {
10      "href": "https://api.checkout.com/payments/pay_ygiek2asp6dutdk5lzshdsalh4"
11    },
12    "redirect": {
13      "href": "https://www.sandbox.paypal.com/agreements/approve?ba_token=BA-3XH04039WX2586748"
14    }
15  }
16}

For subsequent payment requests, take the customer to the redirect URL provided in the initial response, where they can accept the billing agreement.

Before requesting a subsequent payment in the recurring series, the first payment needs to be successfully captured.


1{
2  "source": {
3    "type": "id",
4    "id": "{{instrument_id}}"
5  },
6  "currency": "USD",
7  "amount": 2000,
8  "items": [
9    {
10      "name": "laptop",
11      "unit_price": 2000,
12      "quantity": 1
13    }
14  ],
15  "processing_channel_id": "{{NAS-processingChannel-personal}}",
16  "success_url": "https://example.com/payments/success",
17  "failure_url": "https://example.com/payments/failure",
18  "payment_type": "recurring"
19}

If you receive a 202 Success response with a payment id and a status field set to Pending, your request was successful.


1{
2  "id": "pay_nglcin3mv2bexgf3czygeoq5ty",
3  "status": "Pending",
4  "source": {
5    "id": "src_kfwecr3gjzbfctdbobiwi2dcka",
6    "type": "paypal"
7  },
8  "processing": {
9    "order_id": "1P682271WG2976509"
10  },
11  "_links": {
12    "self": {
13      "href": "https://api.checkout.com/payments/pay_nglcin3mv2bexgf3czygeoq5ty"
14    }
15  }
16}

You can use the payment id in the payment response, or the cko-session-id in the success/failure URL to retrieve details about the payment. For example, https://www/checkout.com/order/succeeded?cko-session-id=sid_vii64oquze5u3h2x6hh4rurc4y.

To get a detailed view of all required and optional fields, see our API reference.

get

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


1{
2  "id": "pay_ykxmuzebtj3ujjlbnb6cks4emy",
3  "requested_on": "2022-02-15T15:26:11.3538099Z",
4  "source": {
5    "type": "paypal"
6  },
7  "amount": 2000,
8  "currency": "USD",
9  "payment_type": "Regular",
10  "customer": {
11    "id": "cus_maogovyg5idubpp3hmi7ayesn4",
12    "email": "john.smith@example.com"
13  },
14  "shipping": {
15    "address": {
16      "address_line1": "123 Anywhere St.",
17      "address_line2": "Apt. 456",
18      "city": "Anytown",
19      "state": "AL",
20      "zip": "123456",
21      "country": "US"
22    }
23  },
24  "status": "Pending",
25  "processing": {
26    "order_id": "0C438986FY9797333"
27  },
28  "items": [
29    {
30      "name": "laptop",
31      "quantity": 1,
32      "unit_price": 2000
33    }
34  ],
35  "_links": {
36    "redirect": {
37      "href": "https://www.sandbox.paypal.com/checkoutnow?token=0C438986FY9797333"
38    },
39    "self": {
40      "href": "https://api.sandbox.checkout.com/payments/pay_ykxmuzebtj3ujjlbnb6cks4emy"
41    },
42    "actions": {
43      "href": "https://api.sandbox.checkout.com/payments/pay_ykxmuzebtj3ujjlbnb6cks4emy/actions"
44    }
45  }
46}

You can process a refund through the Dashboard or using the refund API. However, there is no chargeback or dispute mechanism available for PayPal.

To get a detailed view of all required and optional fields, see our API reference.

post

https://api.checkout.com/payments/{id}/refunds


1{
2  "amount": 100
3}


1{
2  "action_id": "act_jf7fv3vgiu7ezjfgzvvsqobxru",
3  "_links": {
4    "payment": {
5      "href": "https://api.sandbox.checkout.com/payments/pay_fsud3hyoqkxencjvb5cfv6yqoe"
6    }
7  }
8}

Smart Button payments cannot be voided by the merchant once they have been created. If you wish to void a payment in progress, please wait for the payment_captured webhook, and then process a refund.

Customers may still cancel a payment themselves, which will cause the payment to expire and a payment_expired webhook to fire.

Express Checkout payments can be voided after authorization or a partial capture, or if the payment expires.

You may receive the following webhooks when using PayPal. View all of our webhook notifications.

Webhook	Description
`payment_created`	Sent when a payment request has been successfully initiated.
`payment_declined`	Sent when a payment request has been rejected.
`payment_expired`	Sent when a payment reaches its expiry date without being captured.
`payment_refund_pending`	Sent when a full or partial payment refund has been accepted.
`payment_captured`	Sent when the payment has been successfully captured.
`payment_canceled`	Occurs when an authorized payment is canceled by the payment method.
`payment_refund_accepted`	Sent when the refund of the payment has been (fully or partially) accepted.
`payment_refunded`	Sent when the payment has been (fully or partially) refunded.
`payment_refund_declined`	Sent when a refund has been declined.

The following webhooks apply to Express Checkout payments:

Webhook	Description
`payment_pending`	Sent when a payment request has been successfully initiated.
`payment_authorized`	Sent when a payment is successfully authorized.
`payment_approved`	Send when a payment is approved by the merchant.
`payment_captured`	Sent when the payment has been successfully captured.
`payment_capture_declined`	Sent when a payment request has been rejected.
`payment_voided`	Sent when a payment is voided after authorization or partial capture, or if the payment has expired.
`payment_expired`	Sent when an authorized payment reaches its expiry date without being captured.
`payment_void_declined`	Sent when a void request is declined.

To start testing, contact your Customer Success Manager or Implementation Engineer to activate PayPal payments in the sandbox environment.

Create a PayPal transaction as above, following the redirect link in the response to PayPal's website.
Sign in to your PayPal customer account using your PayPal username and password.
Confirm the payment.
You are then redirected to your predefined success URL.

To start testing payments, follow the steps below:

Create a PayPal developer account, if you don't already have one.
In your developer account, create PayPal business and personal sandbox accounts and a PayPal sandbox environment.

You can find a list of your test payments in your PayPal sandbox accounts.

You can find more information in the PayPal sandbox testing guide.

Account type	Description	Usage
Developer	PayPal developer account.	Access to the PayPal developer dashboard, creating and managing Business and Personal sandbox accounts.
Business	PayPal sandbox Business account. For example, @business.example.com	Adding PayPal as a payment method in your test Customer Area, providing the Merchant ID and email address of this account.
Personal	PayPal sandbox Personal account. For example, @personal.example.com	Testing payments from a consumer experience perspective.

Granting third-party permissions to Checkout.com is required to connect your PayPal account to your Checkout.com integration. Follow the below steps to grant permissions for each type of environment.

Sign in to your PayPal test store using the Business test account details.
Retrieve your merchant_id and share it with your Customer Success Manager.
Follow PayPal's instructions on granting third-party permissions.
On the Permissions page, select the following checkboxes:
- Use Express Checkout to process payments
- Issue a refund for a specific transaction
- Process your shopper's credit or debit card payments
- Authorize and capture your PayPal transactions
- Obtain information about a single transaction
- Obtain authorization for pre-approved payments and initiate pre-approved transactions
- Generate consolidated reports for all accounts (if this is available in your region)
- Use Express Checkout to process mobile payments (if you plan to support mobile payments)
If you're using PayPal for recurring payments, also select the following checkboxes:
- Charge an existing customer based on a prior transaction
- Create and manage Recurring Payments

Your PayPal merchant ID is generated when you create your sandbox and live PayPal Business accounts. It consists of 13 randomly generated alphanumeric characters. Follow the below steps to retrieve your merchant ID for each type of environment.

Sign in to PayPal using your sandbox Business account details.
Go to Profile and select Account Settings.
In the Business profile section, select Business information.
Copy your PayPal merchant ID.

PayPal Seller Protection only applies to physical goods.

If you participate in the PayPal Seller Protection program, include the following fields in your payment requests:

deliveryAddress
shopperName

Contact your PayPal partner to find out which additional parameters you should include in the payment request.

We recommend checking that your setup is working properly, and you can successfully perform test payments.

Contact your Customer Success Manager to ensure the test payment is eligible for PayPal Seller Protection. This information is displayed in the transaction details.

We've made some changes to our API

PayPal
Beta

Information

Redirect payment flow

Request a payment

Request example

Response example

Redirect the customer

PayPal Smart Payment Button

PayPal Express Checkout

Request example

Response example

Redirect the customer

Capture the payment

Full capture example request

Full capture example response

Partial capture example request

Partial capture example response

Request a recurring payment

Initial request example

Initial response example

Set up subsequent requests

Subsequent request example

Subsequent response example

Get details about a payment

Response example

Refund a payment

Request example

Response example

Cancel a payment

Webhooks

Testing PayPal

Create developer and sandbox accounts

Required PayPal accounts for testing

Set up third-party API access on your PayPal account

Get your PayPal merchant ID

PayPal seller protection