Paypal Custom Checkout Integration with Chargebee APIs

Tutorial Scope

This tutorial helps to implement Custom checkout for wallet payments and creating a subscription in Chargebee, using PayPal's BAID (Billing Agreement Identifier), integrated through Chargebee’s APIs. We have also included the sample code and Github links to help you test and try the tutorial with mock checkouts.

Prerequisites

Before trying out this tutorial, you need to set up the following:

• A Chargebee account. Sign up for a free trial if you don't have one.
• Plans configured in Chargebee.
• PayPal sandbox account integrated with your Chargebee user interface.
• Configure PayPal Commerce as a gateway before initiating the integration process.
• PayPal's client key and API key.
• Your Chargebee test site's API key.
• Get access token to use the PayPal REST API server.

Steps to integrate Paypal Custom Checkout

Here are the steps to integrate Paypal Custom Checkout with Chargebee APIs.

Step 1: Set up your development environment

To set up your development environment, follow these steps.

• Before integrating Reference Transactions, you must enable it from PayPal and set up your development environment.
• Create sandbox accounts to test your web and mobile apps after you get a token that lets you access protected REST API resources. For details, see Get started.

Get API credentials

To get these credentials from a REST API app in the Developer Dashboard, follow these steps.

1. Log in to the Developer Dashboard with your PayPal account.
2. Under the DASHBOARD menu, select My Apps & Credentials.
3. Confirm that you are on the Sandbox tab to get the API credentials to be used while you're developing code. After testing this and prior to go live, switch to the Live tab to get the live credentials.
4. Select Create App.
5. Under App Type, select Platform - Move payments to sellers as a platform (Marketplace, crowdfunding, or e-commerce platform).
6. Select Create App. For details on getting API credentials, see Get API Credentials.

Get sandbox account information

To get sandbox account information, follow these steps.

1. Log in to the Developer Dashboard with your PayPal account.
2. In the Developer Dashboard, under SANDBOX, select Accounts.
3. Under Account Name, find your personal sandbox account.
4. Under Manage Accounts, select the (...) button for your personal account.
5. Select View/Edit Accounts to display your email ID and a system-generated password.
6. Repeat these steps for the business account. For details on sandbox account, see Get sandbox account information.

Then, return to this page to integrate Reference Transactions.

Step 2: Set up Chargebee's Client Library

Download and import the client library of your choice. Configure the client library with the Chargebee Test site and its full-access API Key.

Step 3: Set PayPal Branding Button (Client-Side Implementation)

Set PayPal button with an action to initiate the payment process and branding. To get the PayPal button logo, see PayPal logo centre.

The following is an example of a PayPal payment button, you can also create your own branding button using similar snippets.

<div role="button" id="Paypal-button-container" onclick="createBilling()">
    <table border="0" cellpadding="10" cellspacing="0" align="center"><tr><td align="center"></td></tr><tr><td align="center">
        <img src="https://www.paypalobjects.com/webstatic/en_US/i/buttons/checkout-logo-large.png" alt="Check out with PayPal" />
    </td></tr></table><!-- PayPal Logo -->
</div>

Step 4: Create Billing Agreement Token (Server-Side Implementation)

Pass the Access-Token to authorize the call and agreement details including the description, payer, and billing plan in the JSON request body to create a billing agreement token.

To create a billing agreement token, follow these steps.

• Set the payment_method parameter in the payer object to PayPal.

Example

curl -v -X POST https://api-m.sandbox.Paypal.com/v1/billing-agreements/agreement-tokens \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Access-Token>" \
  -d '{
  "description": "Billing Agreement",
  "shipping_address":
  {
    "line1": "PO Box 9999",
    "city": "Walnut",
    "state": "California",
    "postal_code": "91789",
    "country_code": "US",
    "recipient_name": "John Doe"
  },
  "payer":
  {
    "payment_method": "Paypal"
  },
  "plan":
  {
    "type": "MERCHANT_INITIATED_BILLING",
    "merchant_preferences":
    {
      "return_url": "https://example.com/return",
      "cancel_url": "https://example.com/cancel",
      "notify_url": "https://example.com/notify",
      "accepted_pymt_type": "INSTANT",
      "skip_shipping_address": false,
      "immutable_shipping_address": true
    }
  }
}'

• If your request for a billing agreement with PayPal payment method succeeds, the API returns the HTTP 201 Created status code and a JSON response that includes an approval URL:

Response

