pay

2026-06-10 05:48

POST /v2/payments/pay

The pay API is called by the POS to create a payment request. Ensure that the payment terminal is ready to receive payment requests before calling this API.

Structure

A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see:

Request parameters

Parameter name	Type	Required	Description
paymentRequestId	String	Yes	The unique ID that is defined by a POS provider to identify a payment request. Maximum length: 64 characters. Only letters (a-z, A-Z), numbers (0-9), and underscores (_) are allowed. Note: This parameter is unique for each store. This parameter is an idempotency key field. For payments that are initiated with the paymentRequestId, the same result is to be returned. For details about API idempotency, see Idempotency.
paymentMethod	String	Yes	The payment method that is used to collect the payment by the merchant or acquirer. For the supported payment methods, see Supported payment methods.
paymentAmount	Amount	Yes	The payment amount that the merchant requests to receive in the order currency.
originalMerchantOrderId	String	No	The original and unique ID on the merchant end to identify an order. Maximum length: 255 characters
originalMerchantStoreId	String	No	The original and unique ID on the merchant end to identify a store. Maximum length: 255 characters

Amount

Parameter name

Type

Required

Description

value

Integer

Yes

The amount value in the currency's smallest unit. For example, 10000 means 100.00 in SGD.

Value range: 0-2147483647

currency

String

Yes

The 3-character currency code that follows ISO-4217. For example, USD.

Maximum length: 3 characters

Response parameters

