PayPal
Last updated: March 13, 2024
PayPal enables customers to securely perform online payments, using any credit or debit card connected to their PayPal account.
Our PayPal integration supports the following checkout experiences:
- Pay Now: customers complete the payment on the PayPal pop-up
- Continue: customers complete the payment on the merchant's order review page
Information
To enable PayPal payments on your account, contact your Account Manager or [email protected].
Model | Gateway |
---|---|
Payment flow | Direct |
Auto capture | Payments are captured immediately after authorization by default. |
Manual capture | Full and Partial capture. |
Refund | Full and Partial capture. |
Disputes | All disputes are handled directly via PayPal. |
Chargeback | All chargebacks are handled directly via PayPal. |
Recurring payment |
The PayPal JavaScript SDK displays relevant, PayPal-supported payment methods on your checkout page. This provides customers with a personalized and streamlined checkout experience.
You can use the JavaScript SDK to:
- render buttons and payment method icons (marks)
- check the
funding-eligibility
of any given payment method
To integrate the PayPal JS SDK and open the PayPal pop-up, follow these steps:
Initialize the PayPal JS SDK by adding it in a
<script> src="https://www.paypal.com/sdk/js?client-id=ASLqLf4pnWuBshW8Qh8z_DRUbIv2Cgs3Ft8aauLm9Z-MO9FZx1INSo38nW109o_Xvu88P3tly88XbJMR&merchant-id={YOUR_PAYPAL_MERCHANT_ID}&disable-funding=credit,card,sepa&commit=false" data-partner-attribution-id="CheckoutLtd_PSP"</script>
tag:a.
merchant-id
- provided by Checkout.com during integration. Your PayPal Merchant ID is generated when you create your test and live PayPal Business accounts; it consists of 13 randomly generated alphanumeric characters.b.
data-partner-attribution-id
andclient-id
- depends on your sandbox or production environment as outlined in the Environment parameters section.
Information
Checkout.com only supports the direct PayPal payment experience. Support for payment types such as PayPal Credit, credit card payments, and others will be added. Therefore, please use the following URL query parameter for PayPal SDK to make sure that all unavailable payment options are not shown to customers (&disable-funding=credit,card,sepa
). By default, the JS SDK renders all eligible payment buttons.
Place a
<div id=”paypal-button-container”></div>
wrapper on your page where you want to render the PayPal button.Manage the order via the PayPal JS SDK:
a. Return the
order_id
from the context creation in thecreateOrder()
callback.b. Make a handler in the
onApprove()
callback that continues to the next steps in your back end.
1paypal2.Buttons({3createOrder() {4// your custom handler to return the order_id string5return getOrderId();6},7onApprove: async function (data) {8// your custom handler to continue after the user approval of the transaction9handlePaymentApproval();10},11})12.render('#paypal-button-container');
The PayPal Developer docs for PayPal JavaScript configuration provide additional information.
client-id
: “ATbi1ysGm-jp4RmmAFz1EWH4dFpPd-VdXIWWzR4QZK5LAvDu_5atDY9dsUEJcLS5mTpR8Wb1l_m6Ameq”data-partner-attribution-id
: “CheckoutLtd_PSP”
<script src="https://www.paypal.com/sdk/js?client-id=ASLqLf4pnWuBshW8Qh8z_DRUbIv2Cgs3Ft8aauLm9Z-MO9FZx1INSo38nW109o_Xvu88P3tly88XbJMR&merchant-id={YOUR_PAYPAL_MERCHANT_ID}&disable-funding=credit,card,sepa&commit=false" data-partner-attribution-id="CheckoutLtd_PSP">
PayPal supports both auto capture and manual capture payment flows:
- use auto capture if your goods and services are available immediately after purchase. For example, digital goods or tickets. Specify
"capture": true
in your payment context request. - use manual capture if your goods and services are not available immediately after purchase. For example, shipped goods. Specify
"capture": false
in your payment context request. When you instantiate the PayPal JS SDK, you must add the&intent=authorize
query parameter. If authorization is successful, you can capture the payment.
The exact steps required depends on whether you use PayPal's Pay Now or Continue payment experience.
- Pay Now: customers complete the payment on the PayPal page
- Continue: customers complete the payment on the merchant's order review page
- Request a Checkout.com payment context.
- Open the PayPal pop-up.
- Request a payment.
- Capture the payment, if you're using a manual capture payment flow.
- Request a Checkout.com payment context.
- Open the PayPal pop-up.
- Get the latest customer data from PayPal to create the review page.
- Request a payment.
- Capture the payment, if you're using a manual capture payment flow.
A Checkout.com payment context request will return an order_id
which is required when configuring subsequent requests.
To make it easier to reconcile the payment at a later date, include the following fields in your request:
reference
processing.invoice_id
post
https://api.checkout.com/payment-contexts
1{2"source": {3"type": "paypal"4},5"currency": "USD",6"amount": 2000,7"capture": false,8"items": [9{10"name": "laptop",11"unit_price": 2000,12"quantity": 113}14],15"processing_channel_id": "{{PayPal-processingChannel-personal}}",16"success_url": "http://www.example.com/success.html",17"failure_url": "http://www.example.com/failure.html"18}
You can find the full list, as well as complete request and response examples, in our API reference.
Pay Now
Set "user_action": "pay_now"
in the request and commit=true
in the JS script URL, to display a Complete purchase button in the flow.
When the customer clicks Complete purchase, payment is completed without any further action from the customer.
Use this flow if the final payment amount is already known when you initiate the checkout flow.
Continue
Set "user_action": " continue"
in the request and commit=false
in the JS script URL, so that the default flow redirects customers to the PayPal payment page.
This page displays a Continue to Review Order button which customers then click. As the merchant, you redirect the customer to a review page where you pull shipping address details from PayPal. Customers are able to edit their shipping address and/or adjust their shipping option and amount prior to submitting the order.
Use this flow when you present PayPal upfront for a faster checkout experience and higher conversion rates.
Information
If you do not specify the user_action
field in your request, the Continue payment flow will be used by default.
PayPal provides shipping configuration in the shipping_preference
field using the following possible values:
no_shipping
- Shipping does not have to be defined; usually for digital goods and services where no delivery is required.set_provided_address
- Uses the merchant-provided address; customer cannot change the address on the PayPal pages. Only if the merchant does not pass an address, the customer can choose the address on the PayPal pages.get_from_file
- This is the default value whereby you collect the shipping details from PayPal widget.
Information
For"shipping_preference": "set_provided_address"
the following fields are mandatory:
address_line1
country
If you receive a 201 Created
success status response code your request was successful, and in the response, you will receive an order ID in the partner_metadata
field. You should use this order ID in the PayPal SDK for the createOrder() method.
1{2"id": "pct_ckjrpk7vux4ejhghe6ssgkoy2y",3"partner_metadata": {4"order_id": "7YP86878G2990415D"5},6"_links": {7"self": {8"href": "https://api.checkout.com/payment-contexts/pct_ckjrpk7vux4ejhghe6ssgkoy2y"9}10}11}
For information on how to configure the PayPal pop-up, please see the Configure the front-end PayPal JavaScript SDK section.
Once the customer confirms payment in PayPal pop-up, you must call the payment context endpoint to retrieve the latest customer data which you then display on the Review Page.
In the next step, you may use updated information from the context as part of the payment request.
In the front end, once the customer confirms the payment in the PayPal pop-up, you can use the onApprove()
callback function to get information from the user’s session on PayPal’s side. The response will contain all fields required to create the payment.
get
https://api.checkout.com/payment-contexts/{id}
1{2"payment_request": {3"source": {4"type": "paypal"5},6"amount": 2000,7"currency": "USD",8"payment_type": "Regular",9"authorization_type": "Final",10"capture": false,11"customer": {12"name": "John Smith",13"email": "[email protected]"14},15"shipping": {16"first_name": "John Smith",17"address": {18"address_line1": "1 Main St",19"city": "San Jose",20"state": "CA",21"zip": "95131",22"country": "US"23}24},25"items": [26{27"name": "laptop",28"quantity": 1,29"unit_price": 200030}31],32"success_url": "http://www.example.com/success.html",33"failure_url": "http://www.example.com/failure.html",34"processing_channel_id": "pc_zmcw5ppbvr3ullkdlza6u4teoi"35},36"partner_metadata": {37"customer_id": "WDB9U9PV7Y2KY",38"order_id": "7YP86878G2990415D"39}40}
post
https://api.checkout.com/payments
In the final order review page the customer has the option to update the following details, which may affect the total payment amount:
- shipping address
- shipping method
If the customer does not make any changes, you can use the following request example:
1{2"payment_context_id":"pct_ckjrpk7vux4ejhghe6ssgkoy2y",3"processing_channel_id": "{{NAS-processingChannel-personal}}"4}
If the customer updates either of the shipping details, you must provide updated values in your payment request. Your request should only include the fields impacted by the customer's update to the shipping details. For example:
- the new
shipping.address
- the new
amount
, to reflect the change in shipping method or address
Your request was successful if you receive a 202 Success
response code which contains the status
field set to Pending
.
1{2"id": "pay_z7wmqrxtmkouzlhhvyxuc3ecxq",3"status": "Pending",4"customer": {5"id": "cus_qypaijolqf5enei2y5b5men32m",6"email": "[email protected]",7"name": "John Doe"8},9"processing": {10"partner_order_id": "7YP86878G2990415D"11},12"_links": {13"self": {14"href": "https://api.checkout.com/payments/pay_z7wmqrxtmkouzlhhvyxuc3ecxq"15}16}17}
The manual capture flow enables you to authorize a payment and then capture the payment later. Authorizing a payment places a hold on the customer’s funds and gives you time before finalizing the transaction. E.g. verifying if the item is still in stock.
Information
Manual capture should be triggered when you ship the items.
Our solution can perform full and multiple partial captures for the payment.
Information
- if the capture amount equals the authorized amount we will consider the capture final
- if the capture amount is less than the authorized amount, but you send a capture request with
capture_type
set tofinal
, we'll consider the capture final and release the remaining authorized amount. If you do not specify acapture_type
in your request,final
is used by default.
For more information on capturing a payment, see the Capture a Payment page.
If you want to use full capture, pass the payment_id
in the request.
post
https://api.checkout.com/payments/{id}/captures
Response example
If you receive a 202 Success
response containing, your request was successful.
1{2"action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",3"_links": {4"payment": {5"href": "https://api.sandbox.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"6}7}8}
If you want to perform multiple partial capture, pass "capture_type" : NonFinal
in the capture request.
You can also use "capture_type" : Final
.
post
https://api.checkout.com/payments/{id}/captures
Request example
1{2"amount": 1000,3"capture_type": "NonFinal"4}
Response example
If you receive a 202 Success
response containing the Action ID, your request was successful.
1{2"action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",3"_links": {4"payment": {5"href": "https://api.sandbox.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"6}7}8}
A billing agreement between you and PayPal is required to allow recurring payments.
The initial payment should be performed using the auto capture payment flow. The payment context requests must include the following fields and values:
capture
set totrue
payment_type
set torecurring
plan.type
set to one of the values from the following table:
| New agreement ID is issued for each onboarding customer. |
| Recommended as default. If an existing agreement is found, PayPal returns the same billing agreement id that was issued previously. Customers will not see multiple agreements with the same merchant. |
| Refers to partner hosted agreements. These are no longer allowed within the EU. |
| Refers to partner hosted agreements. These are no longer allowed within the EU. |
You can find complete lists of all required and optional fields in our API reference.
post
https://api.checkout.com/payment-contexts
1{2"source": {3"type": "paypal"4},5"currency": "USD",6"amount": 2000,7"capture": true,8"payment_type": "Recurring",9"items": [10{11"name": "laptop",12"unit_price": 2000,13"quantity": 114}15],16"processing": {17"plan": {18"type": "merchant_initiated_billing"19}20},21"processing_channel_id": "{{NAS-processingChannel-personal}}",22"success_url": "http://www.example.com/success.html",23"failure_url": "http://www.example.com/failure.html"24}
201 Created
success status response code with an order id your request was successful.
1{2"id": "pct_pn3qgabosnjefd5mqhvnwkgeyq",3"partner_metadata": {4"order_id": "BA-2MT22297HW5277538"5},6"_links": {7"self": {8"href": "https://api.checkout.com/payment-contexts/pct_pn3qgabosnjefd5mqhvnwkgeyq"9}10}11}
Once the initial payment is captured successfully, you can trigger subsequent payments based on your schedule.
- Add
\&intent=tokenize\&vault=true
in the JS SDK script if the payment sets up as a recurring.<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&merchant-id=YOUR_Merchant_ID&vault=true"></script>
- Replace the
createOrder
function in the SDK code with thecreateBillingAgreement
function.
post
https://api.checkout.com/payments/
Use this request only if the customer did not make any changes in the final review page.
1{2"payment_context_id":"pct_ckjrpk7vux4ejhghe6ssgkoy2y",3"processing_channel_id": "{{NAS-processingChannel-personal}}"4}
Your request was successful if you receive a 202 Success
status response code which contains a status
field set to Pending
.
1{2"id": "pay_myvk2vuj3dgeffho6iuretryfm",3"status": "Pending",4"source": {5"id": "src_fkhtu6spgqfelnndfqcjpsnaae",6"type": "paypal"7},8"processing": {9"partner_order_id": "7GU48395JD5519252"10},11"_links": {12"self": {13"href": "https://api.checkout.com/payments/pay_myvk2vuj3dgeffho6iuretryfm"14}15}16}
For subsequent payment requests to occur, the following steps must be complete:
- Customer accepts the billing agreement in the PayPal pop-up widget.
- First payment status has to change to
Captured
. - You must store the
source.id
from the payment response and initiate the next payment using thatsource.id
.
post
https://api.checkout.com/payments/
1{2"source": {3"type": "id",4"id": "src_fkhtu6spgqfelnndfqcjpsnaae"5},6"merchant_initiated": true,7"currency": "USD",8"amount": 2000,9"items": [10{11"name": "laptop",12"unit_price": 2000,13"quantity": 114}15],16"processing_channel_id": "{{NAS-processingChannel-personal}}",17"success_url": "http://www.example.com/success.html",18"failure_url": "http://www.example.com/failure.html",19"payment_type": "recurring"20}
Your request was successful if you receive a 202 Success
response code which contains the status
field set to Pending
.
1{2"id": "pay_ok7yhvutuylevnatk3x3dxviq4",3"status": "Captured",4"source": {5"id": "src_fkhtu6spgqfelnndfqcjpsnaae",6"type": "paypal"7},8"processing": {9"partner_order_id": "83U53060E16713839"10},11"_links": {12"self": {13"href": "https://api.checkout.com/payments/pay_ok7yhvutuylevnatk3x3dxviq4"14}15}16}
PayPal's Seller Protection program can help to cover you in the event of claims, chargebacks, or reversals that are raised as a result of Unauthorized Transaction or Item Not Received scenarios.
Information
For more information on your eligibility and what the Seller Protection program covers, refer to PayPal's documentation.
For a transaction to be eligible for Seller Protection, you must provide the customer's full name and address in the payment context request.
Typically, digital goods do not benefit from Seller Protection unless you have an explicit agreement with PayPal. If you have an agreement, you must also provide the processing.partner_customer_risk_data
field in your payment context request.
When you perform an eligible test payment, the transaction will be marked as Seller Protection-eligible in the sandbox environment. Contact your Account Manager for more information.
Use the payment_id
found in the payment response to retrieve details about the payment.
For more details, see our API reference.
PayPal supports both partial and full refunds. PayPal refunds are based on the capture and not on the payment. If you perform multiple captures you must specify the "capture_action_id"
in your refund request.
You can refund payment through the dashboard or using the refund API.
Information
If you refund or void a transaction directly via Paypal instead of using our API or Dashboard, the payment status will not sync back with Checkout.com.
post
https://api.checkout.com/payments/{id}/refunds
1{2"amount": 1003}
1{2"actionId": "act_cxpffngdvouvabegyy3asiuou",3"_links": {4"payment": {5"href": "https://api.checkout.com/payments/pay_ok7yhvutuylevnatk3x3dxviq4"6}7}8}
If you perform multiple partial captures, you must make a partial or full refund on the specific capture based on the capture id assigned to it. Do this by specifying the "capture_action_id"
and amount
in your refund.
Information
If you perform multiple partial captures, the refund amount cannot exceed the amount of that specific capture. You can see the capture amount and the capture action id using our GET action endpoint.
post
https://api.checkout.com/payments/{id}/refunds
Request example for multiple partial captures
1{2"amount": 1000,3"capture_action_id" : "act_d2on4akgfwfexg3ye65la3udtq"4}
1{2"actionId": "act_d2on4akgfwfexg3ye65la3udtq",3"reference": "ORD-5023-4E89",4"_links": {5"payment": {6"href": "https://api.checkout.com/payments/pay_jwvjl5tin54ubn7x2stvmunske"7}8}9}
Once a payment is created using the auto-capture payment flow, it cannot be voided by the merchant. If you wish to reverse a payment in progress, please wait for the payment_captured webhook, and then process a refund. The webhooks you may receive are outlined in more detail below.
A payment can be fully voided after it is authorized but not yet captured. PayPal doesn’t support partial void.
post
https://api.checkout.com/payments/{id}/voids
1{2"action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",3"reference": "ORD-5023-4E89",4"_links": {5"payment": {6"href": "https://api.sandbox.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"7}8}9}
To test your integration, you require a PayPal developer account. Using your developer account, you can then create a PayPal sandbox environment, a PayPal Business and Personal sandbox accounts to test payments.
- Create a PayPal developer account, if you do not already have one.
- Using your developer account, create PayPal Business and Personal sandbox accounts.
Information
To see your test payments, you must create your sandbox accounts using your PayPal developer account.
For more details, see the PayPal sandbox testing guide.
The following table provides an overview of the PayPal accounts required for your test integration:
Account type | Description | Purpose |
Developer | PayPal developer account. | Access the PayPal developer dashboard, create and manage Business and Personal sandbox accounts. |
Business | PayPal sandbox Business account. For example, with an email address ending in @business.example.com | Add PayPal as a payment method in your test Customer Area. Provide the Merchant ID and email address of this account. |
Personal | PayPal sandbox Personal account. For example, with an email address ending in @personal.example.com | Test payments from a customer's side. |
Once you've created PayPal developer and sandbox accounts, you're ready to start testing:
- Reach out to your Account Manager or [email protected] to activate PayPal payments in the sandbox environment.
- Create a PayPal transaction, by following the PayPal Payment flow and using either a Auto-capture, Manual-capture, or Recurring payment flow.
- Log in to the test customer's PayPal account.
- Confirm the payment.
You will then be redirected to your predefined success URL.
Information
We strongly recommend that you use a generic company email address for your live PayPal Business account instead of a personal email address. This is to prevent having to configure a new account for your business in future, should the personal email address no longer be in use for any reason.
Log in to PayPal with your live Business account.
Follow PayPal's Merchant Account Admin Guide on granting third-party permissions. Under Permissions, select the following items:
- 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 available in your region
- Use Express Checkout to process mobile payments - if you plan on supporting mobile payments
If you're using PayPal for recurring payments, also select the following boxes:
- Charge an existing customer based on a prior transaction
- Create and manage Recurring Payments
Airlines must provide additional information about the ticket, passenger, and flight in their payment context request, using the processing.airline_data
field:
1{2"processing": {3"airline_data": [4{5"ticket": {6"number": "045-21351455613",7"issue_date": "2023-05-20",8"issuing_carrier_code": "AI",9"travel_agency_name": "World Tours",10"travel_agency_code": "01"11}12},13{14"passenger": [15{16"first_name": "John",17"last_name": "White",18"date_of_birth": "1990-05-26",19"address": {20"country": "US"21}22}23]24},25{26"flight_leg_details": [27{28"flight_number": "101",29"carrier_code": "BA",30"class_of_travelling": "J",31"departure_airport": "LHR",32"departure_date": "2023-06-19",33"departure_time": "15:30",34"arrival_airport": "LAX",35"stop_over_code": "X",36"fare_basis_code": "SPRSVR"37},38{39"flight_number": "103",40"carrier_code": "BA",41"class_of_travelling": "J",42"departure_airport": "LAX",43"departure_date": "2023-06-23",44"departure_time": "15:30",45"arrival_airport": "LHR",46"stop_over_code": "X",47"fare_basis_code": "SPRSVR"48}49]50}51]52}53}
Webhook | Description |
---|---|
| Sent when a payment request has been successfully initiated. |
| Sent when the payment has been successfully captured. |
| Sent when a payment request has been rejected. |
| Occurs when a payment reached its expiry date without being captured |
| Sent when the payment has been (fully or partially) refunded. |
| Sent when a refund has been declined. |
Webhook | Description |
---|---|
| Sent when a payment request has been successfully initiated. |
| Sent when payment is approved by the customer. |
| Sent when the payment has been successfully captured. |
| Sent when a payment request has been rejected. |
| Sent when payment is voided after authorization. Sent when payment is voided after partial capture. Sent when payment is expired. |
| Occurs when an authorized payment reached its expiry date. |
| Sent when void request is declined. |