Getting Started

PointCheckout Integration Support

API Integration


INTRODUCTION

This document provides the integration details between the merchant & the PointCheckout systems. The integration allows the merchant system with its own shopping and order processing system to work in conjunction with PointCheckout system for the payments. The merchant would need the API credentials & the private secret key to access the PointCheckout API.

The process is outlined below:

  1. When a customer is ready to pay for their order/shopping cart on the merchant system, a “Pay with PointCheckout” option is presented.

  2. On submitting the “Pay with PointCheckout” button, the merchant system processes the order & makes the “NEW CHECKOUT REQUEST” API call to PointCheckout & obtains a checkout key.

  3. On successfully obtaining the token from PointCheckout in the previous step, the merchant system then redirects the customer to PointCheckout passing in this checkout key (See  PAYMENT PAGE REDIRECT).

  4. The customer then logs in or registers to PointCheckout. At this stage, the customer may either successfully complete the payment or cancel the payment.

  5. In any of the cases in the previous step, the customer is finally returned to the merchant system.

  6. Once the customer has been returned to the merchant system from PointCheckout, the merchant system makes the

    “GET CHECKOUT REQUEST” API call to retrieve the status of the payment and at this stage the checkout is now complete.

REQUIREMENTS

Below are the requirements that must be implemented in the shopping cart extension for PointCheckout.

  1. Add a new Payment Method to the checkout page called PointCheckout. Should use the PointCheckout logo.

  2. Should support the following configuration options:

    a. Support for Staging / Test / Live environments.
    b. Ability to restrict payment to users from specific countries
    c. Ability to restrict payment to users from specific user groups d. Ability to configure new order status


SETTINGS SCREEN

The settings screen for the PointCheckout payment method should include at minimum the following configuration options. 

SUPPORTED ENVIRONMENTS

The PointCheckout Payment Extension / Plugin should support the following two environments; Staging and Production. Throughout the API, they will be referred to as $BASE_URL and user can select current environment in the administrator settings screen.

STAGING ENVIRONMENT

Base URL

https://pay.staging.pointcheckout.com


TEST ENVIRONMENT

Base URL

https://pay.test.pointcheckout.com


PRODUCTION ENVIRONMENT

Base URL

https://pay.pointcheckout.com


API REQUESTS

There are two relevant API requests within the checkout process:

NEW CHECKOUT REQUEST

This requests sends the checkout details to the PointCheckout checkout service. It returns a unique checkout id that would be used for the processing of the payment.

REQUEST URL 

Request URL

$BASE_URL/api/mer/v1.1/checkout

METHOD TYPE

Request Type

POST


HEADER PARAMETERS

HEADER

DETAILS

Api-Key

The merchant API key.

Api-Secret

The Merchant API Secret.

Content-Type

application/json

QUERY PARAMETERS

The Request URL may include the below parameters

PARAMETER

TYPE

DETAILS

qr (new)

Boolean

indicator to generate a Base64 QR image and include it in the response, default is false. (Optional)

qrsize (new)

Integer

the size of the QR image in pixels, default is 300

REQUEST BODY

The request is a JSON based object. It includes the following parameters 

HEADER

TYPE

DETAILS

referenceId

String

A merchant unique reference ID for this checkout. This can be the order ID. Must match any reference shown to user during checkout / order history. (Required)

redirectUrl

String

URL to redirect user to after payment update (successful or failure)

successUrl

String

URL to redirect user to after a successful payment (optional when redirectUrl is present)

failureUrl

String

URL to redirect user to after a failed payment (optional when redirectUrl is present)

grandtotal*

Decimal

The grand total of the whole order. This is the amount customer must pay. (Required)

subtotal **

Decimal

Sum of all individual line items (without discount / tax / shipping / etc). (Required)

shipping

Decimal

Total value of shipping. (Required)

tax

Decimal

Tax value on order. (Required)

discount

Decimal

Value of discount applied to Subtotal. (Required)

currency

String

ISO 4217 Currency Code (3 letter currency code). (Required)

deviceReference (new)

String

Merchant device reference, to be used by the merchant to indicate the source device of the checkout if more than one device is used to submit checkouts to PointCheckout

items

Array

An array of objects representing the items associated with this order. (Required)

name

String

The name of the item being sold to customer. (Required)

sku

String

Merchant item SKU. (Required)

quantity

Decimal

Quantity of item being bought by user. (Required)

total

Decimal

Total selling price for quantity of this item. (Required)

customer

Object

Details of the customer making the purchase

firstName

String

Customer first name

lastName

String

Customer last name

email

String

Customer email address

phone

String

Customer phone number with international calling code (Ex. 971567xxxxxx).

billingAddress

Object

Customer billing address

name

String

Billing address name

address1

String

Billing address line 1

address2

String

Billing address line 2

city

String

