Antom, leading provider of tailored payment solutions
Contact Us
Log In

pay（反扫支付）

POST /v1/payments/pay

使用此接口向Antom发起支付，并根据返回的状态和操作指示处理支付结果。 

结构

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

注意：将每个参数（除数组外）的数据类型设置为字符串，即参数的值必须使用英文双引号（" "）包裹起来。例如：

  • 如果参数的数据类型为整数属性，且其值为 20，设置为 "20"。
  • 如果参数的数据类型为布尔属性，且其值为 true，设置为 "true"。


入参

productCode String  REQUIRED

根据商户与 Antom之间的合同，商户可以使用的支付产品。对于反扫支付，该值固定为IN_STORE_PAYMENT。

paymentRequestId String  REQUIRED

商户为识别支付请求而分配的专属 ID。Antom 使用此字段进行幂等性控制。

更多信息：

  • 此为幂等字段。商户使用 paymentRequestId 字段来实现幂等性控制。对于使用相同 paymentRequestId 值发起的支付请求，如果达到最终状态（S或F），则对同一请求应返回相同的结果。
  • 最大长度：64 字符

order Order  REQUIRED

订单信息，如买家信息、商户信息、订单描述和订单金额。

此参数也用于风险控制、监管、报告、用户支付结果展示等。

paymentAmount Amount  REQUIRED

商户请求在订单货币中接收的支付金额。

paymentMethod PaymentMethod  REQUIRED

由商户或收单机构用来收取支付的支付方式。

paymentExpiryTime Datetime  

支付有效期是一个特定时间，超过这个时间后，支付将失效。支付有效期过后，收单机构或商户必须终止订单处理。默认的支付有效期由合同约定。如果你想使用不同于默认时间的支付有效期，可以在此字段中指定。

注意：通常对于反扫支付，合同中的默认支付有效期是支付请求发送后的 10 分钟。例如，如果请求在 2019-11-27T12:00:01+08:30 时发送，支付有效期则为 2019-11-27T12:10:01+08:30。

更多信息：

  • 值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。

paymentNotifyUrl URL  REQUIRED

用于接收支付结果通知的链接。

更多信息：

  • 最大长度：2048 字符

paymentFactor PaymentFactor  

指示支付场景。

settlementStrategy SettlementStrategy  

支付请求的结算策略。

注意：在满足以下任一条件时指定此字段：

  • 已签署多个结算合约，且有多个结算合约支持此交易。在这种情况下，使用此字段指定结算货币，以便从所有已签署的结算合约中选择用于此交易的合约。
  • 当 paymentMethodType 的值为 CONNECT_WALLET 时。

merchantRegion String  

商户或二级商户开展业务所在的国家或地区。遵循 ISO 3166 国家代码标准的二位字母国家/地区代码。目前仅支持US,JP,PK,SG。

注意：使用全球收单网关（GAGW）产品时，此字段是必需的。

更多信息：

  • 最大长度：2 字符

出参

result Result  REQUIRED

请求结果包含状态和错误代码等信息。

paymentRequestId String  

商家为标识支付请求分配的专属 ID。

更多信息：

  • 最大长度：64 字符

paymentId String  

Antom 为识别支付而分配的支付 ID。

更多信息：

  • 最大长度：64 字符

paymentAmount Amount  

商户请求在订单货币中接收的支付金额。

actualPaymentAmount Amount  

实际支付金额，等于支付金额乘以支付汇率。

注意：当支付货币与支付服务提供商的实际支付货币匹配时，该字段的值等于支付金额。

paymentQuote Quote  

交易时支付货币与实际支付货币之间的汇率。

注意：当支付货币与支付服务提供商的实际支付货币相同时，该字段为空。

paymentTime Datetime  

支付成功或失败的最终状态发生的时间和日期。

更多信息：

  • 值遵循 ISO 8601 标准格式。例如，“2019-11-27T12:01:01+08:00”。

pspCustomerInfo PspCustomerInfo  

顾客的 Alipay+支付方式 信息。

注意: Alipay+ 移动支付提供商，是参与Alipay+ 核心服务的移动支付合作伙伴，也是与蚂蚁集团成员合作、面向用户或发卡机构提供支付服务的其他支付服务提供商。

challengeActionForm ChallengeActionForm  

当支付结果未处于成功或失败的最终状态时，提供关于验证操作的信息。

redirectActionForm RedirectActionForm  

关于重定向操作的信息：

  • 当用户重定向方法为GET (method=GET)时，redirectUrl 的值是一个可用于用户重定向的完整链接。
  • 当用户重定向方法为POST (method=POST)时，redirectUrl 的值是用户应被重定向到的完整链接的一部分。其他构建完整链接所需的参数在参数字段中提供。

