# Charges

# List charges

Returns a list of charge objects with most recently created charges first. Charges are filtered based on the parameters specified. Pagination is supported and number of charges per page can be specified using the arguments - page and limit.

Endpoint GET /charges

Query parameters

Parameter Description Example
method Customer's payment method in-bank-transfer
status Current charge status completed
startDate Earliest charge creation time in UTC 2021-12-14T02:10:00
endDate Latest charge creation time in UTC 2021-12-14T02:10:00
customerCurrency Customer's currency SGD
customerEmail Customer's email customer@gmail.com
customerPhone Customer's phone number with '+' stripped. Used for filtering charges only if the customerEmail parameter is not specified. 6512345678901
page Page number of results. The value is 1 by default. 2
limit Limit on the number of objects returned. The value is 10 by default and can range from 1 to 50 25

Request example

curl
-H "Content-Type: application/json"
-u {API_KEY}:{API_SECRET}
"https://api.xanpay.com/charges?method=in-bank-transfer "

Response example

{
  "charges": [
    {
      "id": "61b80f7921fa8a00112e974c",
      "customer": {
        "id": "5fd6eab02d02960011030e73",
        "email": "customer@gmail.com",
        "phone": "+6512345678901"
      },
      "destination": {
        "account": "+6587808619",
        "nonce": "kohlrabi",
        "qrCode": "",
        "accountName": "",
        "bank": "ICIC0000001"
      },
      "notifyPayload": "eyJvcmRlcklkIjogIjI1MSJ9",
      "merchantAmount": 5000,
      "merchantCurrency": "INR",
      "method": "in-bank-transfer",
      "customerAmount": 5000,
      "customerCurrency": "INR",
      "status": "completed",
      "createdAt": "2021-12-14T03:28:57.796Z",
      "updatedAt": "2021-12-14T04:29:57.078Z"
    }
  ],
  "pagination": {
    "totalPages": 132,
    "total": 132,
    "currentPage": 1
  }
}

# Get a charge

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

Endpoint GET /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": {
    "id": "5fd6eab02d02960011030e73",
    "email": "customer@gmail.com",
    "phone": "+6512345678901"
  },
  "merchantAmount": 150,
  "merchantCurrency": "HKD",
  "method": "paynow",
  "customerAmount": 26.24,
  "customerCurrency": "SGD",
  "status": "completed",
  "destination": {
    "account": "+6587767191",
    "nonce": "cantaloupe",
    "qrCode": "00020101021126380009SG.PAYNOW010100211+658776719103010520400005303702540510.005802SG5902NA6009Singapore62140110cantaloupe6304A97B"
  },
  "notifyPayload": "eyJvcmRlcklkIjogIjI1MSJ9",
  "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

# Charge object

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

Attributes

Parameter Description
id Unique charge ID
customer Customer object including email and phone
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
refunds A list of refunds
orders A list of orders
notifyPayload Custom string to be saved as a part of the charge object Note: we recommend encoding in base64
sessionId Unique session ID. Exist if charge is created with sessions
createdAt Timestamp of when the charge was created
updatedAt Timestamp of when the charge was updated

# Charge status

Status Description
pending Waiting for the customer to transfer funds
completed Customer has sent the 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