# Charges

Some API endpoints are restricted to a limited number of partners. If you require access to functionality like charge creation, please contact us through the dashboard (opens new window).

# Create a charge

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 String to be sent with order status changes to registered webhooks. 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": "bc7d7cg2a56bec00127b069f",
  "merchantAmount": 150,
  "merchantCurrency": "HKD",
  "method": "paynow",
  "customerAmount": 26.24,
  "customerCurrency": "SGD",
  "status": "pending",
  "destination": {
    "account": "+6587767191",
    "nonce": "cantaloupe",
    "qrCode": "00020101021126380009SG.PAYNOW010100211+658776719103010520400005303702540510.005802SG5902NA6009Singapore62140110cantaloupe6304A97B"
  },
  "createdAt": 1588654478993,
  "updatedAt": 1588654478993,
  "isDuplicate": true,
  "cancelToken": "b383402d494dd2effb704ede581af3c9"
}

# Get a charge

Returns charge details including a charge object which includes a destination object.

Endpoint POST /charges/{id}

Response Charge object

Request example

curl
-H "Content-Type: application/json"
-u {API_KEY}:{API_SECRET}
"https://api.xanpay.com/charges/6f7d1cc4d56bef00123b068f"

Response example

{
  "id": "6f7d1cc4d56bef00123b068f",
  "customer": "bc7d7cg2a56bec00127b069f",
  "merchantAmount": 150,
  "merchantCurrency": "HKD",
  "method": "paynow",
  "customerAmount": 26.24,
  "customerCurrency": "SGD",
  "status": "completed",
  "destination": {
    "account": "+6587767191",
    "nonce": "cantaloupe",
    "qrCode": "00020101021126380009SG.PAYNOW010100211+658776719103010520400005303702540510.005802SG5902NA6009Singapore62140110cantaloupe6304A97B"
  },
  "createdAt": 1588654478993,
  "updatedAt": 1588654488993
}

# Cancel a charge

Cancels a Pending charge on user's behalf.

Endpoint PATCH /charges/{id}/cancel

Response true if the status was changed successfully

Request example

curl
-H "Content-Type: application/json"
-u {API_KEY}:{API_SECRET}
-X PATCH
"https://api.xanpay.com/charges/6f7d1cc4d56bef00123b068f/cancel"

Response

true

# Secure mode

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=

# Charge object

Below you can find description for each charge's field.

Attributes

Parameter Description
id Unique charge ID
customer Customer ID
merchantAmount Amount charged in merchant's currency
merchantCurrency Merchant's currency
method Customer's payment method
customerAmount Amount charged in customer's currency
customerCurrency Customer's currency, depends on the method
status Current charge status
destination Bank/wallet information where the customer must transfer funds. Please refer to destination
createdAt Timestamp of when the charge was created
updatedAt Timestamp of when the charge was updated
isDuplicate Boolean; if the charge creation is requested with the same parameters (except the orders parameter) true, otherwise false
cancelToken A token that allows cancellation of Pending charges

# Charge status

Status Description
pending Waiting for the customer to transfer funds
completed Customer has sent the funds
refund_initiated Merchant initiated a refund
refund_confirmed XanPay confirmed the refund. An sms with instructions is sent to the customer
refund_completed The customer provided refund information. XanPay is transferring funds
expired Expired due to non-payment by the customer
cancelled The charge is cancelled before a payment was made

# Destination object

This object contains payment instructions. It identifies the bank/wallet where the customer must transfer funds to complete the transaction.

Parameter Description
qrCode QR code that could be scanned by a payment method.
account Account ID. Could be a bank account or a phone number.
nonce Unique word a customer must attach to his payments