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 using PointCheckout / Card” option is presented.

  2. On submitting the “Pay using Pointcheckout / Card” 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 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 Card payment or Pay using PointCheckout.

  2. When the payment method to be used is POINTCHECKOUT, PointCheckout Logo from https://www.pointcheckout.com/en/image/logo.png must be presented to the customer at the payment page

  3. Should support the following configuration options:

    1. Support for Test / Live environments.

    2. Ability to restrict payment to users from specific countries

    3. Ability to restrict payment to users from specific user groups

    4. 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; Test and Production. Throughout the API, they will be referred to as $BASE_URL and the admin can select the current environment in the administrator settings screen.

TEST ENVIRONMENT

Base URL

https://api.test.pointcheckout.com


PRODUCTION ENVIRONMENT

Base URL

https://api.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/mer/v1.2/checkouts

METHOD TYPE

Request Type

POST

HEADER PARAMETERS

HEADER

DETAILS

X-PointCheckout-Api-Key

The merchant API key.

X-PointCheckout-Api-Secret

The Merchant API Secret.

Content-Type

application/json

REQUEST BODY

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

PARAMETER

TYPE

DETAILS

transactionId

String

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

resultUrl

String

URL to redirect user to after a successful or failed payment. ( See Get Checkout Request)

amount(1)

Decimal

The amount customers must pay. (Required)

subtotal(2)

Decimal

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

shipping

Decimal

Total value of shipping. (Optional) 

handling

Decimal

Handling fees for the order. (Optional)

tax

Decimal

Tax value on order. (Optional)

discount

Decimal

Value of discount applied to Subtotal. (Optional)

currency

String

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

deviceReference

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. (Optional)

paymentMethods(3) 

Array

Array containing payment methods to be available at the payment page. When left empty all available options will show. When provided the payment methods order in the payment page will follow the same order passed in this parameter. (Optional)

defaultPaymentMethod

Enum

Active payment method when opening the payment page. When left empty the default for your account at PointCheckout will be used. (Optional)

generateQR

Boolean

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

qrSize

Integer

the size of the QR image in pixels, default is 300. (Optional)

sendCustomerEmail

Boolean

Indicator to send an email to the customer containing the payment link, this will only work if a valid email address  is passed in the customer request

sendCustomerSms

Boolean

Indicator to send an sms to the customer containing the payment link, this will only work if a valid phone number is passed in the customer request

expiryInMinutes

Integer

Number of minutes the payment will remain available, after that the payment will expire.. (Optional)

languageCode

String

2 Letter ISO 639-1 language code, for viewing the payment page. When the language is not supported, the system will revert to the default. (Optional)

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 quantity of this item. (Required)

customer

Object

Details of the customer making the purchase. (Required)

firstName

String

Customer first name. (Optional)

lastName

String

Customer last name. (Optional)

email(4) 

String

Customer email address. (Optional)

phone(4)

String

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

billingAddress

Object

Customer billing address. (Optional)

name

String

Billing address name (Optional)

address1

String

Billing address line 1 (Optional)

address2

String

Billing address line 2 (Optional)

city

String

Billing address city (Optional)

state

String

Billing address state (Optional)

zip

String

Billing zip code (Optional)

country

String

Billing address country (3 letter ISO country code) (Optional)

shippingAddress

Object

Customer billing address (Optional)

name

String

Shipping address name (Optional)

address1

String

Shipping address line 1 (Optional)

address2

String

Shipping address line 2 (Optional)

city

String

Shipping address city (Optional)

state

String

Shipping address state (Optional)

zip

String

Shipping zip code (Optional)

country

String

Shipping address country (3 letter ISO country code) (Optional)

  1. Grand Total = “subtotal” + “shipping” + “tax” – “discount”

  2. Subtotal = Sum (item total) for all items.

  3. Please consult with PointCheckout team on available payment methods for your account.

  4. A valid customer email or phone number is required.

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.

error

String

An error message explaining error if “success” is false

