Skip to main content

Mobile SDK payment

On this page we describe the steps required to initiate and verify a payment via the PointCheckout payment gateway for mobile based applications using the PointCheckout mobile SDKs.

How it works#

Three steps are required to accept payments via the PointCheckout payment gateway for mobile-based applications using the PointCheckout SDKs:

  1. Create a new Mobile Checkout
  2. Initiate the PointCheckoutClient using the checkoutKey received in the response
  3. On callback, query the API for the payment status

The diagram below shows the overall flow to be used in order to accept payments using the PointCheckout web integration

Website integration flow

Step 1: Create a new checkout#

SERVER API CALL

API calls made to the PointCheckout API endpoints should be made from your server. You should NEVER include your API keys in your mobile application. A mallicious user can gain access to your account if those keys are exposed.

When the customer is ready to pay, create a new mobile checkout by making a call from your server to POST /checkout/mobile. In your request, you must include the following required parameters:

ParameterDescription
requestIdA unique Identifier for this request, can be used later to query the status on the checkout
orderIdThis can be the order ID. Must match any reference shown to the user during checkout / order history
currencyISO 4217 Currency Code (3 letter currency code)
amountA postive decimal number representing the amount customer should pay
customerThe details of the customer making teh payment
billingAddressThe customer billing address
deliveryAddressThe address where the service will be delivered
itemsAn array of the items associated with this order

Here's an example of how you would create a new checkout for 100.00 AED:

curl
curl -L -X POST "https://api.test.pointcheckout.com/mer/v2.0/checkout/mobile" \-H "X-POINTCHECKOUT-KEY: YOUR_X-POINTCHECKOUT-KEY" \-H "X-POINTCHECKOUT-SECRET: YOUR_X-POINTCHECKOUT-SECRET" \-H "content-type: application/json" \-d '{  "requestID": "EXAMPLE-123.1",  "orderID": "EXAMPLE-123",  "currency": "AED",  "amount": 100.00,  "customer": {...},  "billingAddress": {...},  "deliveryAddress": {...},  "items": [...]}'
Failed or cancelled orders

If a payment fails or customer cancels the the payment, you cannot reuse the same requestId. You can however use the same orderId to create a new checkout.

Step 2: Initiate the PointCheckoutClient#

The response from Step 1 above will result in a new checkout being succesffully created for your merchant account. Once received, use the checkoutKey to initiate the client

200 Response
{  "success": true,  "elapsed": 12,  "result": {    "id": "1653241101733169556",    "requestId": "EXAMPLE-123.1",    "orderId": "EXAMPLE-123",    "currency": "AED",    "amount": 100.00,    "status": "PENDING",    "checkoutKey": "90ed4298f15d46df994fd1cfbbec5aa24390e811295cf8b5",    ...  }}

To learn more about the specific mechanism to use our SDKs, you can view the instructions for each of the SDK platforms below:

Android

Image alt text
Android

iOS

Image alt text
iOS

Step 3: Verifying payment status#

Once the payment process has completed (regardless of status), the SDK will excute the callback function passed to the SDK during the client initialization in Step 2.

To verify the payment status, make an API call from your server to GET /checkout/{checkoutId}. The checkoutId is the ID received in the server response in Step 1

Here's an example of how you can query the status of checkout with id 1653241101733169556:

curl
curl -L -X GET "https://api.test.pointcheckout.com/mer/v2.0/checkout/1653241101733169556" \-H "X-POINTCHECKOUT-KEY: YOUR_X-POINTCHECKOUT-KEY" \-H "X-POINTCHECKOUT-SECRET: YOUR_X-POINTCHECKOUT-SECRET" \-H 'Content-Type: application/json'
CONFIRMING CHECKOUT IS PAID

A paid checkout will have the status of PAID. If the checkout has a status other than paid, you should either display and error or take the user back to the checkout flow.

Checkout status values#

Below is a list of available status codes that may be provided via the PointCheckout API to describe the status of a checkout:

STATUSDETAILS
PENDINGNew Checkout. User has not completed the payment.
AUTHORIZEDThe payment has been authorized. A subsequent CAPTURE or CANCEL API call is expected before expiry.
PAIDThis status is effective when a customer has successfully completed the payment associated with this checkout.
FAILEDPayment failed due to payment failure. PointCheckout failed to recover such a checkout process.
CANCELLEDUser cancelled the checkout process and returned to the merchant page.
EXPIREDCheckout has expired without being processed
REFUNDEDCheckout has been fully refunded to customer
PARTIALLY_REFUNDEDCheckout have been partially refunded to customer

Step 4: Test the Integration#

Once your integration is ready, you can use the below test card details to verify your integration

  • Number: 4242 4242 4242 4242
  • Expiry date: 12/25
  • CVV: 100
  • Name: TEST USER
GO LIVE REQUIREMENTS

Before receiving your live API Key and Secret, make sure your web application is compliant with our website requirements. To learn more, view the Website go-live checklist.