注意：此字段仅在接口调用成功时返回。   

grossSettlementAmount Amount  

净结算金额，等于交易金额乘以 settlementQuote 的值。

注意：当结算货币与交易货币相同时，此字段为空。

settlementQuote Quote  

交易时结算货币与交易货币之间的汇率，仅在锁定汇率的情况下提供。

注意：当结算货币与交易货币相同时，此字段为空。

API Explorer

请求

URL

Method
POST
json
{
  "order": {
    "merchant": {
      "merchantMCC": "1234",
      "merchantName": "cup Hu",
      "referenceMerchantId": "seller231117459@login.com",
      "store": {
        "referenceStoreId": "S0000000001",
        "storeMCC": "1405",
        "storeName": "UGG-2"
      }
    },
    "orderAmount": {
      "currency": "USD",
      "value": "50000"
    },
    "orderDescription": "Mi Band 3 Wrist Strap Metal Screwless Stainless SteelXiaomi MiBand 3 ",
    "referenceOrderId": "10277574507XXXX"
  },
  "paymentAmount": {
    "currency": "USD",
    "value": "50000"
  },
  "paymentFactor": {
    "inStorePaymentScenario": "PaymentCode"
  },
  "paymentMethod": {
    "paymentMethodId": "28100602000000000012XXXX",
    "paymentMethodType": "CONNECT_WALLET"
  },
  "paymentNotifyUrl": "http://xmock.inc.alipay.net/api/Ipay/globalSite/automtion/paymentNotify.htm",
  "paymentRequestId": "pay_1089760038715669_10277574507XXXX",
  "productCode": "IN_STORE_PAYMENT"
}

响应

json
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "paymentRequestId": "pay_1089760038715669_10277574507XXXX",
  "paymentId": "2019060811401080010018882020035XXXX",
  "paymentAmount": {
    "value": "500",
    "currency": "USD"
  },
  "actualPaymentAmount": {
    "value": "983",
    "currency": "CNY"
  },
  "paymentQuote": {
    "guaranteed": false,
    "quoteCurrencyPair": "840/156",
    "quotePrice": 1.9658466
  },
  "paymentTime": "2019-06-01T12:01:01+08:00",
  "paymentCreateTime": "2019-06-01T12:01:00+08:00",
  "pspCustomerInfo": {
    "pspName": "ALIPAY_CN",
    "pspCustomerId": "2088111111XXXX",
    "displayCustomerId": "test***@xxx.com"
  }
}

更多信息 

本节提供了关于其他参数的额外信息。请参阅以下参数以了解详情：

productCode：
此参数的值是商家根据与 Antom 之间的合同用于收款的支付产品。当商家可以使用多个产品时，此参数是必需的。

order:
order 参数包含商户、商品、物流和购买环境等信息。在支付过程中，这些订单信息主要用于风险控制或反洗钱。支付完成后，这些信息用于展示消费记录、监管报告等目的。然而， Antom 不会验证 order 中的金额与支付请求中的金额是否一致，订单信息也不应用于资金操作。如果需要使用 Antom 提供的风险控制能力，请使用env字段
在这种情况下，order.merchant.referenceMechantId，order.merchant.merchantMCC，order.merchant.store.referenceStoreId 和 order.merchant.store.storeMcc 是必需的。建议指定 order.env.storeTerminalRequestTime 和 order.env.storeTerminalId。

text
{  
    "order": {
        "referenceOrderId": "102775745075669",
        "orderDescription": "Mi Band 3 Wrist Strap Metal Screwless Stainless Steel For Xiaomi Mi Band 3 ",
        "orderAmount": {
            "value": "500",
            "currency": "USD"
        },
        "goods": [{
            "referenceGoodsId": "102775745075669",
            "goodsName": "xxx goods",
            "goodsUnitAmount": {
                "currency": "USD",
                "value": "498"
            },
            "goodsQuantity": "1"
        }],
        "shipping": {
            "shippingName": {
                "fullName": "Bob Day"
            },
            "shippingAddress": {
                "region": "US",
                "state": "California",
                "city": "San Mateo",
                "address1": "400 El Camino Real",
                "address2": "suite 107",
                "zipCode": "95014"
            },
            "shippingCarrier": "USPS",
            "shippingPhoneNo": "9093749555"
        },
        "buyer": {
            "referenceBuyerId": "bob@gmail.com",
            "buyerName": {
                "fullName": "Bob Day"
            },
            "buyerPhoneNo": "+86 18888888888",
            "buyerEmail": "bob@gmail.com"
        },
    "env": {  "storeTerminalId": "209898256","storeTerminalRequestTime": "2019-06-01T12:01:01+08:00"},
    "extendInfo": "{"chinaExtraTransInfo":{"businessType":"1|2|3|4|5","hotelName":"Holiday Inn San Jose|Hyatt Resort San Mateo","checkinTime":"2018-10-21|2018-10-30","checkoutTime":"2018-10-24|2018-11-03","flightNumber":"UA898|CA986","departureTime":"2018-10-22 20:49|2018-10-23 04:50","admissionNoticeUrl":"https://www.iconfont.cn/search/index?test"}}"



    }


    }