{
  "links": [
    {
      "href": "https://api-m.sandbox.Paypal.com/agreements/approve?ba_token=BA-8A802366G0648845Y",
      "rel": "approval_url",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.Paypal.com/v1/billing-agreements/BA-8A802366G0648845Y/agreements",
      "rel": "self",
      "method": "POST"
    }
  ],
  "token_id": "BA-8A802366G0648845Y"
}

• Redirect the customer to the approval URL, where the customer can consent to the billing agreement and select a funding instrument.
• Then, the customer is redirected to the return URL that the merchant specified during billing agreement token creation.

Step 5: Create Billing Agreement (Server-Side Implementation)

After buyer approval, you use a billing agreement token to create the agreement.

Include the token in the URI

curl -v -X POST https://api-m.sandbox.Paypal.com/v1/billing-agreements/agreements \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Access-Token>" \
  -d '{
  "token_id": "BA-8A802366G0648845Y"
}'

A successful request returns the HTTP 201 Created status code and a JSON response body that includes the billing agreement ID, the state of the agreement, which is ACTIVE, and information about the payer:

{
  "id": "B-50V812176H0783741",
  "state": "ACTIVE",
  "description": "Billing Agreement",
  "payer": {
    "payer_info": {
      "email": "john@user.com",
      "first_name": "John",
      "last_name": "Doe",
      "payer_id": "ZU7HZ76P4VL5U"
    }
  },
  "plan": {
    "type": "MERCHANT_INITIATED_BILLING",
    "merchant_preferences": {
      "notify_url": "https://example.com/notify",
      "accepted_pymt_type": "INSTANT"
    }
  },
  "links": [
    {
      "href": "https://api-m.sandbox.Paypal.com/v1/billing-agreements/agreements/B-50V812176H0783741/cancel",
      "rel": "cancel",
      "method": "POST"
    },
    {
      "href": "https://api-m.sandbox.Paypal.com/v1/billing-agreements/agreements/B-50V812176H0783741",
      "rel": "self",
      "method": "GET"
    }
  ],
  "merchant": {
    "payee_info": {
      "email": "merchant@example.com"
    }
  },
  "create_time": "2017-08-08T07:19:28.000Z",
  "update_time": "2017-08-08T07:19:28.000Z"
}

Save the id value from the above JSON response. This value is the Billing Agreement ID(BAID). You must use this BAID as a value of the payment method’s reference ID during Subscription creation.

Step 6: Creating a Subscription (Server-Side Implementation)

To create a subscription in Chargebee, pass the Billing Agreement ID(BAID) as a reference_id value in the payment_method with other POST parameters (in the checkout page's form submit an event), using the create subscription API.

Sample request to create a subscription in Chargebee

# creates a subscription with customer information and billing details.
curl  https://{site}.chargebee.com/api/v2/subscriptions \
     -u {site_api_key}:\
     -d plan_id="no_trial" \
     -d auto_collection="on" \
     -d customer[first_name]="John" \
     -d customer[last_name]="Doe" \
     -d customer[email]="john@user.com" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US" \
     -d payment_method[reference_id]="B-50V812176H0783741"\
     -d payment_method[type]="Paypal_express_checkout"

Though the parameters have been validated at the client-side, for additional security, it is strongly recommended that you perform these validations on the server-side as well.

Chargebee Response

The following are the responses.

• Chargebee returns a successful response in the JSON format wrapped in the client library’s 'result' class.
• In case of an error, Chargebee returns an error response, which is an exception thrown by the client library.

In case of successful checkout, you can redirect the user to a simple Thank You page.

Validation and Error-Handling

Here's how we validate user inputs and handle API call errors in this demo:

• Client-Side Validation: Chargebee uses the jQuery form validation plugin to verify whether the user's field inputs(email, zip code, and phone number) are valid or not.
• Server-Side Validation: As this is a demo application, we skipped the server-side validation for all input parameters. However, we recommend you perform the validation at your end.
• Payment Errors: If a payment fails due to processing errors, Chargebee returns an error response as a payment exception by the client library. Exceptions are handled in the demo application with appropriate error messages.
• General API Errors: Chargebee might return error responses for various reasons such as invalid configuration, bad requests, etc. To identify specific reasons for all error responses, you can check the API documentation. Also, take a look at the error handler file to check how these errors can be handled.

Reference Links

• Chargebee API Docs
• Jquery Validation
• PayPal Integration Docs