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": 112}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": 112}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": 116}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": 113}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": 200033}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": 1003}
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 |
---|---|
| Sent when a payment request has been successfully initiated. |
| Sent when a payment request has been rejected. |
| Sent when a payment reaches its expiry date without being captured. |
| Sent when a full or partial payment refund has been accepted. |
| Sent when the payment has been successfully captured. |
| Occurs when an authorized payment is canceled by the payment method. |
| Sent when the refund of the payment has been (fully or partially) accepted. |
| Sent when the payment has been (fully or partially) refunded. |
| Sent when a refund has been declined. |
The following webhooks apply to Express Checkout payments:
Webhook | Description |
---|---|
| Sent when a payment request has been successfully initiated. |
| Sent when a payment is successfully authorized. |
| Send when a payment is approved by the merchant. |
| Sent when the payment has been successfully captured. |
| Sent when a payment request has been rejected. |
| Sent when a payment is voided after authorization or partial capture, or if the payment has expired. |
| Sent when an authorized payment reaches its expiry date without being captured. |
| 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.