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:

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


Redirect payment flow

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

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

    Copied!

    Request example

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

    Response example

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

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

    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/

      Copied!

      Request example

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

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

      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

        Copied!

        Full capture example request

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

        Full capture example response

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

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

        Partial capture example request

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

        Partial capture example response

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

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

        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/

          Copied!

          Initial request example

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

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

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

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

          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}

            Copied!

            Response example

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

            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

              Copied!

              Request example

              1
              2
              3
              {
              "amount": 100
              }

              Response example

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

              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:

              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.