Use this guide to add PayPal to your Ignite 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 Ignite setup
• 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

Initialize Payment

The Initialize Payment endpoint v1/payments initializes the payment object made with PayPal via Bolt Checkout. Returns an ID that identifies this payment session and associated details.

Request

• payment_data: The success and cancel URLs inform PayPal where to redirect users upon completion of the payment flow, with URLs that vary based on the completion status.

{
  "payment_method": {
    "type": "paypal",
    "payment_data": {
        "success": "https://example.com/on_paypal_success",
        "cancel": "https://example.com/on_paypal_cancel"
    },
  },
  "shopper_identity": {
    "phone": "8888888888",
    "email": "test123@bolt.com",
    "first_name": "Test",
    "last_name": "Bolt",
    "create_bolt_account": true
  }
}

Response

The response includes an ID, status, and secure authentication URL.

{
   "id": "abcd1234",
   "status": "awaiting_user_confirmation",
   "action": {
       "type": "redirect",
       "url": "https://example.com/unique_paypal_authentication_url",
       "method": "GET"
   }
}

Update Payment

The Update Payment endpoint v1/payments/{payment_id} makes updates to the cart object associated with a payment that has already been initialized with v1/payments. This action completely replaces the cart, so you’ll resend the entire cart object with updated payment information.

Request

{
   "cart": {
       "currency": "USD",
       "items": [
           {
               "image_url": "https://google.com",
               "name": "Face Mask",
               "quantity": 1,
               "reference": "COTF-WA1",
               "total_amount": 1400,
               "unit_price": 1400
           }
       ],
       "tax_amount": 109,
       "total_amount": 1509,
       "order_reference": "test1"
   }
}

Response

Because this payment has already been authorized during Initialize Payment, the response indicates that the payment is ready to be finalized.

{
   "id": "abcd1234",
   "status": "payment_ready",
   "action": {
       "type": "finalize",
       "url": "api.bolt.com/v1/payments/finalize",
       "method": "POST"
   }
}

Finalize Payment

The Finalize Payment endpoint v1/payments/{id}/finalize authorizes the payment and debits the shopper’s PayPal account.

Request

• Path: Pass the id returned from v1/payments
• Body: Pass a first and last name in the shopper_identity object to associate the payment with a shopper

Response

{
   "id": "12334",
   "status": "success",
   "payment_method_id": "d3rawa",
   "transaction": {
      "reference": "F6ZT-3G64-HVGG"
   }
}

Step 2: Bolt Shopper Implementation

With each request, pass in the authorization header and access token (bearer {access_token}). The token is used to associate the payment with the shopper’s account.

Get Account Details

Fetch account details with v1/account to access saved payment methods.

Response

Filter the list by processor: “paypal” to access the PayPal account.

{
    "payment_methods": [
       {
           "id": "ubhdnqd8",
           "type": "saved_apm",
           "processor": "paypal",
           "description": "alan.watts@bolt.com"
         }
    ]
}

Initialize Payment

The Initialize Payment endpoint v1/payments initializes payments made with PayPal via Bolt Checkout. Returns an ID for this payment session and associated details.

Request

• saved_payment_method: Pass the id returned in v1/account

{
  "payment_method": {
    "type": "saved",
    "payment_data": {
        "id": "309jfew09fjwe",
    },
  },
}

Response

The response includes an ID, status, and payment URL.

{
   "id": "abcd1234",
   "status": "payment_ready",
   "action": {
       "type": "finalize",
       "url": "api.bolt.com/v1/payments/finalize",
       "method": "POST"
   }
}

Update Payment

The Update Payment endpoint v1/payments/{payment_id} makes updates to the cart object associated with a payment that has already been initialized with v1/payments. This action completely replaces the cart, so you’ll resend the entire cart object with updated payment information.

Request

Along with the request body, pass in the authorization header and access token (bearer {access_token}). The token is used to associate the payment with the shopper’s account.

{
   "cart": {
       "currency": "USD",
       "items": [
           {
               "image_url": "https://google.com",
               "name": "Face Mask",
               "quantity": 1,
               "reference": "COTF-WA1",
               "total_amount": 1400,
               "unit_price": 1400
           }
       ],
       "tax_amount": 109,
       "total_amount": 1509,
       "order_reference": "test1"
   }
}

Response

Because this payment has already been authorized during Initialize Payment, the response indicates that the payment is ready to be finalized.

{
   "id": "abcd1234",
   "status": "payment_ready",
   "action": {
       "type": "finalize",
       "url": "api.bolt.com/v1/payments/finalize",
       "method": "POST"
   }
}

Finalize Payment

The Finalize Payment endpoint v1/payments/{id}/finalize authorizes the payment and debits the shopper’s PayPal account.

Request

Pass the id returned from v1/payments into the path param.

Response

{
   "id": "12334",
   "status": "success",
   "payment_method_id": "d3rawa",
   "transaction": {
      "reference": "F6ZT-3G64-HVGG"
   }
}

Considerations

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