Antom, leading provider of tailored payment solutions

createPaymentSession

POST /v1/payments/createPaymentSession
使用此接口可创建用于客户端 SDK 集成的支付会话。通过此接口响应,APO 返回加密的会话数据。您使用这些会话数据初始化客户端 SDK。SDK 帮助您完成支付流程,以及跳过支付过程中的中间页面重定向。

结构

报文由报文头和报文体组成。本文主要介绍报文体结构信息,有关报文头的结构信息,请参阅:
注意:将每个字段(除数组外)的数据类型设置为字符串。这意味字段值必须使用双引号(" ")括起来。例如:
  • 如果字段的数据类型为整数属性,且其值为 20,设置为 "20"。
  • 如果字段的数据类型为布尔属性,且其值为 true,设置为 "true"。

入参

productScene String  

指定产品场景。
注意:Checkout page 集成场景下需指定此参数的值为 CHECKOUT_PAYMENT。

更多信息:

  • 最大长度:32 字符

paymentRequestId String  REQUIRED

商户为识别支付请求而分配的专属 ID。

更多信息:

  • 最大长度:64 字符

order Order  REQUIRED

包括买家、商户、商品、金额、配送信息和购买环境的订单信息。此字段用于以下目的:
  • 在支付过程中,此字段主要用于 APO 的风险控制或反洗钱。
  • 支付完成后,此字段用于记录和报告,如采购追踪和监管报告。

availablePaymentMethod PaymentMethod  

商家或收单机构用于收取支付的支付方式。

paymentAmount Amount  REQUIRED

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

savedPaymentMethods Array<PaymentMethod>  

买家在商户系统中已存储的支付信息。

paymentFactor PaymentFactor  

影响支付的因素。此字段用于指示支付场景。
注意:当 paymentMethodType 的值为 CARD并且您集成客户端 SDK 时,指定此参数。

paymentMethod PaymentMethod  REQUIRED

商家或收单机构用于收取支付的支付方式。

paymentRedirectUrl URL  REQUIRED

支付完成后买家被重定向到的商户页面链接。

更多信息:

  • 最大长度:2048 字符

paymentNotifyUrl URL  

用于接收支付结果通知的链接。
注意:如果希望接收支付结果的异步通知,请设置此参数。您也可以在 APO Dashboard 中设置接收结果通知的链接。如果请求和 APO Dashboard 中都指定了链接,则请求中指定的值优先。

更多信息:

  • 最大长度:2048 字符

settlementStrategy SettlementStrategy  

支付请求的结算策略。

enableInstallmentCollection Boolean  

指示是否允许 APO 收集支付的分期信息。
注意:
如果需要 APO 收集分期信息,请指定此参数。有效值为:
  • true: 表示当用户的卡支持分期时,APO 会收集分期信息。如果用户的卡不支持分期,则不提供分期。
  • false: 表示不需要 APO 收集分期信息。如果值为空或未指定此参数,情况相同。

creditPayPlan CreditPayPlan  

此支付的分期付款计划信息。
注意:当支付支持分期且在 paymentMethod.paymentMethodMetaData 中指定了与银行卡相关的信息时,指定此参数。

productCode String  REQUIRED

表示合同中规定的正在使用的支付产品。对于单笔支付,值设置为 CASHIER_PAYMENT。

merchantRegion String  

商户经营业务的国家或地区。该参数遵循 ISO 3166 国家代码标准的二位字母国家或地区代码。
可能的值包括 US, SG, HK, PK, JP, CN, BR, AU, 和 MY。 
注意:当使用全球收单网关(GAGW)产品时,此参数是必需的。

更多信息:

  • 最大长度:2 字符

locale String  

收银台指定的语言标签。如果该字段为空或设置为自动,则将使用浏览器的默认语言设置,通常为英文。

更多信息:

  • 最大长度:8 字符

env Env  

下单的环境信息。
注意:当需要风险控制时指定此参数。提供此信息有助于提高反洗钱和欺诈检测的准确性,以及提高支付成功率。  

paymentSessionExpiryTime Datetime  

支付会话过期的具体日期和时间。默认过期时间为会话创建后 1 小时。例如,如果会话在 2023-7-27T12:00:01+08:30 创建,那么会话过期时间为 2023-7-27T13:00:01+08:30。
注意:如果希望使用不同于默认时间的支付会话过期时间,请指定此参数。指定的过期时间必须在会话创建后 0 到 1 小时之间。

