Antom, leading provider of tailored payment solutionsAntom, leading provider of tailored payment solutions

pay

POST /v2/payments/pay

pay 接口由您的 POS 调用以创建支付请求。在调用此接口前，请确保支付终端已准备就绪可接收支付请求。

结构

报文由报文头和报文体组成。本文主要介绍报文体结构信息，有关报文头的结构信息，请参阅：

请求参数

参数名称

类型

是否必需

描述

paymentRequestId

String

是

由 POS 提供商定义的用于标识支付请求的唯一 ID。

  • 最大长度：64 个字符。
  • 仅允许字母（a-z、A-Z）、数字（0-9）和下划线（_）。

注意：此参数对每个门店是唯一的。它是一个幂等键字段，使用 paymentRequestId 发起的支付请求会返回相同的结果。详细信息请参阅幂等性。

paymentMethod

String

是

商户或收单机构用于收取付款的支付方式。更多信息请参阅支持的支付方式。

paymentAmount

Amount

是

商户请求以订单币种接收的支付金额。

originalMerchantOrderId

String

否

商户端用于标识订单的原始唯一 ID。（最大长度：255 个字符）

originalMerchantStoreId

String

否

商户端用于标识门店的原始唯一 ID。（最大长度：255 个字符）

Amount

参数名称

类型

是否必需

描述

value

Integer

是

货币最小单位的金额值。例如，10000 表示新加坡元 100.00。（取值范围：0-2147483647）

currency

String

是

遵循 ISO-4217 标准的 3 个字符的货币代码。例如，USD。（最大长度：3 个字符）

响应参数

参数名称

类型

是否必需

描述

result

Result

是

接口调用的结果。

paymentId

String

是

由 POS 提供商定义的用于标识支付的唯一 ID，与交易报告中的 paymentId 一致。

paymentReceipt

Receipt

否

支付成功后提供给商户和买家的收据信息。

  • 信息以键值结构提供。在卡支付场景中，通过 customerReceipt 和 cashierReceipt 返回值。
  • 在扫码支付场景中，paymentReceipt 返回空值。
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

参数名称

类型

是否必需

描述

resultStatus

String

是

结果状态。有效值为：

  • S：成功
  • F：失败
  • U：未知

resultCode

String

否

结果码。（最大长度：64 个字符）

resultMessage

String

否

详细描述结果码的结果消息。（最大长度：256 个字符）

Receipt

参数名称

类型

是否必需

描述

cashierReceipt

String

否

提供给商户的收据，显示交易信息。

customerReceipt

String

否

提供给买家的收据，显示交易信息。

结果码

结果码

状态码

结果信息

后续操作

SUCCESS

S

成功

无需后续操作。

PROCESS_FAIL

F

发生常规业务故障。请勿重试。

联系 Antom 技术支持。

PARAM_ILLEGAL

F

参数名称或值不符合指定要求。结果消息会根据具体错误而有所不同。

检查请求参数（包括头部参数和主体参数）是否正确有效。有关接口传参的更多信息请参阅请求头。

INVALID_API

F

调用的接口无效。

检查进行接口调用时是否使用了正确的接口名称。接口名称不区分大小写。

CLIENT_INVALID

F

客户端 ID 无效。

检查是否使用了正确的客户端 ID。支付终端集成使用支付终端的序列号（SN）作为客户端 ID。

INVALID_SIGNATURE

F

签名未通过验证。

参考集成示例代码，检查是否使用了正确的公钥、签名消息和签名算法。

INVALID_ENCRPT_DATA

F

加密数据无效。

参考集成示例代码，检查是否使用了正确的加密数据。

METHOD_NOT_SUPPORTED

F

服务器未实现请求的 HTTP 方法。

确保 HTTP 方法为 POST。

TERMINAL_NOT_LOGIN

F

支付终端未登录。

登录支付终端。

PAYMENT_METHOD_NOT_SUPPORT

F

不支持该支付方式。

使用其他支付方式。

TERMINAL_BUSY

F

支付终端繁忙。

稍后重试。

PAYMENT_FAIL

F

支付失败。

调用 inquiryPayment 接口查询最终支付状态，或在支付终端上手动检查支付状态并在 POS 上手动更新支付状态。如果上述方法无效，请联系 Antom 技术支持以排查问题。

PAYMENT_AMOUNT_EXCEED_LIMIT

F

支付金额大于合同或支付方式允许的最大金额。

检查支付金额是否超过限制，或使用较低的金额重试。联系 Antom 技术支持了解限制。

PAYMENT_AMOUNT_BELOW_LIMIT

F

支付金额小于合同或支付方式允许的最小金额。

检查支付金额是否超过限制，或使用更高的金额重试。联系 Antom 技术支持了解限制。

PAYMENT_IN_PROCESS

U

支付正在处理中。

调用 inquiryPayment 接口查询最终支付状态。

UNKNOWN_EXCEPTION

U

未知原因引起的接口调用失败。

重新调用接口。

示例

以下代码展示了一个请求报文：

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

以下代码展示了一个响应报文：

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\"}"
    }
}