XanPay Documentation

# Advanced APIs

XanPay provides advanced APIs to high-volume customers. Access to these is restricted to a limited number of partners who have transacted at least USD 2m per month for 6 months. If your account is eligible, and you wish to dedicate designer and developer resources to this project, please contact us through the dashboard (opens new window).

In your custom interface design, we require that predefined user interface strings are used. You can access these strings through our translations API. You would need to implement the following steps for each charge:

  1. Verify customer's phone number
  2. Secure transaction with a hash
  3. Create a charge

# Translations

This API endpoint is restricted to a limited number of high-volume partners. If your account is eligible, please contact us through the dashboard (opens new window).

Returns user interface strings in the language corresponding to the requested locale. We require that you use these translations for your interface.

Endpoint GET /translations

Url parameters

Parameter Default Description
locale none locale you want to use

Available locales

Locale Language
en English
zh Chinese
th Thai

Request example

curl 
-H "Content-Type: application/json"
-u {API_KEY}:{API_SECRET}
"https://api.xanpay.com/translations?locale=en"

Response example

{
    "translation": {
        "mainPage": {
            "cancelled": "Your pending charge has been cancelled",
            "title": "You are paying",
            "country": {
                "label": "Country"
            },
            ...
}

# Customers

Before creating a charge, an API client is required to facilitate phone verification, by doing the following steps in order:

  1. Initiate phone verification
  2. Verify phone number

# Initiate phone verification

This API endpoint is restricted to a limited number of high-volume partners. If your account is eligible, please contact us through the dashboard (opens new window).

Initiates verification of a customer's phone number by sending an One-Time Password(OTP) to the number.

Endpoint POST /customers/phone/verification

Payload attributes

Parameter Default Description
phone none An object with code & phone attributes

Request example

curl
-H "Content-Type: application/json"
-u {API_KEY}:{API_SECRET}
-X POST
 -d '{"phone": {"code": "+65", "phone": "87767192"}}'
"https://api.xanpay.com/customers/phone/verification"

Response example

{
   "isSuccess": true
}

# Verify phone number

This API endpoint is restricted to a limited number of high-volume partners. If your account is eligible, please contact us through the dashboard (opens new window).

Verifies customer's phone number and returns a verification code which is valid for 5 minutes and could be used to initiate a charge. To do so, it requires the a customer's phone number and a verification code that the customer has entered.

Endpoint POST /customers/phone/verify

Payload attributes

Parameter Default Description
phone none An object with code & phone attributes
code none OTP received from POST /customers/phone/verification

Request example

curl
-H "Content-Type: application/json"
-u {API_KEY}:{API_SECRET}
-X POST
 -d '{"phone": {"code": "+65", "phone": "87767192"}, "code": "123456"}'
"https://api.xanpay.com/customers/phone/verify"

Response example

{
   "verificationCode": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwaG9uZU51bWJlciI6Iis2NTEyMzQ1Njc4OTAxIiwicGhvbmUiOnsiY29kZSI6Iis2NSIsInBob25lIjoiMTIzNDU2Nzg5MDEifSwiY3VzdG9tZXIiOnRydWUsImp3dGlkIjoiZDVhNDJhMzUtM2I2Ny00MGY0LTg3Y2YtOTgyZTBhNmYyMDkwIiwiaWF0IjoxNjM4MzQxMzMyLCJleHAiOjE2MzgzNDMxMzJ9.BeNOlbOkBOBp99uhFbWEGbVMHxXeqAI7Owv-ed7j990"
}

# Charge creation

# Create a charge

This API endpoint is restricted to a limited number of high-volume partners. If your account is eligible, please contact us through the dashboard (opens new window).

Initiates a charge on user's behalf. Its response contains a destination object which specifies payment instructions to be followed by the customer to make the payment.

To create a charge, you need the following:

  1. Verification code: acquired during phone verification
  2. Hash: acquired when enabling secure mode

Endpoint POST /charges

Response Charge object

Payload attributes

Parameter Default Description
verificationCode none A code received during phone verification
email none Customer's email
merchantAmount none Amount to be charged in merchant's' currency
merchantCurrency none Merchant's currency
method none Customer's payment method
orders none A list of orders
notifyPayload none Custom string to be saved as a part of the charge object Note: we recommend encoding in base64
hash none Enables secure mode

Request example

curl
-H "Content-Type: application/json"
-u {API_KEY}:{API_SECRET}
-X POST
-d
  '{
    "verificationCode": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwaG9uZU51bWJlciI6Iis2NTEyMzQ1Njc4OTAxIiwicGhvbmUiOnsiY29kZSI6Iis2NSIsInBob25lIjoiMTIzNDU2Nzg5MDEifSwiY3VzdG9tZXIiOnRydWUsImp3dGlkIjoiZDVhNDJhMzUtM2I2Ny00MGY0LTg3Y2YtOTgyZTBhNmYyMDkwIiwiaWF0IjoxNjM4MzQxMzMyLCJleHAiOjE2MzgzNDMxMzJ9.BeNOlbOkBOBp99uhFbWEGbVMHxXeqAI7Owv-ed7j990",
    "email": "john007@gmail.com",
    "merchantAmount": 150,
    "merchantCurrency": "HKD",
    "method": "paynow",
    "orders": [
      {
        "id": "1",
        "name": "Laptop",
        "quantity": 1,
        "amount": 150
      }
    ],
    "notifyPayload": "eyJvcmRlcklkIjogIjI1MSJ9"
  }'
"https://api.xanpay.com/charges"

Response example

{
  "id": "6f7d1cc4d56bef00123b068f",
  "customer": {
    "id": "5fd6eab02d02960011030e73",
    "email": "customer@gmail.com",
    "phone": "+6512345678901"
  },
  "merchantAmount": 150,
  "merchantCurrency": "HKD",
  "method": "paynow",
  "customerAmount": 26.24,
  "customerCurrency": "SGD",
  "status": "pending",
  "destination": {
    "account": "+6587767191",
    "nonce": "cantaloupe",
    "qrCode": "00020101021126380009SG.PAYNOW010100211+658776719103010520400005303702540510.005802SG5902NA6009Singapore62140110cantaloupe6304A97B"
  },
  "notifyPayload": "eyJvcmRlcklkIjogIjI1MSJ9",
  "createdAt": 1588654478993,
  "updatedAt": 1588654478993,
  "isDuplicate": true,
}

# Secure mode

This API endpoint is restricted to a limited number of high-volume partners. If your account is eligible, please contact us through the dashboard (opens new window).

Generates a hash of critical payment parameters that is used to further secure transactions.

A hash is a string which initializes Secure Mode. Once the hash is generated, it must be sent as a parameter when creating a charge via the API.

Endpoint POST /charges/hash

Payload attributes

Parameter Default Description
merchantAmount none Amount to be charged in merchant's' currency
merchantCurrency none Merchant's currency
orders none A list of orders

Response hash

Request Example

curl
-H "Content-Type: application/json"
-u {API_KEY}:{API_SECRET}
-X POST
-d
  '{
    "merchantAmount": 150,
    "merchantCurrency": "HKD",
    "orders": [
      {
        "id": "1",
        "name": "Laptop",
        "quantity": 1,
        "amount": 150
      }
    ]
  }'
"https://api.xanpay.com/charges/hash"

Response example

MI0c0SPmr6oOfr731aXcqx84jrQFnph23P3AwIC72Ls=