Use this guide to add PayPal to your Embeddable Checkout implementation. You’ll integrate both guest and logged-in experiences in this article.

Before You Start

These instructions assume that you:

• Have an active Bolt Merchant Account
• Have completed the Embeddable Checkout implementation
• Have reviewed Bolt’s API collection, particularly the account details endpoint

Enable Channel-Initiated Billing

Enable the PayPal feature Channel-Initiated Billing for your PayPal Business Account. Complete this step before you begin implementation.

For Sandbox

1. Go to PayPal’s technical support center and click Contact Us to open a support ticket.
2. Sign into your PayPal account.
3. Enter the following information:
   • • Subject: Enable channel-initiated billing transactions
   • Description: PayPal is rejecting our request to the /v1/billing-agreements/agreement-tokens endpoint due to an authorization issue with a response similar to (please disregard debug_id as it is old): {“name”:“AUTHORIZATION_ERROR”,“debug_id”:“a2259bddf3dc3”,“message”:“Authorization error”,“information_link”:“https://developer.paypal.com/webapps/developer/docs/api/#AUTHORIZATION_ERROR”,“details”:[{“name”:“REFUSED_CHANNEL_INITIATED_BILLING_NOT_ENABLED”,“message”:“This facilitator account is not permitted for Channel Initiated Billing”}. How can we set up channel initiated billing?
   • Environment: Sandbox
   • Integrated through a shopping cart?: No
   • Technical Support Identifier: We provided the full error JSON, including the debug id, which PayPal used to determine which email was linked to the PayPal account that was seeing the error.
4. Submit the ticket.

For Production

1. Sign into your PayPal account.
2. Click Help > Help Center > Contact Us > Message Us.
3. Enter the following message:
   • PayPal is rejecting our request to the /v1/billing-agreements/agreement-tokens endpoint due to an authorization issue with a response similar to (please disregard debug_id as it is old): {“name”:“AUTHORIZATION_ERROR”,“debug_id”:“a2259bddf3dc3”,“message”:“Authorization error”,“information_link”:“https://developer.paypal.com/webapps/developer/docs/api/#AUTHORIZATION_ERROR”,“details”:[{“name”:“REFUSED_CHANNEL_INITIATED_BILLING_NOT_ENABLED”,“message”:“This facilitator account is not permitted for Channel Initiated Billing”}. How can we set up channel initiated billing?
4. Submit the ticket.

Step 1: Guest Shopper Implementation

Guest payments use the Initialize Guest Payment endpoint POST /v3/guest/payments and the Finalize Guest Payment endpoint POST /v3/guest/payments/{id}. Authenticate both with your X-API-Key and X-Publishable-Key headers.

Initialize Payment

Send the shopper’s profile, the cart, and a paypal payment method:

• success_url and cancel_url: where PayPal sends the shopper after they approve or cancel the payment.
• profile.create_account: whether to create a Bolt account for the shopper.

Request

{
  "profile": {
    "create_account": true,
    "first_name": "Test",
    "last_name": "Bolt",
    "email": "test123@boltapp.com",
    "phone": "+14155550199"
  },
  "cart": {
    "order_reference": "test1",
    "total": { "units": 1509, "currency": "USD" },
    "tax": { "units": 109, "currency": "USD" },
    "items": [
      {
        "reference": "COTF-WA1",
        "name": "Face Mask",
        "quantity": 1,
        "unit_price": 1400,
        "total_amount": { "units": 1400, "currency": "USD" },
        "image_url": "https://www.example.com/face-mask.png"
      }
    ]
  },
  "payment_method": {
    ".tag": "paypal",
    "success_url": "https://example.com/on_paypal_success",
    "cancel_url": "https://example.com/on_paypal_cancel"
  }
}

Response

A new PayPal payment is pending until the shopper approves it. Redirect the shopper to url, and keep the id to finalize the payment.

{
  ".tag": "pending",
  "id": "iKv7t5bgt1gg",
  "status": "awaiting_user_confirmation",
  "action": "redirect",
  "url": "https://www.paypal.com/checkout/redirect"
}

Finalize Payment

After PayPal redirects the shopper to your success_url, call POST /v3/guest/payments/{id} with the id from the initialize response to authorize the payment and debit the shopper’s PayPal account.

Request

{
  ".tag": "finalize"
}

Response

{
  ".tag": "finalized",
  "id": "iKv7t5bgt1gg",
  "status": "success",
  "transaction": {
    "reference": "OBYG-X1PX-FN55"
  }
}

Step 2: Bolt Shopper Implementation

Payments for a logged-in Bolt shopper use the Initialize Payment endpoint POST /v3/payments. With each request, pass the shopper’s access token in the Authorization: Bearer {access_token} header along with your X-API-Key and X-Publishable-Key headers. The token associates the payment with the shopper’s account.

Get Account Details

Fetch account details with GET /v3/account to see the shopper’s saved payment methods. Confirm with Bolt how a saved PayPal account is listed for your division.

Initialize Payment

Pass the saved payment method by reference, with the cart in the same shape as the guest request.

Request

{
  "cart": {
    "order_reference": "test1",
    "total": { "units": 1509, "currency": "USD" },
    "tax": { "units": 109, "currency": "USD" }
  },
  "payment_method": {
    ".tag": "id",
    "id": "X5h6j8uLpVGK"
  }
}

Response

Payments with a saved payment method are processed immediately, so the response is already finalized and needs no further call. If the response is pending, finalize it with POST /v3/payments/{id} and {".tag": "finalize"}, as in the guest flow.

{
  ".tag": "finalized",
  "id": "iKv7t5bgt1gg",
  "status": "success",
  "transaction": {
    "reference": "OBYG-X1PX-FN55"
  }
}

Considerations

Some object parameters have been omitted for brevity. Refer to the Embeddable Checkout API v3 reference for the full specs.