result

Object

Result Object

id

String

Unique PointCheckout ID associated with this checkout.

displayId

String

Checkout human readable short key, serves as an easier reference to the 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.

orderId

String

Order 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.

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 the customer must pay.

cash

Decimal

Cash amount to be collected from Shopper

status

String

Current checkout status. (See Checkout Statuses)

branchId

String

The PointCheckout branch ID associated with this checkout.

branchName

String

The PointCheckout branch name associated with this checkout.

customerFirstName

String

Customer’s first name

customerLastName

String

Customer’s last name

customerEmail

String

Customer’s email address 

customerPhone

String

Customer’s phone number

deviceReference

String

Merchant device reference, the same as provided in the request

firebaseDatabase

String

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

firebaseCollection

String

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

firebaseDocument

String

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

redirectUrl

String

URL for the customer payment redirect. ( See Payment Page Redirect)

redirectUrlShort

String

URL for the customer payment redirect. ( See Payment Page Redirect)

timestamp

DateTime

The date time of creating the payment in ISO8601 format (yyyy-MM-ddTHH:mm:ss.SSSZZ).

base64QR

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.

{

    "transactionId": "CHK-100000000",

    "currency": "JOD",

    "amount": "100.0",

    "subtotal":"100.0",

    "shipping": "2.0",

    "tax":"2.0",

    "discount":"4.0",

    "resultUrl":"https://www.example.com/payment/redirect",

    "defaultPaymentMethod":"CARD",

    "paymentMethods":["POINTCHECKOUT", "CARD"],

    "deviceReference": "POS-01",

    "generateQR":false,

    "expiryInMinutes":1440,

"items": [{

        "name": "Laptop XYZ case",

        "sku": "1234",

        "quantity": 2,

        "total": 90

    }, {

        "name": "iPhone 7 Cover",

        "sku": "4434",

        "quantity": 1,

        "total": 10

    }],

    "customer": {

        "id":"CID1234567",

        "firstName":"Bashar",

        "lastName":"Saleh",

        "email":"[CUSTOMER EMAIL]",

        "phone" : "[CUSTOMER PHONE]",

        "billingAddress":[{

            "name":"[CUSTOMER NAME]",

            "address1":"[ADDRESS 1]",

            "address2":"[ADDRESS 2]",

            "city":"[CITY]",

            "country":"[COUNTRY 3-LETTER ISO CODE]"

        }],

        "shippingAddress":[{

            "name":"[CUSTOMER NAME]",

            "address1":"[ADDRESS 1]",

            "address2":"[ADDRESS 2]",

            "city":"[CITY]",

            "country":"[COUNTRY 3-LETTER ISO CODE]"

        }]

    },

    "sendCustomerEmail":false,

    "sendCustomerSms":false

}



SAMPLE RESPONSE BODY

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

{

    "success": true,

    "elapsed": 703,

    "result": {

        "id": "1676670774124267597",

        "displayId": "QQ0RDQ",

        "referenceId": "CHK-100000000",

        "orderId": null,

        "merchantId": "1599726225179342576",

        "merchantName": "Test store",

        "currency": "JOD",

        "grandtotal": 100.0,

        "cash": 0,

        "status": "PENDING",

        "paymentMethod": null,

        "branchId": null,

        "branchName": null,

        "customerEmail": "bashar@pointcheckout.com",

        "customerFirstName": "Bashar",

        "customerLastName": "Bashar",

        "customerPhone": "971567824730",

        "deviceReference": "POS-01",

        "firebaseCollection": "pc-checkout",

        "firebaseDatabase": "pc-test-734bc",

        "firebaseDocument": "P3HmB-noOP-_P5oMSR95zRhbSlVncKMs",

        "redirectUrl": "https://pay.test.pointcheckout.com/checkout/edb65423c077916b966...",

        "redirectUrlShort": "http://pcout.co/c/dEHizoxw",

        "timestamp": "2020-09-01T22:04:14.592Z",

        "base64QR": null

    }

}



