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 a NEW CHECKOUT REQUEST or a NEW WALLET 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 to retrieve the final transaction response.


 

SUPPORTED ENVIRONMENTS

PointCheckout supports the following two environments; Test and Production. Throughout the API, they will be referred to as $BASE_URL and the user can select the current environment in the administrator settings screen.

TEST ENVIRONMENT

This environment is used for testing and UAT

Base URL

https://pay.test.pointcheckout.com

 

PRODUCTION ENVIRONMENT

The live payments environments.

Base URL

https://pay.pointcheckout.com

 


 

API REQUESTS

There are two relevant API requests within the checkout process:

NEW CHECKOUT REQUEST

This request 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/v1.0/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

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 the user during checkout/order history. (Required)

successRedirectUrl

String

URL to redirect the user to after a successful payment

failRedirectUrl

String

URL to redirect the user to after a failed payment

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

The 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)

items

Array

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

name

String

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

sku

String

Merchant item SKU. (Required)

quantity

Decimal

Quantity of item being bought by the user. (Required)

total

Decimal

Total selling price for the 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 with this 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 the 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.

status

String

Current checkout status. (See Checkout Request)

checkoutKey

String

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

 

SAMPLE REQUEST BODY

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

 

{

  "referenceId": "CHK-1000",

  "grandtotal": "100.00",

  "subtotal": "100.00",

  "shipping": "2.0",

  "tax": "2.0",

  "discount": "4.00",

  "currency": "aed",

  "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” response.

 

{

    "success": true,

    "elapsed": 468,

    "result": {

        "checkoutId": "1584154845799418134",

        "merchantId": "15b9b327ce8bfa09",

        "merchantName": "amazon.com",

        "referenceId": "CHK-0056",

        "currency": "AED",

        "grandtotal": 100,

        "status": "PENDING",

        "checkoutKey": "8d1796e88bbc37ef73a9edc3d3d85c0267c5c0bb3feb56dc"

    }

}

 

 


 

NEW WALLET CHECKOUT REQUEST

This request sends the checkout details to the PointCheckout checkout service without a pre-determined amount or products/items. It returns a unique checkout id that would be used for the processing of the payment.

NOTE: PointCheckout must enable this request for the merchant. It is not enabled by default and requires pre-approval.

REQUEST URL

Request URL

$BASE_URL/api/v1.0/wallet-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

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 the user during checkout/order history. (Required)

successRedirectUrl

String

URL to redirect the user to after a successful payment

failRedirectUrl

String

URL to redirect the user to after a failed payment

currency

String

ISO 4217 Currency Code (3 letter currency code). (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).

* 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 the server processing this request.

result

Object

Result Object

checkoutId

String

Unique PointCheckout ID associated to this 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 the 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. In the case  of a wallet request, this will be 0.

status

String

Current checkout status. (See Checkout Request)

checkoutKey

String

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

SAMPLE REQUEST BODY

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

 

{

  "referenceId": "CHK-1000",

  "currency": "aed",

  "customer": {

    "firstName": "Bashar",

    "lastName": "Saleh",

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

    "phone": "971567824730"

  }

}

SAMPLE RESPONSE BODY

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

 

{

    "success": true,

    "elapsed": 468,

    "result": {

        "checkoutId": "1584154845799418134",

        "merchantId": "15b9b327ce8bfa09",

        "merchantName": "amazon.com",

        "referenceId": "CHK-0056",

        "currency": "AED",

        "grandtotal": 0,

        "status": "PENDING",

        "checkoutKey": "8d1796e88bbc37ef73a9edc3d3d85c0267c5c0bb3feb56dc"

    }

}

 

 


 

GET CHECKOUT REQUEST

This request is used to inquire about the status of a PointCheckout payment, usually after a user is redirected back to the merchant website.

REQUEST URL

Request URL

$BASE_URL/api/v1.0/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

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 with this 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 the 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.

status

String

Current checkout status. (See Checkout Request)

checkoutKey

String

Checkout Key used for redirecting user to the checkout page to complete payment. (See Redirect)

error

String

An error message explaining error if “success” is false

SAMPLE SUCCESSFUL RESPONSE BODY

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

 

{

    "success": true,

    "elapsed": 468,

    "result": {

        "checkoutId": "1584154845799418134",

        "merchantId": "15b9b327ce8bfa09",

        "merchantName": "amazon.com",

        "referenceId": "CHK-0056",

        "currency": "AED",

        "grandtotal": 100,

        "status": "PAID",

        "checkoutKey": "8d1796e88bbc37ef73a9edc3d3d85c0267c5c0bb3feb56dc"

    }

}

 

SAMPLE ERROR RESPONSE BODY

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

 

{

    "success": false,

    "elapsed": 150,

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

}

 


 

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

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

CANCELLED

User canceled the checkout process and returned to merchant page.

 


 

PAYMENT PAGE REDIRECT

Upon a successful NEW CHECKOUT REQUEST, the 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 (See 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  July 9, 2019