createCashierPayment
POST
: /amsin/api/v1/business/create
集成商可调用此接口来创建支付订单。
- 万里汇接受请求后,会发送响应报文给集成商跳转到支付页面的URL。集成商需要引导用户跳转到支付页面并完成支付
- 此接口为异步支付。万里汇在响应报文内的
result.resultStats
字段里仅表示此次API请求成功。若需查询支付结果,集成商需调用inquirePayment查询。
接口结构
万里汇接口报文结构包括:请求头,请求体。关于头信息,详见:
请求参数
字段名 | 数据类型 | 是否为必填字段 | 描述 |
orderGroup | OrderGroup 对象 | 是 | 支付的订单信息 |
payToDetails | 数组<PayToDetail 对象> | 是 | 应付明细 |
paymentRedirectUrl | 字符串 | 是 | 支付后跳转地址,一般为商户的支付结果页 更多信息:
|
industryProductCode | 字符串 | 是 | 行业产品代码 取值为固定值:
|
extendInfo | 字符串 | 否 | 扩展信息 更多信息:
|
响应参数
字段名 | 数据类型 | 是否为必填字段 | 描述 |
result | Result 对象 | 是 | 本次调用结果, 反映本次调用的业务状态、错误信息等 |
payToSummaries | 数组<PayToSummary 对象> | 是 | 应付概要信息 |
actionForm | JSON 字符串 | 是 | 下一步动作,当本次处理结果非终态时提供,作为下一步动作的参考。 使用时需将JSON字符串转换为actionForm对象。 ActionForm为父类,子类有:
|
extendInfo | 字符串 | 否 | 扩展信息 更多信息:
|
响应处理
集成商调用createCashierPayment接口之后,万里汇会发送响应报文给集成商:
- 结果码(
reult.resultStatus
)
- 本支付为异步流程。结果码(
reult.resultStatus
)仅展示本次API请求是否被万里汇接受。集成商需调用inquirePayment API以获得支付结果。 result.resultStatus
取值范围为:
result.resultStatus | 描述 |
S | API请求成功 |
F | API请求失败 失败原因请检查结果码(即 |
U | API检查结果未知,请重试API请求。如果问题继续,请联系万里汇技术支持 |
- 在万里汇响应报文内,集成商可以获得跳转到支付页面的URL(
actionForm.rediectUrl
) - 用户需要在支付页面上完成支付。支付完毕后,用户跳转到支付结果页面
- 如果用户支付成功,集成商可以在支付订单完成后5秒钟后调用inquirePayment API查询支付结果
- 如果用户支付失败,用户需要在支付页面上再次完成支付(支付页面的URL相同)
- 如果支付页面URL过期,用户会跳转到支付结果页面,并显示"Unknown Exception"未知错误。此时集成商需要再次调用createCashierPayment API,且使用不同的
payToRequestId
,以获得新的支付页面URL
结果码
resultCode | resultStatus | resultMessage | 处理建议 |
SUCCESS | S | Success | |
PROCESS_FAIL | F | A general business failure occurred. Do not retry. | 需要人工介入。联系万里汇技术支持以解决此问题 |
PARAM_ILLEGAL | F | Illegal parameters exist. For example, a non-numeric input, or an invalid date. | 参考API文档页面以确认请求头和传参是否正确 |
UNKNOWN_EXCEPTION | U | The API call is failed, which is caused by unknown reasons. | 服务器忙。若稍后重试问题依旧,联系万里汇技术支持以解决问题 |
AMOUNT_EXCEEDS_LIMIT | F | The amount of the payment order exceeds the limit. | 支付金额超出上限。更改金额并重试 |
AMOUNT_LESS_THEN_LIMIT | F | The amount of the payment order is less than the limit. | 支付金额低于下限。更改金额并重试 |
CURRENCY_NOT_SUPPORT | F | The currency is not supported. | 资金币种不支持。确认币种正确并重试 |
REPEAT_REQ_INCONSISTENT | F | Repeated requests are inconsistent. | 重试请求不一致。需保证所有请求参数均相同 |
UNSUPPORTED_TIME_UNIT | F | Unsupported time unit. | 不支持输入的时间单位。请使用正确的时间单位后重试。 |
EXPIRY_TIME_OUT_OF_RANGE | F | The expiration time is not within the valid range. | 输入的相对过期时间或绝对过期时间超出规定的范围。请确保两者在规定范围内之后重试。 |
范例
请求
{
"orderGroup":{
"orderBuyer":{
"referenceBuyerId":"*****"
},
"orderGroupDescription":"Cashier_payment",
"orderGroupId":"*****",
"orders":[
{
"orderTotalAmount":{
"currency": "USD",
"value": "10"
},
"orderDescription":"Cashier_payment",
"referenceOrderId":"*****",
"transactionTime":"2022-06-17T08:43:58.588Z"
}
]
},
"industryProductCode":"ONLINE_DIRECT_PAY",
"paymentRedirectUrl":"http://www.sample.com",
"payToDetails":[
{
"payToRequestId":"payTo_requestId_*****",
"payToAmount":{
"currency": "USD",
"value": "10"
},
"payToMethod":{
"paymentMethodType":"BALANCE",
"paymentMethodDataType":"PAYMENT_ACCOUNT_NO",
"paymentMethodData":"",
"customerId":"*****"
},
"paymentNotifyUrl":"http://www.sample.com",
"referenceOrderId":"*****"
}
]
}
响应
{
"actionForm": "{\"actionFormType\":\"RedirectActionForm\",\"method\":\"GET\",\"redirectUrl\":\"http://{domain_name}.net/business/cashier/checkout?partnerId=******&cashierOrderId=******\"}",
"payToSummaries": [
{
"payToAmount": {
"currency": "USD",
"value": "10"
},
"payToCreateTime": "2022-03-21T00:00:00-07:00",
"payToId": "*****",
"payToRequestId": "payTo_requestId_******"
}
],
"result": {
"resultCode": "SUCCESS",
"resultMessage": "success.",
"resultStatus": "S"
}
}