Skip to content

PayPal

Beta

Last updated: July 20, 2022

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

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

check

Separate capture

error
Payments are captured immediately after authorization by default.

Refund

check

Partial refund

check

Disputes

check
All disputes are handled directly via PayPal.

Chargeback

check
All chargebacks are handled directly via PayPal.

Recurring payment

check

Redirect payment flow

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

  1. Request a PayPal payment
  2. Redirect the customer

Request a payment

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

Request example

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

Response example

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 the customer

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

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:

  1. Request a PayPal payment
  2. 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.

PayPal Express Checkout

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/

Request example

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
}

Response example

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 the customer

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.

Capture the payment

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

Full capture example request

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

Full capture example response

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
}

Partial capture example request

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

Partial capture example response

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
}

Request a recurring payment

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/

Initial request example

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
        "name": "laptop",
13
        "unit_price": 2000,
14
        "quantity": 1
15
    }],
16
    "processing_channel_id": "pc_ekaubqrravqupfxde7kxvd2t3i"
17
}

Initial response example

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
}

Set up subsequent requests

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.

Subsequent request example

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

Subsequent response example

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
}

Get details about a payment

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}

Response example

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
        "name": "laptop",
30
        "quantity": 1,
31
        "unit_price": 2000
32
    }],
33
    "_links": {
34
        "redirect": {
35
            "href": "https://www.sandbox.paypal.com/checkoutnow?token=0C438986FY9797333"
36
        },
37
        "self": {
38
            "href": "https://api.sandbox.checkout.com/payments/pay_ykxmuzebtj3ujjlbnb6cks4emy"
39
        },
40
        "actions": {
41
            "href": "https://api.sandbox.checkout.com/payments/pay_ykxmuzebtj3ujjlbnb6cks4emy/actions"
42
        }
43
    }
44
}

Refund a payment

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

Request example

1
{
2
    "amount": 100
3
}

Response example

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

Cancel a payment

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.

Webhooks

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

WebhookDescription

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:

WebhookDescription

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.

Testing PayPal

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

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

Create developer and sandbox accounts

To start testing payments, follow the steps below:

  1. Create a PayPal developer account, if you don't already have one.
  2. 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.

Required PayPal accounts for testing

Account typeDescriptionUsage

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.

Set up third-party API access on your PayPal account

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.

  1. Sign in to your PayPal test store using the Business test account details.
  2. Retrieve your merchant_id and share it with your Customer Success Manager.
  3. Follow PayPal's instructions on granting third-party permissions.
  4. 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)
  5. 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

Get your PayPal merchant ID

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.

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

PayPal seller protection

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.

On this page

Redirect payment flow
PayPal Smart Payment Button
PayPal Express Checkout
Request a recurring payment
Get details about a payment
Refund a payment
Cancel a payment
Webhooks
Testing PayPal