Billing address city

state

String

Billing address state

zip

String

Billing zip code

country

String

Billing address country (3 letter ISO country code)

shippingAddress

Object

Customer billing address

name

String

Shipping address name

address1

String

Shipping address line 1

address2

String

Shipping address line 2

city

String

Shipping address city

state

String

Shipping address state

zip

String

Shipping zip code

country

String

Shipping address country (3 letter ISO country code)

    * Grand Total = “subtotal” + “shipping” + “tax” – “discount”
  ** Subtotal = Sum (item total) for all items 

RESPONSE

The response is a JSON based object. It has the following structure

HEADER

TYPE

DETAILS

success

Boolean

Whether or not this operation completed successfully.

elapsed

Number

Time elapsed at server processing this request.

result

Object

Result Object

checkoutId

String

Unique PointCheckout ID associated to this checkout.

checkoutKey

String

Checkout Key used for redirecting user to checkout page to complete payment. (See  PAYMENT PAGE REDIRECT)

checkoutDisplayId (new)

String

Checkout human readable short key, serves as an easier reference to the checkout

merchantId

String

The PointCheckout merchant ID associated with this checkout.

merchantName

String

The PointCheckout merchant name associated with this checkout.

referenceId

String

Merchant unique reference ID for this checkout. This should be the same as Order ID and match reference shown to user during checkout / order history.

currency

String

ISO 4217 Currency Code (3 letter currency code) associated with this checkout.

grandtotal

Decimal

The grand total of the whole order. This is the amount customer must pay.

cod (new)

Decimal

Cash amount to be collected from Shopper

status

String

Current checkout status. (See  CHECKOUT STATUSES)

deviceReference (new)

String

Merchant device reference, the same as provided in the request

firebaseDatabase (new)

String

Google firebase database name, to be used to receive notifications on checkout updates

firebaseCollection (new)

String

Google firebase collection name, to be used to receive notifications on checkout updates

firebaseDocument (new)

String

Google firebase document name, to be used to receive notifications on checkout updates

base64QR (new)

String

Base64 QR Code image data, that can be used for Quick Payment using PointCheckout Mobile App, This will only contain value when the qr Request URL query parameter is present and set to true

 

SAMPLE REQUEST BODY

Below is a sample request body for a “New Checkout” request.   

{

  "referenceId":"CHK-1000",

  "successRedirectUrl":"https://onlinestore.com/pointcheckout/payment-success",

  "failRedirectUrl":" https://onlinestore.com/pointcheckout/payment-success ",

  "grandtotal":"100.00",

  "subtotal":"100.00",

  "shipping":"2.0",

  "tax":"2.0",

  "discount":"4.00",

  "currency":"aed",

  "deviceReference":"POS-01",

  "items":[

    {

      "name":"Laptop XYZ case",

      "sku":"1234",

      "quantity":2,

      "total":90

    },

    {

      "name":"iPhone 7 Cover",

      "sku":"1234",

      "quantity":1,

      "total":10

    }

  ],

  "customer":{

    "firstName":"Bashar",

    "lastName":"Saleh",

    "email":"bashar.saleh@gmail.com",

    "phone":"971567824730",

    "billingAddress":{

      "name":"Bashar Saleh",

      "address1":"Business Central Towers",

      "address2":"Media city",

      "city":"Dubai",

      "state":"Dubai",

      "zip":"123",

      "country":"ARE"

    },

    "shippingAddress":{

      "name":"Bashar Saleh",

      "address1":"Business Central Towers",

      "address2":"Media city",

      "city":"Dubai",

      "state":"Dubai",

      "zip":"123",

      "country":"ARE"

    }

  }

}


 

SAMPLE RESPONSE BODY

Below is a sample response body for a “New Checkout” request.  

{

    "success":true,

    "elapsed":468,

    "result":{

        "checkoutId":"1584154845799418134",

        "checkoutKey":"8d1796e88bbc37ef73a9edc3d3d85c0267c5c0bb3feb56dc",

        "checkoutDisplayId":"N098T3",

        "merchantId":"15b9b327ce8bfa09",

        "merchantName":"amazon.com",

        "referenceId":"CHK-0100",

        "currency":"AED",

        "grandtotal":100,

        "cod":0,

        "status":"PENDING",

        "deviceReference":"POS-01",

        "firebaseDatabase":"pc-checkout",

        "firebaseCollection":"checkout",

        "firebaseDocument":"nTDry405THLLrVKTstjIQemXIVC3OhJN",

        "base64QR":null

    }

}


 

SAMPLE ERROR RESPONSE BODY

Below is a sample response body for a “New Checkout” request.  

{

    "success":false,

    "elapsed":150,

    "error":"A checkout already exists for this merchant with reference id 'CHK-1000'"

}

 



GET CHECKOUT REQUEST