SAMPLE ERROR RESPONSE BODY

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


{

    "success": false,

    "elapsed": 175,

    "error": "A checkout already exists for this merchant with transaction id 'CHK-100000000'"

}


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/mer/v1.2/checkouts/$CHECKOUT_ID

METHOD TYPE

Request Type

GET

HEADER PARAMETERS


HEADER

DETAILS

X-PointCheckout-Api-Key

The merchant API key.

X-PointCheckout-Api-Secret

The Merchant API Secret.

Content-Type

application/json

QUERY PARAMETERS

The Request URL may include the below parameters

PARAMETER

TYPE

DETAILS

generateQR

Boolean

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

qrSize

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.

error

String

An error message explaining error if “success” is false

result

Object

Result Object

id

String

Unique PointCheckout ID associated with this checkout.

displayId

String

Checkout human readable short key, serves as an easier reference to the 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.

orderId

String

Order 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.

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 the customer must pay.

cash

Decimal

Cash amount to be collected from Shopper

status

String

Current checkout status. (See Checkout Statuses)

paymentMethod

String

Payment method used while processing the payment.

branchId

String

The PointCheckout branch ID associated with this checkout.

branchName

String

The PointCheckout branch name associated with this checkout.

customerFirstName

String

Customer’s first name

customerLastName

String

Customer’s last name

customerEmail

String

Customer’s email address 

customerPhone

String

Customer’s phone number

deviceReference

String

Merchant device reference, the same as provided in the request

firebaseDatabase

String

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

firebaseCollection

String

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

firebaseDocument

String

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

redirectUrl

String

URL for the customer payment redirect. ( See Payment Page Redirect)

redirectUrlShort

String

URL for the customer payment redirect. ( See Payment Page Redirect)

timestamp

DateTime

The date time of creating the payment in ISO8601 format (yyyy-MM-ddTHH:mm:ss.SSSZZ).

base64QR

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": 703,

    "result": {

        "id": "1676670774124267597",

        "displayId": "QQ0RDQ",

        "referenceId": "CHK-100000000",

        "orderId": null,

        "merchantId": "1599726225179342576",

        "merchantName": "Test store",

        "currency": "JOD",

        "grandtotal": 100.0,

        "cash": 0,

        "status": "PENDING",

        "paymentMethod": null,

        "branchId": null,

        "branchName": null,

        "customerEmail": "bashar@pointcheckout.com",

        "customerFirstName": "Bashar",

        "customerLastName": "Bashar",

        "customerPhone": "971567824730",

        "deviceReference": "POS-01",

        "firebaseCollection": "pc-checkout",

        "firebaseDatabase": "pc-test-734bc",

        "firebaseDocument": "P3HmB-noOP-_P5oMSR95zRhbSlVncKMs",

        "redirectUrl": "https://pay.test.pointcheckout.com/checkout/edb65423c077916b966...",

        "redirectUrlShort": "http://pcout.co/c/dEHizoxw",

        "timestamp": "2020-09-01T22:04:14.592Z",

        "base64QR": null

    }

}



SAMPLE ERROR RESPONSE BODY

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


{

    "success": false,

    "elapsed": 60,

    "error": "Checkout not found for API merchant"

}


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.

AUTHORIZED

The payment has been authorized, a subsequent Capture or Cancel payment API call is expected before the checkout Expires.

PAID

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

FAILED

Payment failed due to payment failure. PointCheckout failed to recover such a checkout process.

CANCELLED

User cancelled the checkout process and returned to the merchant page.

EXPIRED

Checkout has expired without being processed

REFUNDED

Checkout has been fully refunded to the Shopper

PARTIALLY_REFUNDED

Checkout have been partially refunded to the shopper


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 resultyUrl passed in the “New Checkout” request. The response contains the following URL encoded parameters:

PARAMETER

DETAILS

checkoutId

The PointCheckout checkout ID that was processed.

reference

Merchant unique reference ID for this checkout