# Charges

WARNING

Not all REST API endpoints are available to all users. If you need 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. Verification code is acquired in phone verification

Endpoint

POST /charges

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 Any items you wish to be captured in the receipt
notifyUrl none An endpoint to call after the charge is completed (see webhooks)
notifyPayload none A payload to be sent along with the order completed notification to the notifyUrl endpoint (see webhooks)
hash none Enables the secure mode

Response

Response contains a charge object

Request Example

curl
-H "Content-Type: application/json"
-u {API_KEY}:{API_SECRET}
-X POST
-d 
  '{
    "verificationCode": "1Xbn3jvam8j4Xj10fakfdn1jdnald",
    "email": "john007@gmail.com",
    "merchantAmount": 150, 
    "merchantCurrency": "HKD", 
    "method": "paynow", 
    "orders": [
      {
        "id": "1",
        "name": "Laptop", 
        "quantity": 1, 
        "amount": 150
      }
    ],
    "notifyUrl": "http://example.com", 
    "notifyPayload": "{\"orderId\": \"123\"}"
  }'
"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.

Endpoint

POST /charges/{id}

Response

Response contains a charge object

Request Example

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

Response

{
  "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

# Generate a hash to enable the secure mode

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

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 Any items you wish to be captured in the receipt

Response

Response contains a hash - a string that can be used as a parameter when initializing our widget, or using the REST API to create a charge.

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 Status of the charge. Please refer to charge statuses
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 statuses

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

Ths object contains Bank/wallet information where the customer must transfer funds

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