This requests asks PointCheckout to send checkout updated, usually after a user is redirected back to the merchant website. 

REQUEST URL 

Request URL

$BASE_URL/api/mer/v1.1/checkout/ $CHECKOUT_ID 

METHOD TYPE

Request Type

GET


HEADER PARAMETERS

HEADER

DETAILS

Api-Key

The merchant API key.

Api-Secret

The Merchant API Secret.

Content-Type

application/json

QUERY PARAMETERS

The Request URL may include the below parameters

PARAMETER

TYPE

DETAILS

qr  (new)

Boolean

indicator to generate a Base64 QR image and include it in the response, default is false. (Optional)

qrsize  (new)

Integer

the size of the QR image in pixels, default is 300


RESPONSE

The response is a JSON based object. It has the following structure

HEADER

TYPE

DETAILS

success

Boolean

Whether or not this operation completed successfully.

elapsed

Number

Time elapsed at server processing this request.

result

Object

Result Object

checkoutId

String

Unique PointCheckout ID associated to this checkout.

checkoutKey

String

Checkout Key used for redirecting user to checkout page to complete payment. (See  PAYMENT PAGE REDIRECT) )

checkoutDisplayId  (new)

String

Checkout human readable short key, serves as an easier reference to the checkout

merchantId

String

The PointCheckout merchant ID associated with this checkout.

merchantName

String

The PointCheckout merchant name associated with this checkout.

referenceId

String

Merchant unique reference ID for this checkout. This should be the same as Order ID and match reference shown to user during checkout / order history.

currency

String

ISO 4217 Currency Code (3 letter currency code) associated with this checkout.

grandtotal

Decimal

The grand total of the whole order. This is the amount customer must pay.

cod  (new)

Decimal

Cash amount to be collected from Shopper

status

String

Current checkout status. (  CHECKOUT STATUSES)

deviceReference  (new)

String

Merchant device reference, the same as provided in the request

firebaseDatabase  (new)

String

Google firebase database name, to be used to receive notifications on checkout updates

firebaseCollection  (new)

String

Google firebase collection name, to be used to receive notifications on checkout updates

firebaseDocument  (new)

String

Google firebase document name, to be used to receive notifications on checkout updates

base64QR  (new)

String

Base64 QR Code image data, that can be used for Quick Payment using PointCheckout Mobile App, This will only contain value when the  qr Request URL query parameter is present and set to  true


SAMPLE SUCCESSFUL RESPONSE BODY

Below is a sample response body for a “Get Checkout” request.   

{

    "success":true,

    "elapsed":468,

    "result":{

        "checkoutId":"1584154845799418134",

        "checkoutKey":"8d1796e88bbc37ef73a9edc3d3d85c0267c5c0bb3feb56dc",

        "checkoutDisplayId":"N098T3",

        "merchantId":"15b9b327ce8bfa09",

        "merchantName":"amazon.com",

        "referenceId":"CHK-0056",

        "currency":"AED",

        "grandtotal":100,

        "cod":0,

        "status":"PENDING",

        "deviceReference":"POS-01",

        "firebaseDatabase":"pc-checkout",

        "firebaseCollection":"checkout",

        "firebaseDocument":"nTDry405THLLrVKTstjIQemXIVC3OhJN",

        "base64QR":null

    }

}

 


SAMPLE ERROR RESPONSE BODY

Below is a sample response body for a “Get Checkout” request.  

{

    "success":false,

    "elapsed":150,

    "error":"No checkout found with id '1584154845799418132'"

}




CHECKOUT STATUSES

A checkout can have multiple statuses that describe the current state that the checkout is in.    

STATUS

DETAILS

PENDING

New Checkout. User has not completed payment.

PAID

This status is effective when a customer has successfully completed the payment associated with this checkout.

FAILED

Payment failed due card or reward payment failure. PointCheckout failed to recover such checkout process.

CANCELLED

User cancelled the checkout process and returned to merchant page.


PAYMENT PAGE REDIRECT

Upon a successful NEW CHECKOUT REQUEST user should be redirected to the PointCheckout Payment Page. The URL used for the redirect is shown below:  

Redirect URL

$BASE_URL/checkout/$CHECKOUT_KEY

  *  $CHECKOUT_KEY is the Checkout Key returned in a successful new checkout request request (See  CHECKOUT RESPONSE RESPONSE )

PAYMENT RESPONSE HANDLING

Once a user completes a transaction, the user is redirected to the merchant website to proceed with the payment. The user is redirected to the pre-configured URL in the Merchant Admin panel. The response contains the following URL encoded parameters:   

PARAMETER

DETAILS

checkoutId

The PointCheckout checkout ID that was processed.

We do not return the referenceId on purpose to avoid storing such details in merchant session and enforce a lookup / storage of payment and order details.


Last Updated  November 4, 2019