paymentMethod:
paymentMethod 的值为 CONNECT_WALLET，表示 Antom 从用户的支付码（由 Antom 生成）中收款。

paymentMethodId:
用户支付工具的专属 ID。对于反扫支付，此字段是必需的，商户可以据此决定调用哪个支付服务来处理支付。更多信息请参阅 支付码规范。

paymentExpiryTime:
支付执行方必须确保在过期时间后支付不会成功。如果请求中未指定此参数，则过期时间由支付执行方决定。

paymentFactor：
paymentFactor.inStorePaymentScenario 的值为 PaymentCode, 表示使用支付代码进行支付。 

支付代码规范

一个 Antom 的支付代码是 16 到 24 位的数字，以 25 到 30 之间的数字开头。

对于反扫支付，使用以下规则来确定调用哪个支付服务：

  • 如果使用了 Antom 的支付代码进行支付，商家需要将支付路由到 Antom。
  • 如果使用了非 Antom 的支付代码进行支付，商家需要将支付路由到该非 Antom 支付代码对应的支付提供者。
  • 如果一个与 Antom 集成的商户也与遵循 Antom 支付码规则的其他本地支付方式（如澳门钱包或 PayPay 钱包）进行了集成，当使用这些本地支付方式的支付码时，商户需要将支付路由到本地支付系统。或者使用 Antom 的支付码时，则需要将支付路由到 Antom。要判断支付码属于 Antom 还是本地支付方式，应遵循以下规则：

亚洲


支付代码规则

支付服务

长度 

前两位数字 

特殊规则

24

25 - 30

第四、五、六位数字为8、0、1。

PayPay

16~24

25 - 30

无

Antom


支付代码规则

支付服务

长度 

前两位数字 

特殊规则

16~24

25 - 30

第四、五、六位数字为0、0、3。

澳门钱包

16~24

25 - 30

无

Antom


支付代码规则

PaymentService

长度 

前两位数字 

特殊规则 

16~24

25 - 30

无

Antom


支付代码规则

PaymentService

长度 

前两位数字 

特殊规则 

16~24

25 - 30

无

Antom

结果处理逻辑