更多信息:

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

riskData RiskData  

蚂蚁集团用于风险控制的数据。指定此参数以使用 APO 的风险控制能力。

出参

result Result  REQUIRED

接口调用的结果。

paymentSessionId String  REQUIRED

APO 为识别支付会话而分配的加密 ID。

更多信息:

  • 最大长度:64 字符

paymentSessionData String  REQUIRED

加密的支付会话数据。将数据传递给前端以初始化 SDK 客户端。

更多信息:

  • 最大长度:4096 字符

paymentSessionExpiryTime Datetime  REQUIRED

支付会话过期的具体日期和时间。

更多信息:

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

normalUrl String  

用于跳转至 Checkout Page 的链接。

更多信息:

  • 最大长度:2048 字符
API Explorer

请求

URL
Method
POST
Case
json
{
  "env": {
    "clientIp": "112.80.248.78"
  },
  "order": {
    "buyer": {
      "buyerPhoneNo": "1346667****",
      "referenceBuyerId": "yeiasdasda****"
    },
    "orderAmount": {
      "currency": "EUR",
      "value": "100"
    },
    "orderDescription": "xxxxx",
    "referenceOrderId": "926e1c32-4a6c-442e-b5ce-8ec5b902****"
  },
  "paymentAmount": {
    "currency": "EUR",
    "value": "100"
  },
  "paymentFactor": {
    "isAuthorization": true
  },
  "paymentMethod": {
    "paymentMethodMetaData": {
      "billingAddress": {
        "address1": "Wuchang road",
        "address2": "Xihu",
        "city": "Hangzhou",
        "region": "CN",
        "state": "Zhejiang",
        "zipCode": "310000"
      },
      "cardNo": "411734780615****",
      "cardholderName": {
        "firstName": "Tom",
        "lastName": "Jay"
      },
      "cvv": "850",
      "enableAuthenticationUpgrade": true,
      "expiryMonth": "12",
      "expiryYear": "29",
      "is3DSAuthentication": true,
      "isCardOnFile": true
    },
    "paymentMethodType": "CARD"
  },
  "paymentNotifyUrl": "https://www.yourNotifyUrl",
  "paymentRedirectUrl": "https://www.yourMerchantWeb.com",
  "paymentRequestId": "55bf93a6-71a1-4ca9-b014-53273bd6****",
  "productCode": "CASHIER_PAYMENT",
  "settlementStrategy": {
    "settlementCurrency": "EUR"
  }
}

响应

Case
json
{
  "paymentSessionData": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Kvvmsdk+akdLvoShW5avHX8e8J15P8uNVEf/PcCMyXg==&&SG&&111",
  "paymentSessionExpiryTime": "2023-04-06T03:28:49+08:00",
  "paymentSessionId": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Ikyj9FPVUOpv+DjiIZqMe",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

更多信息

关于 order 字段:APO 不会验证 order 字段中的金额与支付请求中的金额是否一致。订单信息也不应用于资金操作。此字段主要用于风险控制、监管、监管报告和消费记录显示。如果需要 APO 提供的风险控制能力,请使用 env 字段。
order字段例如text
{
 "order": {
 "referenceOrderId": "102775745075669",
 "orderDescription": "Mi Band 3 金属无螺丝不锈钢腕带适用于 Xiaomi Mi Band 3 ",
 "orderAmount": {
 "value": "500",
 "currency": "USD"
        },
 "goods": [{
 "referenceGoodsId": "102775745075669",
 "goodsName": "xxx 商品",
 "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"
        }
    }
} 

结果码

结果码值结果码信息行动建议
SUCCESSS成功
支付会话已成功创建。无需进一步操作。
PARAM_ILLEGALF缺少必需的参数,或者存在非法参数。例如,非数字输入,无效的日期,或者参数的长度和类型错误。
检查并验证当前接口所需的请求字段(包括头部字段和正文字段)是否正确传递并有效。
PROCESS_FAILF发生了常见的业务失败。
获取 APO 技术支持前请勿尝试。
NO_PAY_OPTIONSF没有可用的支付选项。
请联系 APO 技术支持以获取详细原因。
CARD_NOT_SUPPORTEDF用于交易的银行卡不被支持。
使用另一张银行卡支付交易。
UNKNOWN_EXCEPTIONU由于未知原因,接口调用失败。
重新调用接口以解决问题。如果问题未解决,请联系 APO 技术支持。