Skip to content

PayPal Beta

Last updated: 20th July 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

    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.


    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
      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}

        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

          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

          Once a payment is created, you cannot void it. If you wish to void a payment in progress, please wait for the payment_captured webhook, and then process a refund.

          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_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.


          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.