# 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
refundedAmount Amount for which refund has been completed in customer currency
refunds Array of refund objects. Please refer to refunds
subscriptionId ID of the subscription into which the customer is enrolled and towards which this payment is being made
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
notifyPayload Custom string to be saved as a part of the charge object Note: we recommend encoding in base64

# 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