Parameter name	Type	Required	Description
result	Result	Yes	The result of the API call.
paymentId	String	Yes	The unique ID that is defined by a POS provider to identify a payment and consistent with the paymentId in transaction reports.
paymentReceipt	Receipt	No	The receipt information that is provided to merchants and buyers after the payment is successful. The information is provided in the key-value structure. In card payment scenarios, values are returned through customerReceipt and cashierReceipt. In QR code payment scenarios, paymentReceipt returns empty values. copy { "cashierReceipt": "{\"acquirerMerchantId\":\"0000000001XXXXX\",\"acquirerProcessTime\":\"2025-05-13T13:19:51Z\",\"acquirerTerminalId\":\"911XXXXX\",\"aid\":\"A00000000XXXXX\",\"applicationCryptogram\":\"5AC388057A1XXXXX\",\"applicationLabel\":\"VISA CREDIT\",\"approvalCode\":\"0XXXXX\",\"cardBrand\":\"VISA\",\"cardNo\":\"47617300000XXXXX\",\"cvm\":\"NO_CVM\",\"posEntryMode\":\"CONTACTLESS\",\"rrn\":\"2827948XXXXX\",\"tvr\":\"00000XXXXX\"}", "customerReceipt": "{\"acquirerMerchantId\":\"0000000001XXXXX\",\"acquirerProcessTime\":\"2025-05-13T13:19:51Z\",\"acquirerTerminalId\":\"911XXXXX\",\"aid\":\"A00000000XXXXX\",\"applicationCryptogram\":\"5AC388057A1XXXXX\",\"applicationLabel\":\"VISA CREDIT\",\"approvalCode\":\"0XXXXX\",\"cardBrand\":\"VISA\",\"cardNo\":\"47617300000XXXXX\",\"cvm\":\"NO_CVM\",\"posEntryMode\":\"CONTACTLESS\",\"rrn\":\"2827948XXXXX\",\"tvr\":\"00000XXXXX\"}"

Result

Parameter name	Type	Required	Description
resultStatus	String	Yes	The result status. Valid values are: `S`: Successful `F`: Failed `U`: Unknown
resultCode	String	No	The result code. Maximum length: 64 characters
resultMessage	String	No	The result message that describes the result code in detail. Maximum length: 256 characters

Receipt

Parameter name	Type	Required	Description
cashierReceipt	String	No	The receipt provided for merchants displays the transaction information.
customerReceipt	String	No	The receipt provided for buyers displays the transaction information.

Result codes

*resultCode*	*resultStatus*	*resultMessage*	Further action
`SUCCESS`	`S`	Success.	No action is required.
`PROCESS_FAIL`	`F`	A general business failure occurred. Do not retry.	Contact Antom Technical Support to troubleshoot the issue.
`PARAM_ILLEGAL`	`F`	Parameter names or values do not meet the specified requirements. The result message can vary according to the specific error encountered.	Check whether the request parameters, including the header parameters and body parameters, are correct and valid. For more information about the parameters of this API, see the Request header section.
`INVALID_API`	`F`	The called API is invalid.	Check whether the correct API name is used when making the API call. API names are case-insensitive.
`CLIENT_INVALID`	`F`	The client ID is invalid.	Check whether the correct client ID is used. The payment terminal integration uses the serial number (SN) of the payment terminal as the client ID.
`INVALID_SIGNATURE`	`F`	The signature is not validated.	Refer to the sample code to check whether the correct public key, signed message, and signature algorithm are used.
`INVALID_ENCRPT_DATA`	`F`	The encrypted data is invalid.	Refer to the sample code to check whether the correct encrypted data is used.
`METHOD_NOT_SUPPORTED`	`F`	The server does not implement the requested HTTP method.	Ensure the HTTP method is `POST`.
`TERMINAL_NOT_LOGIN`	`F`	The payment terminal is not logged in.	Log in to the payment terminal.
`PAYMENT_METHOD_NOT_SUPPORT`	`F`	The payment method is not supported.	Select another payment method.
`TERMINAL_BUSY`	`F`	The payment terminal is busy.	Try again later.
`PAYMENT_FAIL`	`F`	The payment failed.	Call the inquryPayment API to query the final payment status. or manually check the payment status on the payment terminal and manually update the payment status on the POS. If the above-mentioned methods do not work, contact Antom Technical Support to troubleshoot the issue.
`PAYMENT_AMOUNT_EXCEED_LIMIT`	`F`	The payment amount is greater than the maximum amount allowed by the contract or payment method.	Check whether the payment amount exceeds the limit or use a lower amount and try again. Contact Antom Technical Support to know the limitation.
`PAYMENT_AMOUNT_BELOW_LIMIT`	`F`	The payment amount is less than the minimum amount allowed by the contract or payment method.	Check whether the payment amount is lower than the limit or use a higher amount and try again. Contact Antom Technical Support to know the limitation.
`PAYMENT_IN_PROCESS`	`U`	The payment is being processed.	Call the inquryPayment API to query the final payment status.
`UNKNOWN_EXCEPTION`	`U`	An API calling is failed, which is caused by unknown reasons.	Call the API again.

Samples

The following code shows a request message:

copy
{
  "paymentRequestId": "pay_1089760038715669_1027757450XXXXX",
  "paymentMethod": "CARD",
  "paymentAmount": {
    "currency": "SGD",
    "value": "50000"
  },
  "originalMerchantOrderId": "order_1139563780653456_2031034758XXXXX",
  "originalMerchantStoreId": "store_2034252352003947_1031044734XXXXX"
}

The following code shows a response message:

copy
{
  "result":{
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success."
  },
  "paymentId": "201906081140108001001888202003XXXXX",
  "paymentReceipt":{
    "cashierReceipt": "{\"acquirerMerchantId\":\"0000000001XXXXX\",\"acquirerProcessTime\":\"2025-05-13T13:19:51Z\",\"acquirerTerminalId\":\"911XXXXX\",\"aid\":\"A00000000XXXXX\",\"applicationCryptogram\":\"5AC388057A1XXXXX\",\"applicationLabel\":\"VISA CREDIT\",\"approvalCode\":\"0XXXXX\",\"cardBrand\":\"VISA\",\"cardNo\":\"47617300000XXXXX\",\"cvm\":\"NO_CVM\",\"posEntryMode\":\"CONTACTLESS\",\"rrn\":\"2827948XXXXX\",\"tvr\":\"00000XXXXX\"}",
    "customerReceipt": "{\"acquirerMerchantId\":\"0000000001XXXXX\",\"acquirerProcessTime\":\"2025-05-13T13:19:51Z\",\"acquirerTerminalId\":\"911XXXXX\",\"aid\":\"A00000000XXXXX\",\"applicationCryptogram\":\"5AC388057A1XXXXX\",\"applicationLabel\":\"VISA CREDIT\",\"approvalCode\":\"0XXXXX\",\"cardBrand\":\"VISA\",\"cardNo\":\"47617300000XXXXX\",\"cvm\":\"NO_CVM\",\"posEntryMode\":\"CONTACTLESS\",\"rrn\":\"2827948XXXXX\",\"tvr\":\"00000XXXXX\"}"
    }
}