Antom, leading provider of tailored payment solutions

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  

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

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

更多信息:

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

paymentRedirectUrl URL  

支付完成后用户被重定向到的链接。

更多信息:

  • 最大长度:2048 字符

paymentNotifyUrl URL  REQUIRED

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

更多信息:

  • 最大长度:2048 字符

paymentFactor PaymentFactor  

指示支付场景。

settlementStrategy SettlementStrategy  

支付请求的结算策略。

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

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

merchantRegion String  

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

注意:当使用 Antom 全球网关(GGW)产品时,此字段是必需的。

更多信息:

  • 最大长度:2 字符

出参

result Result  REQUIRED

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

paymentRequestId String  

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

更多信息:

  • 最大长度:64 字符

paymentId String  

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

更多信息:

  • 最大长度:64 字符

paymentAmount Amount  

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

paymentTime Datetime  

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

更多信息:

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

paymentCreateTime Datetime  

支付创建的日期和时间。

更多信息:

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

pspCustomerInfo PspCustomerInfo  

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

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

challengeActionForm ChallengeActionForm  

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

redirectActionForm RedirectActionForm  

提供有关重定向操作的信息。

grossSettlementAmount Amount  

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

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

settlementQuote Quote  

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

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

API Explorer

请求

URL
Method
POST
json
{
  "order": {
    "env": {
      "userAgent": "Mozilla/5.0 (Linux; Android 9; LYA-AL00 Build/HUAWEILYA-AL00L; wv)  AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0  Chrome/70.0.3538.110  Mobile Safari/537.36 NebulaSDK/1.8.100112 Nebula  AlipayDefined(nt:WIFI,ws:360|0|3.0) AliApp(APHK/2.6.0.160)  AlipayClientHK/2.6.0.160 Language/zh-HK useStatusBar/true isConcaveScreen/true AlipayClient/10.1.32.600 Alipay Language/zh-Hans"
    },
    "merchant": {
      "merchantMCC": "1234",
      "merchantName": "cup Hu",
      "referenceMerchantId": "seller231117459@login.com",
      "store": {
        "referenceStoreId": "S000000XXXX",
        "storeMCC": "1405",
        "storeName": "UGG-2"
      }
    },
    "orderAmount": {
      "currency": "USD",
      "value": "10"
    },
    "orderDescription": "Mi Band 3 Wrist Strap Metal Screwless Stainless Steel For Xiaomi Mi Band 3 "
  },
  "paymentAmount": {
    "currency": "USD",
    "value": "10"
  },
  "paymentFactor": {
    "inStorePaymentScenario": "EntryCode"
  },
  "paymentMethod": {
    "paymentMethodType": "CONNECT_WALLET"
  },
  "paymentNotifyUrl": "http://xmock.inc.alipay.net/api/Ipay/globalSite/automtion/paymentNotify.htm",
  "paymentRequestId": "10277574507XXXX",
  "productCode": "IN_STORE_PAYMENT"
}

响应

json
{
  "paymentAmount": {
    "currency": "USD",
    "value": "10"
  },
  "paymentCreateTime": "2019-11-19T02:44:13-08:00",
  "paymentId": "2019111919401080010018885020050XXXX",
  "paymentRequestId": "10277574507XXXX",
  "redirectActionForm": {
    "method": "SCAN",
    "redirectUrl": "http://render-dev.site.alipay.net/p/h5_dev/hk-cashier-merchant-S907753718/www/index.html#/landing?pre_order_id=https://global.alipay.com/28100204zTlc51j0VY1jA9y0a3o0v4Ikt"
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "Success",
    "resultStatus": "S"
  }
}

更多信息 

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

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

order:
参数order包含订单信息,如商户、商品、物流和购买环境。在支付过程中,这些信息主要用于 Antom 的风险控制或反洗钱检查。支付完成后,这些信息用于展示消费记录、监管报告等用途。
然而,Antom 不会校验 oreder 中的金额与支付请求中的金额是否一致,订单信息也不用于资金操作。如果需要 Antom 提供的风险控制功能,可以使用 env 字段。

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": "suit 107",
"zipCode": "95014"
            },
"shippingCarrier": "USPS",
"shippingPhoneNo": "9093749555"
        },
"buyer": {
"referenceBuyerId": "bob@gmail.com",
"buyerName": {
                "fullName": "Bob Day"
            },
"buyerPhoneNo": "+86 18888888888",
"buyerEmail": "bob@gmail.com"
        },
        "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 生成的二维码收取款项。

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

paymentFactor:
参数 paymentFactor.inStorePaymentScenario 的值为 EntryCode,表明 Antom 需要在此支付中生成一个跳转链接。

paymentId:
如果响应中未返回此字段,您可以使用 paymentRequestId 字段发起 支付结果查询(线下商店)和 取消支付 请求。

结果处理逻辑

调用 支付(入口码支付)接口后,可能会从 Antom 返回以下结果:

  • Antom 返回的结果中,result.resultStatus 为 S,表示商家需要根据表单中的参数进行跳转,从而继续支付流程。
  • Antom 返回的结果中,result.resultStatus 为 F,说明支付请求失败。
  • Antom 返回的结果中,result.resultStatus 为 U,商家需要再次调用 支付(入口码支付)接口。

结果码

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

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

ACCESS_DENIEDF访问被拒绝。

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

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

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

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

请检查客户端 ID 是否正确,或联系 Antom 技术支持以获取详细原因。

 

CURRENCY_NOT_SUPPORT F货币不支持。

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

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

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

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

请联系 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_NOT_EXISTF用户在钱包端不存在。

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

PAYMENT_IN_PROCESSU支付正在处理中。

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

REQUEST_TRAFFIC_EXCEED_LIMITU请求流量超过了限制。

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

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

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