调用 支付 (反扫支付）接口后，可能会从 Antom 返回以下结果，或者商户未收到任何结果：

  • Antom 返回的 result.resultStatus 为S，表示交易成功，资金已成功扣款。
  • Antom 返回的 result.resultStatus 为F，商户需要根据 result.resultCode 中的错误信息采取进一步行动。
  • Antom 返回的 result.resultStatus 为U，商户需要使用 支付结果查询（线下商店）接口查询支付结果。查询请求可以发送 10 到 20 次，每次间隔 3 秒。
  • 如果在发送支付请求后 5 秒内，没有从 Antom 收到异步通知和支付结果，商家需要使用 支付结果查询（线下商店）接口查询支付结果。查询请求可以发送 10 到 20 次，每次间隔 3 秒。
  • 当调用 支付结果查询（线下商店） 接口，如果查询请求超过最大次数仍无法获取支付结果，商家需要调用 取消支付 接口取消交易。如果超出可取消时间段，商家无法使用 取消支付 接口取消交易，可以调用 退款（线下商店）接口进行退款。

结果码

结果码值结果码信息行动建议
SUCCESSS成功

支付成功，无需进一步操作。  

ACCESS_DENIEDF访问被拒绝。

请联系 Antom 技术支持以获取详细原因。 

INVALID_APIF调用的接口无效或未激活。

请联系 Antom 技术支持解决此问题。  

CLIENT_INVALIDF客户端 ID 无效。Antom 对客户端 ID 有限制。

检查 clientId 是否正确，或联系 Antom 技术支持以获取详细原因。 

CURRENCY_NOT_SUPPORT F货币不支持。

请联系 Antom 技术支持以获取详细原因。 

EXPIRED_CODEF支付码已过期。

用户需要刷新支付码。 

INVALID_CONTRACTF合同中的参数值与当前交易不符。

检查合同中的参数值是否与当前交易匹配。如果匹配，请联系 Antom 技术支持解决问题。 

INVALID_MERCHANT_STATUSF商户状态异常，存在限制。

请联系 Antom 技术支持以获取详细原因。 

INVALID_PAYMENT_CODEF支付码无法被 Antom 接受。

选择其他支付方式。如果支持的支付方式，请联系 Antom 技术支持。

INVALID_SIGNATUREF签名验证失败。请求的私钥与 Antom 开发者中心的公钥不匹配。

检查用于签名请求的私钥是否与 Antom 开发者中心的公钥匹配。以下签名参考信息有用：

KEY_NOT_FOUNDF未找到 Antom 或商户的私钥或公钥。

检查私钥或公钥是否存在。如果不存在，请在 Antom 开发者中心上传私钥。

MEDIA_TYPE_NOT_ACCEPTABLEF服务器不支持客户端可接受的媒体类型。

检查媒体类型是否正确，并使用 Antom 接受的媒体类型。

MERCHANT_KYB_NOT_QUALIFIEDF由于商户的 KYB 状态，支付失败。商户要么未完成 KYB，要么 KYB 状态不符合此交易要求。

请联系 Antom 技术支持以获取详细原因。 

MERCHANT_NOT_REGISTEREDF商户未注册。

请使用注册接口注册商户。如果无法调用注册接口，请联系 Antom 技术支持。

METHOD_NOT_SUPPORTEDF服务器不支持请求的 HTTP 方法。仅支持 POST 方法。

确保 HTTP 方法为​POST​。

NO_INTERFACE_DEFF接口未定义。

检查链接是否正确。请参考接口文档中的端点信息。

NO_PAY_OPTIONSF交易不支持该货币。

请检查钱包是否支持该货币，或者检查钱包和货币是否与合约一致。如需详细原因，请联系 Antom 技术支持。

ORDER_IS_CANCELEDF您发起的请求具有与之前已支付并被取消的交易相同的 paymentRequestId。

使用新的 paymentRequestId 重新发起支付。

ORDER_IS_CLOSEDF您发起的请求具有与已存在并关闭的交易相同的 paymentRequestId。

使用新的 paymentRequestId 重新发起支付。

PARAM_ILLEGALF缺少必需参数，或存在非法参数。例如，非数字输入、无效日期，或参数的长度和类型错误。

检查并验证当前接口所需的请求字段（包括头部字段和正文字段）是否正确传递并有效。

PAYMENT_AMOUNT_EXCEED_LIMITF支付金额超过了合同或支付方式允许的最大金额。

检查支付金额是否超过限制，或者使用较低金额再试一次。请联系 Antom 技术支持了解具体限制。

PAYMENT_COUNT_EXCEED_LIMITF支付次数超过了支付方式指定的限制。

请联系 Antom 技术支持了解具体限制。

PAYMENT_NOT_QUALIFIEDF商户未获得支付资格，可能是因为未注册、未签订代扣协议，或被禁止支付。

请联系 Antom 技术支持以获取详细原因。 

PROCESS_FAILF发生了常见的业务失败。

获取 Antom 技术支持前请勿重试。

REPEAT_REQ_INCONSISTENTF金额或货币与先前请求不同。

确保请求中的所有字段相同，或使用新的 paymentRequestId 重新发起支付。

RISK_REJECTF因风险控制，请求被拒绝。

提示用户因风险控制失败，请求被拒绝。

SYSTEM_ERRORF发生系统错误。

获取 Antom 技术支持前请勿重试

USER_AMOUNT_EXCEED_LIMITF支付金额超过了用户的支付限额。

使用不超过账户可用余额的金额创建新的支付，或联系 Antom 技术支持。

USER_BALANCE_NOT_ENOUGHF因对应支付方式的用户余额不足，无法完成支付。

请充值账户或选择其他支付方式。

USER_KYC_NOT_QUALIFIEDF因用户的 KYC 状态，支付失败。用户可能未完成 KYC ，或者 KYC 状态不满足此交易要求（例如，支付金额或产品信息的限制）。

首先完成 KYC 验证。

USER_NOT_EXISTF用户在支付方式端不存在。

请联系 Antom 技术支持以获取详细原因。 

USER_PAYMENT_VERIFICATION_FAILEDF用户在支付方式端被限制支付。

用户验证失败，如 OTP 或 PIN 验证。请重新下单。  

USER_STATUS_ABNORMALF用户在支付方式端的状态异常。

请联系 Antom 技术支持以了解具体原因。

PAYMENT_IN_PROCESSU支付正在处理中。

等待异步通知，或调用 支付结果查询（线下商店）接口查询订单的最终状态。

REQUEST_TRAFFIC_EXCEED_LIMITU请求流量超过了限制。

再次调用接口解决问题。如果问题未解决，请联系 Antom 技术支持。

UNKNOWN_EXCEPTIONU由于未知原因，接口调用失败。

再次调用接口解决问题。如果问题未解决，请联系 Antom 技术支持。