Create Bill - Quantum Metal Developer Docs

Create a bill.

POST /v1/bill/create HTTP/1.1
Content-Type: application/json
Key: {API Key}
Sign: {Signature}

{
    "amount": 0.00,
    "merchantReference": "string",
    "callbackUrl": "string",
    "redirectUrl": "string"
}

Request

Body

application/json

Property	Type	Description
`amount`	number	The amount of the bill.
`merchantReference`	string	Optional. Your own reference number of the bill. Note that we do not check for uniqueness. If not specified, a reference number will be generated for you.
`callbackUrl`	string	The callback URL of the bill. This URL will be called upon bill status is final.
`redirectUrl`	string	The redirect URL of the bill. This should be your web page URL (or deeplink URL) where your customer will be redirected to upon payment complete.

Response

Body

application/json

{
  "code": 0,
  "message": "string",
  "data": {
    "billAmount": 0.0,
    "requireGCAmount": 0.0,
    "currency": "string",
    "merchantReference": "string",
    "billId": "string",
    "billUrl": "string",
    "expiredOn": 1706600000000
  }
}

Property	Type	Description
`code`	number	The response code. Refer to ENUM Definition.
`message`	string	The response message.
`data`	object	The response data.
`data.billAmount`	number	The amount of the bill.
`data.requireGCAmount`	number	The amount of Gold Convert required to pay the bill.
`data.currency`	string	The currency of the bill.
`data.merchantReference`	string	Your own reference number of the bill.
`data.billId`	string	The unique ID of the bill. This ID will be required for requery and other operations.
`data.billUrl`	string	The URL of the bill that you will have to redirect the customer to or encode into a QR Code for customer to scan on their mobile device or QMGold app.
`data.expiredOn`	number	The timestamp (in unix milliseconds) of the bill expiry.

Redirect

After the customer has completed the payment, they will be redirected to the redirectUrl that you have specified in the request.

It is not safe to rely on the Redirect to determine the status of the bill as you might be at risk of spoofing. You should always use the Requery Bill API to check the status of the bill.

Query Parameters

The following query parameters will be appended to the redirectUrl:

{redirectUrl}?billId={billId}&merchantReference={merchantReference}&status={status}

Parameter	Type	Description
`billId`	string	The unique ID of the bill. This ID will be required for requery and other operations.
`merchantReference`	string	Your own reference number of the bill.
`status`	number	The status of the bill. Refer to ENUM Definition.

Callback

Upon bill status is final, we will call the callbackUrl that you have specified in the request.

It is not safe to rely on the Callback to determine the status of the bill as you might be at risk of spoofing. You should always use the Requery Bill API to check the status of the bill.

Body

The following JSON will be sent to the callbackUrl:

application/json

{
  "billId": "string",
  "merchantReference": "string",
  "requestReference": "string",
  "paymentReference": "string",
  "billAmount": "string",
  "currency": "string",
  "status": 0,
  "statusName": "string",
  "isFinal": bool,
  "dateTime": 1706600000000,
}

Property	Type	Description
`billId`	string	The unique ID of the bill. This ID will be required for requery and other operations.
`merchantReference`	string	Your own reference number of the bill.
`requestReference`	string	The request reference number of the request.
`paymentReference`	string	The payment reference number of the payment.
`billAmount`	number	The amount of the bill.
`currency`	string	The currency of the bill.
`status`	number	The status of the bill. Refer to ENUM Definition.
`statusName`	string	The status name of the bill.
`isFinal`	bool	Whether the status of the bill is final.
`dateTime`	number	The timestamp (in unix milliseconds) of the bill status update.

Callback Acknowledgement

You should always return a 200 OK response to acknowledge the callback. If you do not return a 200 OK response, we will retry the callback up to 5 times.

Bind Customer

This guide provides the steps to bind registered customer in the platform.

Requery Bill

Checks the latest status of a bill, at any time.