1. 概述
UMF REST API使用HTTP方法和RESTful结构. 该API认证框架采用OAuth 2.0. 商户请求格式为JSON,该API同样响应JSON格式的数据.
1.1. API操作
可以在如下环境使用UMF REST APIs:
| 环境 | 描述 | 地址 |
|---|---|---|
| 国内测试环境 | 测试. 中国的服务器. 使用您测试的client_id和client_secret生成access token,请求测试地址. | https://uatfx.soopay.net/cberest/v1/ |
| 国内生产环境 | 生产. 中国的服务器. 使用您生产的client_id和client_secret生成access token,请求生产地址. | https://fx.soopay.net/cberest/v1 |
要构造REST请求, 须结合一下几点:
- HTTP方法
- 资源的完整URI
- HTTP请求头
- 若有要求,payload应为JSON格式
请参见右边示例.
和UMF合作后,商户将拥有如下信息.
| 类型 | 描述 |
|---|---|
| 商户rsa私钥 | 签名请求 |
| UMF公钥 | 加密敏感信息 |
| 商户client id | OAuth2认证使用 |
| 商户client secret | OAuth2认证使用 |
1.2 认证
UMF系统支持OAuth2. 使用Client Credentials Grant生成access token. 每个商户有一个client_id和一个client_secret. 商户使用 client_id和client_secret生成access Token. 每个请求必须是HTTPS请求, 在请求头里面加上access token.
如果您确信您的商户 ID, 秘钥,或 bearer token 已经失效了, 请在TMS里重新生成您的秘钥. 一旦您有一个新的秘钥, bearer token会立即生成. 15分钟内新的bearer token将同步整个系统.
1.3 HTTP请求
UMF系统支持GET和POST请求.
- GET: 查询对象或对象列表.
- POST：创建或更新对象.
HTTP请求头
## GET Request:
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/bank?type=CREDIT_CARD \
-H "Content-Type:application/json" \
-H "Authorization:Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
## POST Request:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment \
-H "Content-Type:application/json" \
-H "Authorization:Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f" \
-H "Signature:R4gha4Kgg5NDGXV4+Tpw0PTRldATI/ECwCIYgWmLLMBYnF8oVLU2wfBM/hG4Nw+E77qSTquMShiICVS7qcHMVwHZTbFIAP2ZarkJ21EMGFEKdC5hgdDgNO89xXu0OoAfrJ8fDclfdKgpfd9RIpGH7CzKM3JoO0+RD3zCnhnbGBo=" \
请求REST API, 您的请求头必须包含带有OAuth 2.0 access token的认证请求头.
http get请求头示例:
Content-Type:application/json
Accept-Language:en
Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f
如果请求头是POST请求, 请求头必须包含如下信息:
- Signature:SignatureOfPostBody
http post请求头示例:
Content-Type:application/json
Accept-Language:zh
Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f
Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM=
1.4 HTTP响应
所有的http响应都是带有两部分的json格式字符串.
meta：每个响应的公共信息. 包含相应的消息, 签名, 错误码等等.
result: 实体对象. “result"的字段名称也可能不是"result”, 根据对象的类型和对象的数量改变. 举例: 如果返回的对象是付款对象, result的名称就会改成"payment"对象, 内容是一个付款的json对象. 如果返回的对象是多个付款对象,result的名称是"payments", 内容是一个付款的json数组.
HTTP响应码
| 状态码 | 描述 |
|---|---|
| 200 | 请求成功 |
| 201 | 资源创建完成 |
| 400 | 校验错误 |
| 401 | 请求未认证 |
| 402 | 请求失败 |
| 403 | 禁止访问 |
| 404 | 资源未找到 |
| 50n | UMF服务器错误 |
1.5 获取access token
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/oauth/authorize \
-H "Content-Type:application/json" \
-d '{
"client_id": "6bf3b12b9159f55e3863204ac06f19b7a076cfc9",
"client_secret": "2dbfedf52da5036bde758189b1d27ebc1858655e",
"grant_type": "client_credentials"
}'
## Response data:
{
"expires_in": 3600,
"access_token": "46bc277fc209a1cf129ba020b26b6d33a11de962645423faf9c71b8b1799ce72"
}
创建一个带有您应用的OAuth client_id和client_secret keys的OAuth授权作为access token. 设置请求的content-type为application/json. 在请求的实体里面设置grant_type为 client_credentials.
请求
POST: /oauth/authorize
每一个请求在请求头里面必须加入access_token. 该接口返回一个当前用户的access_token. 每一个token有一个有效期的参数,意味着每一个token在有效期内有效. 如果用户申请了一个新的 access_token, 旧的access_token将立即不可用.
参数:
| 参数 | 描述 |
|---|---|
| client_id | 发给商户的客户端标识符. |
| client_secret | 发给商户的客户端秘钥. |
| grant_type | OAuth认证请求的类型. 该场景下值必须为“client_credentials” . |
响应
响应结果是一个json格式的字符串. 包含access_token和expires_in.
响应:
| 参数 | 说明 |
|---|---|
| expires_in | access token的有效期，单位为秒. |
| access_token | access_token. |
1.6 签名和验签
DSA或RSA签名算法中私钥和公钥是必须的. UMF的OPENSSL生成公钥和私钥. UMF 会向商户发送SSL密钥对. 因此, 商户 可以使用UMF公钥和商户私钥.
请求数据的签名
所有的POST请求都需要包含'Signature'的请求头. POST请求的内容为一个JSON格式的字符串. RSA签名函数在RSA签名算法中使用了商家私钥和JSON字符串得到结果字符串. (得到的值放在"Signature"的请求头里).
示例:
Signature:AWD234SDKEBuYviyhggoopDOUEFLKDSJFI7655DFDFOIUOIulkjj
签名算法:
*使用UTF8编码将JSON字符串转换为字节.
*使用SHA256算法将UTF8编码的字节转换为哈希字节.
*使用商户的私钥对哈希字节加密.
*将哈希字节转换为base64编码的字符串.
最后一步得到的结果即为请求的signature.
对响应结果验签
请求的响应信息使用UMF的安全机制签名. 接收到响应信息后商户需要对结果验签.
响应结果是一个JSON格式的字符串,有两部分组成. 第一部分为 “meta”. 另一部分是结果对象.Signature包含在http head里,属性值为Signature , signature是对body所有内容签名.
验签步骤:
*使用UTF8编码将body字符串转换为字节.
*使用SHA256算法将UTF8编码的字节转换为字节数组.
*使用base64将signature字符串解码为字节数组.
*使用RSA验签.
1.7 加密所有的敏感信息
http请求中需要对所有的敏感信息解密. 敏感信息包括:
- 卡号
- 持卡人姓名
- 信用卡安全码
- 有效期 (仅仅对于信用卡)
- 公民身份证号码 (仅仅对于中国用户)
加密算法
字符串 -> 字节(UTF-8编码) -> 字节(使用UMF的公钥进行RSA加密) -> 字符串(Base64编码)
1.8 日期和时间格式
UMF系统的所有日期和时间格式为ISO8601.
时间格式
YYYY-MM-DDThh:mm:ssTZD
示例:
2016-07-16T19:20:30+01:00
日期格式
YYYYMMDD
示例: 20160716
2. 指南
2.1 请求入门
发起rest api请求的条件：
- 申请商户账号.
- 获取access token.
- 调用API.
所有流程步骤如下.
sequenceDiagram
participant 商户
participant UMF
商户-->>UMF: 申请商户账号
UMF-->>商户: 账号信息
商户-->>UMF: 请求access token
UMF-->>商户: 返回access token
Note right of 商户: 使用access token请求REST API.
商户-->>UMF: 发起API请求
UMF-->>商户: 返回结果
申请商户账号
商户需要与UMF签订合同,确定服务费率和其他细节.
当商户账号生效后, UMF将向商户发送邮件. 邮件内容包含如下信息:
- UMF RSA公钥
- 商户 RSA 私钥
- OAuth2认证用到的client_id and client_secret
获取access token
带着您应用的OAuth client_id和秘钥请求/oauth/authorize获取access_token. 在请求body里面设置grant_type为"client_credentials". 当您请求 Get an access tokenUMF生成并返回给您access token.
关于请求头的相关信息, 请参见 REST API authentication, headers和 Get an access token.
发起API请求
拥有有效的access token, 您就可以请求API接口.
access token是OAuth的认证并且包含在如下格式的请求头:
Authorization:Bearer Access-Token
对于认证的更多细节, 请参见 Authentication.
2.2 信用卡/借记卡支付
下单
## 请求数据:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM="
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"bank_code": "BOC",
"payer_info": {
"phone": "13552105741"
},
"interface_type": "SERVER_TO_SERVER",
"business_type": "B2C"
},
"order": {
"mer_reference_id": "1126144824929101",
"mer_date": "20181126",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"order_summary": "CrossBorderOrderSummary",
"expire_time": "360",
"user_ip": "10.10.70.134",
"sub_orders": [{
"trans_code": "01122030",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"is_customs": "TRUE",
"invoice_id": "123456",
"items": [{
"mer_item_id": "1126144824930102",
"type": "FOOD",
"name": "banana",
"quantity": "2",
"description": "banana",
"amount": {
"total": "0.02",
"currency": "CNY"
}
}]
}],
"sub_mer_id": "umfsubmer001"
},
"notify_url": "http://10.10.38.49:2216/spay_rest/payments/test/mer",
"ret_url": "http://10.10.38.49:2213/notify0000V4.jsp",
"risk_info": {
"trans_type": "02"
}
}'
## 响应数据:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"risk_info": {
"trans_type": "02"
},
"id": "PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF",
"state": "WAIT_BUYER_PAY",
"notify_url": "http://10.10.38.49:2216/spay_rest/payments/test/mer",
"payer": {
"bank_code": "BOC",
"business_type": "B2C",
"interface_type": "SERVER_TO_SERVER",
"payment_method": "DEBIT_CARD",
"payer_info": {
"bank_card": {
"number": "",
"cvv2": "",
"valid_date": "",
"citizen_id_number": "",
"phone": "",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": ""
},
"payer_agreement": {
"usr_busi_agreement_id": "",
"usr_pay_agreement_id": ""
}
}
},
"ret_url": "http://10.10.38.49:2213/notify0000V4.jsp",
"is_from_US": "N",
"order": {
"user_ip": "10.10.70.134",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"sub_orders": [{
"mer_sub_reference_id": "1126144818140110",
"trans_code": "01122030",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"invoice_id": "123456",
"is_customs": "TRUE",
"items": [{
"amount": {
"total": "0.02",
"currency": "CNY"
},
"quantity": "2",
"mer_item_id": "1126144824930102",
"name": "banana",
"description": "banana",
"type": "FOOD"
}]
}],
"sub_mer_id": "umfsubmer001",
"mer_date": "20181126",
"expire_time": "2018-11-27T14:48:18+0800",
"mer_reference_id": "1126144824929101",
"order_summary": "CrossBorderOrderSummary"
}
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF"
},
{
"ref": "sms_verify",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF/verify"
},
{
"ref": "self_payment_refund",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF/self_payment_refund"
}]
}
请求下发短信验证码
## 请求数据:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/PAY_GI3TAOBQGEYDQMRQHAYTMMJRGEZDAMJXGA3TGMKN/verify \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"payer_info": {
"bank_card": {
"number": "KOOqvmXPtylUQYUvPP5oEccTyrfwwruOkT7nDt1DqhUrk86hl0X9fNmFm+/SUkxTF5umXKk6ZnZVuxc/mYxHMyGimSkwCZJDdMjERyMF6HgltSIcMaF/6lsItAtD7Drsmfz8eGSEtnUWVnDEPSEUuKX8g2G6YotmfaoOjkYTWhQ\u003d",
"citizen_id_number": "FJseNpbncU08o2N0WAv1kquTI3yiJyxjP/aJOi/SA2dF2/xngO7FzWV/y4a68GpQoD1n4bRw8Dr6ev0xDybHoebOPGFpRUoVbyTduLCmYTPMJIgLNDAD+OfQI8eZHffdcJFFVvcSBx+cE8ZeF4M4UWyqfxPvJqaHG6Rjr8OMjW4\u003d",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "ch7wpuC2OYFW0bd70ywp7YJZKoDQLP4PDaCE8DLRYQJQfxjuwjuNYx1kgFwqlpc3yyO9knrlTN7jwOlfv3MgnTJUjru3J0iWRogRsUWwcseBiMX4OeN6p+oZ00SwWLC6zjdQ1T5961j4Kh1gSTxGGLpxAcqEL3boQZKSfhCuNJY\u003d",
"valid_date": "",
"cvv2": "",
"phone": "15754314122"
}
}
}
}'
## 响应数据:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"id": "PAY_GY4DCMJSGYYTKMZSHE4TMNJQGEZDAMJYGEYTENQV",
"payer": {
"payment_method": "DEBIT_CARD",
"payer_info": {
"bank_card": {
"number": "1qJwrHurIk/Tv2oVgJ5vJULw+L2nl/u+yxXbRWU9U9gJQbhdmLQqL8muaj3EVn8fHx1fJe/HG2M+kHzQZ+ph+0R0RREX4Jm4QMV0Dgben5H+OVaFfs9HqBWmp86t5F9qCdjIc8ScKtPPV6F3jvBs4tkS91qjetJYc1fed0ZTXSo=",
"cvv2": "",
"valid_date": "",
"citizen_id_number": "b5qt1OCytSzcoZuZNhkkAyb3XVJL0NFMIkjdNguYsKI62x12Qdcli+YOesi+QUZvVsOAC5ruHkZb1YkEQQPhXCqDW5zXnkudNdMGEWZJJEsfWXD01V25EYrm9qwjKyEXQr4Fa1JZC+v6dhZ7EpJ/MiZ6fCcNhTsBc2FdVJNdMa0=",
"phone": "15754314122",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "vbQNsGsOSxzcPG3bIA6fK7Y/azCkd7O51Hh/k+OU5uLaKZnvvI1Txr2LK8rOD2g719/Q6ANmFXpAyev9jhI88DVT/+LbLbJWqR6jreOfyKxQUImpYbnnZec/raDUi2HInA6/WiewtvRsb9nAWrkE8/dP3qo0NmNUprQXCK9l+oM="
}
}
}
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTKMZSHE4TMNJQGEZDAMJYGEYTENQV"
},
{
"ref": "confirm",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTKMZSHE4TMNJQGEZDAMJYGEYTENQV/execute"
}]
}
确认支付
## 请求数据:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/PAY_GI3TAOBQGEYDQMRQHAYTMMJRGEZDAMJXGA3TGMKN/execute \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:a/1A+rSDh2EBPGgiqRcET1hNcUtPBjSjQOYZmkqLx1n+IPAeM2p5c29XkB64jMy0fHfzFaK/cCj3vvq/f+o2fqC+WsLWnby34ByxdH+sgTK+I+bkzEdvwD7S9NCWwdMxejwuhBu+HcUn7uLhYgeRdOXfLIH/aThssRoBMTcmeZc="
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"bank_code": "BOC",
"payer_info": {
"bank_card": {
"number": "N0pUVZ/h4WNfypx8Xw7YcXu8EK0Xws22yUk4bfIysNU8Nlk5PQyTpsGB3vx4El7IC4XZuQeJ5iwnqAtDBZc3ypNdtGlpt4/6CKUJwuKX1JOL07cfeoL1mZV8kAzwAwI81PjpgrRTRiT+4QtbwYGMphqh618SwU+UZDgFReByg0Y\u003d",
"citizen_id_number": "w2uf4RT0Qyda2ZgFr0IixV7Pg3cvnI6qX7bhQx7yLoCfx4js/HwaZaykrsePy9ZcSFcM2H8W98BbsEGQ9B0zlEJsLHnye5ELVl34uQYNcJwlxDDS8SBdppJOPeHKUYvtCh9c3bqwgAf1ZCr+U8GNknu6U5Y/ve7g0ge1r3bXZEQ\u003d",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "Qg21ji6MBVNUdZh59+ia8VDdGqfeXtdrbbz1/2Lu/SgbEBKmDrL1/+EOMYrnO/W6lhq4UJUiy5MAn8j1REsliuhboOuWxMXli2IKfc1hRZXSS6mYhvMnO02l7Ayarbr3Q60Q8xohMIyAdcxRARyDRbxuoJpg/1atP7ZOWH/wlVo\u003d",
"valid_date": "",
"cvv2": "",
"phone": "15754314122",
"verify_code": "122766"
}
}
}
}'
## 响应数据:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"settle_date": "20181126",
"id": "PAY_GY4DCMJSGYYTKMZSHE4TMNJQGEZDAMJYGEYTENQV",
"state": "TRADE_SUCCESS",
"execute_success_time": "2018-11-26T15:35:24+0800",
"payer": {
"bank_code": "BOC",
"payment_method": "DEBIT_CARD",
"payer_info": {
"bank_card": {
"number": "EHF4Q3DNjCEArNJKIEUjNdg56rtOa7A/jGdGGsMJdAs3uQbvaMpCQCJdzcm2x1kotTtlgfphUrUHUZaBT6ip9mzHq0BkurlaehW69zdOJkcWv0R01dgDzZJ41J/p79s90NB2NbPiSTHxT7UbBbubEjmCZqJqlolxWsbp/QDYoHI=",
"cvv2": "",
"valid_date": "",
"citizen_id_number": "fuibTjYXwrz4FyYvMRSTH7mYMEAMqSzHJROIPfe4O1ED3M79PF+bYmq9VS94Y2ZOFdL+2EqYOSho09MWKJc/VUnGv6M38Mqoak1d5ff9P+IQNnyffjhDg01fePJg3OwIPxhZXeJU/cmtCZmgpdTWVVswP1ST6TKpBqWm1yPevuo=",
"phone": "15754314122",
"citizen_id_type": "IDENTITY_CARD",
"verify_code": "122766",
"payer_name": "MqDDOzBjDwaERrsJXR+207iAYktLV+IiHK597FeNt84OIel6yiPhOFauTLhg5DYSZ1e4pZgLmbPEVHp8FemX6zGCtlUw9gB2NCXpm6NhvyMSp9xUqinn9DtevE9Cb9dZBVfIEarSjPkU22+7jOXxazk1IuTS/C+06ZvIUbnqdG8="
}
}
}
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTKMZSHE4TMNJQGEZDAMJYGEYTENQV"
},
{
"ref": "apply_to_customs",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTKMZSHE4TMNJQGEZDAMJYGEYTENQV/apply_to_customs"
},
{
"ref": "refund",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTKMZSHE4TMNJQGEZDAMJYGEYTENQV/refund"
},
{
"ref": "asynchronous_refund",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTKMZSHE4TMNJQGEZDAMJYGEYTENQV/asynchronous_refund"
},
{
"ref": "apply_to_ciq",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTKMZSHE4TMNJQGEZDAMJYGEYTENQV/apply_to_ciq"
}]
}
##协议支付下发短信
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/PAY_GI3TAOBQGEYDQMRQHAYTMMJRGEZDAMJXGA3TGMKN/verify \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"payer_info": {
"bank_card": {
"number": "AFz5NlZFjnYVPWHMi86Q84ULua8+HvRhyfAxYGWJQkg2tqwo571aPZQca8dBo+3/QO3yTFAURAjTZaYr77GunXlB8Nuow2wvyxX6QOa+Po8HXk1wzVvCxiHVUulbqGj4O4bZmTVawToMWphtksz4wuwAAWgxvjFqrWXQVEtAcE0\u003d",
"citizen_id_number": "OJEXNDY7yGyRASMItXir9td8taEoQnXlkVxkCvW72i5+L2lBzouQaXU4nGfsvLFbNa5Z5yMwscZnuUf6i+Hpu6LSTTzoYglIl26fbilVU4MEhDuCDbRuec6+FxHjIjSZkaxL8ctTJHgUtS/O+HE++QmNYWuVnfHK0+Yk83RpmuQ\u003d",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "RikJyJRehnpjlzpLcop14umK/FoE7h1FtpT9HXOfq2zDKd+eVa97pli/uWHYeQqVdTKuWY8YGlIYQCoImawbc19hbN4otEK5xtQmtB3wAVSsTFLzkoZWHebd+Y+2rRH+bnCc93ttlWWRYHqJca2z9SazCLvZn16C25tEsmRtnaI\u003d",
"valid_date": "",
"cvv2": "",
"phone": "15754314122"
}
},
"external_customer_id": "911886886911"
}
}'
##响应结果
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"id": "PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF",
"payer": {
"external_customer_id": "911886886911",
"payment_method": "DEBIT_CARD",
"payer_info": {
"bank_card": {
"number": "oPo8OMwavJJdjEHxtoHIMlS8bZcg4iImwiRNOe6P1Mhx40hKzMj5IzxF0a8VXIJWvkA2Xt2eaw+0hR2be1plRWQSE/f8kc4/sZed1+VNI+vpN2shdqXWdt4GMn3VZx68Be6AnbE/wl8DhfvGjxgKHY9tHMXNoM64oEof2uvH9ag=",
"cvv2": "",
"valid_date": "",
"citizen_id_number": "CT/3BoExrW2m6lHCGvdCCP2MU1DKbGTlg5+hSSXLv2YpXeA2Yt6zCQdbteJ4htcf+6Bda3n8yuXvNPWcohSVRMIT5L0KXf63GDJOtlB8tJFXXKLODGfLRdOOuOKLfN752u3/lrusKDFwN7fuKA5WFJgcn4tG7lKnyXwznuND3XA=",
"phone": "15754314122",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "kT5a+zj+FTwLBTMXdF5m6va0IoNDFnvChA/AkfxPcPTWAwffjuEfKOikkOJ4cmSlERAhnnA8YYFqaqWQ8404Wh2Rv/+uhXjFPIfkosf288ksPWv7M3Nno8z1dxgBjWHJUtSNxbWptj5r6lntT4y325F1Qd3SlV0Wo1TNYnNUTNs="
}
}
}
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF"
},
{
"ref": "confirm",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF/execute"
}]
}
##确认支付
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/PAY_GI3TAOBQGEYDQMRQHAYTMMJRGEZDAMJXGA3TGMKN/execute \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:a/1A+rSDh2EBPGgiqRcET1hNcUtPBjSjQOYZmkqLx1n+IPAeM2p5c29XkB64jMy0fHfzFaK/cCj3vvq/f+o2fqC+WsLWnby34ByxdH+sgTK+I+bkzEdvwD7S9NCWwdMxejwuhBu+HcUn7uLhYgeRdOXfLIH/aThssRoBMTcmeZc="
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"bank_code": "BOC",
"payer_info": {
"bank_card": {
"number": "lFBjnhkXxUXveXJWC92aOnQkKf9aBIbt2fkbk2EJGvzBoF/ddCe/haw9Lb7vT8A9GnVPcrVC+mcwW4Xiu9B4Us7JaQk91Zr6cTCySCIY9CT9t2rb3+dmOwgnJdJsDpc4rk8WdEVxeV36JfFxEGGbarJR9WeVOg90k5a3V6VZWrY\u003d",
"citizen_id_number": "okJyL92gqUjRoU7UCcVnlqEeF+t3pmGbgR/BqGALLIpPXcq3CnPHKI4qSRFArQ2S1/Xw2y4rxUNIZaBAVQUE30mifmYZcJNQo2txCp70RREKo7hRbKH9YVqvCFfMpp40pkJgRnmMKGzSoLlsCPUCbv05Hyq88dbNRAaCdW9i6A8\u003d",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "i4boOVtg1xPuALmKqH9fJG7Jz+zqmqnsPAsjDTYQZgN+nl6paR20hTjDonCP9OSEgvK/DzDHarMKBoP3YWRSvIowrhg0JH6XkOc8LZvXeemuIp4UEAFmT4s7medJEBp7FVlWJ70oCLVBspjbapsJbJEHwND2m7eprGJNvooPa6E\u003d",
"valid_date": "",
"cvv2": "",
"phone": "15754314122",
"verify_code": "409387"
}
},
"external_customer_id": "911886886911"
}
}'
##响应结果
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"settle_date": "20181126",
"id": "PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF",
"state": "TRADE_SUCCESS",
"execute_success_time": "2018-11-26T14:50:56+0800",
"payer": {
"bank_code": "BOC",
"external_customer_id": "911886886911",
"payment_method": "DEBIT_CARD",
"payer_info": {
"bank_card": {
"number": "lBHNHslsTZrwpaSpYw/YecKc7W9zPtivVzw6nwnD4JwY63m9vw6oG4q965B6jsr+SEw3/0e9c6uBIf5qCdl7zBp+Odq9z85ZPG33qB3QSlpn900oP6GawHWMx8y+M8Ev/l2lSXEiwo4jukSNCVKtWkdW6A+X7WxHhErAAdEgb0s=",
"cvv2": "",
"valid_date": "",
"citizen_id_number": "xNeK9I9fZ+pOOCKMYBGda0QkYr742DPvX/w7NwQRLfHaas/xBi/nD7RwbmIXTzBhwq9jASLkgOot4mE9Ozu2B5jq73Vu45IO1bU/VplyM6v3d5uEISJIyKfmuPHSv71MSGbijyzkTbPlxeJVzBVRZWRMoe9vpgc6ro9X78opiwg=",
"phone": "15754314122",
"citizen_id_type": "IDENTITY_CARD",
"verify_code": "409387",
"payer_name": "TRqx2/7sTWernXUV5qRWxEmQ0s+UweQV6OaX5rqLIVazrXMvrGGic3W4jiQDdd5g0hzgwfMxJ+G9kA8bVmoKvihtXO8ldcFLi5u/8eVg9/KsNvs9FlEN1GbPpNM58OTQScvf1wbtZPB8TNh7RNioL9rYywowFsjWcWi3g16oDlI="
},
"payer_agreement": {
"usr_busi_agreement_id": "UB201811261450560000000033862892",
"usr_pay_agreement_id": "P2018080109324500000000041329281"
}
}
}
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF"
},
{
"ref": "apply_to_customs",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF/apply_to_customs"
},
{
"ref": "refund",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF/refund"
},
{
"ref": "asynchronous_refund",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF/asynchronous_refund"
},
{
"ref": "apply_to_ciq",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF/apply_to_ciq"
}]
}
UMF只支持国内银行发行的信用卡和借记卡. 用户支付只支持人民币. UMF可以将人民币转换为 16种外币.
sequenceDiagram
participant 用户
participant 商户
participant UMF
participant 银行
用户-->>商户: 1. 下单
商户-->>用户: 2. 生成订单
用户-->>商户: 3. 确认订单
Note right of 商户: 使用有效的access token发起API请求.
商户-->>UMF: 4. 可选. 获取access token
UMF-->>商户: 5. 返回access_token
Note right of 商户: 使用access token请求API
商户-->>UMF: 6. **可选**. 获取可用的银行
UMF-->>商户: 7. 返回银行列表
商户-->>用户: 8. 向用户展示银行.
商户-->>UMF: 9. 下单
UMF-->>商户: 10. 返回付款对象
用户-->>商户: 11. 填写支付要素, 获取短信验证码.
商户-->>UMF: 12. 调用发送短信验证码接口
UMF-->>商户: 13. UMF返回响应结果.
UMF-->>用户: 14. 向用户发送短信
用户-->>商户:15. 填写验证码并提交
商户-->>UMF: 16. 调用确认支付接口
UMF-->>银行: 17. 请求扣款
银行-->>UMF: 18. 推送结果
UMF-->>商户: 19. 推送支付结果
商户-->>用户: 20. 返回支付结果
时序图描述：
- 用户在商户平台下单.
- 商户生成订单.
- 用户确认订单.
- 可选. 商户 获取access token. 该步骤是可选的. 如果商户已经拥有可以正常调用API的access token, 请忽略步骤4和5.
- UMF返回access token.
- 可选. 商户 查询银行列表. 银行列表基本不变 . 商户可以缓存结果并使用缓存提高加载效率.
- UMF返回可用的银行列表.
- Merchant向用户展示付款页
- 商户向UMF提交订单数据. 调用 下单,请参见右边示例.
- UMF返回一个付款对象.
- 用户选择银行, 填写卡号信息和手机号码, 获取短信验证码. 手机号必须和银行预留号码一致. UMF会校验.
- 商户请求UMF向用户手机号发送短信验证码. 请求 短信验证码.
- 短信发送完成后UMF返回响应数据.
- UMF(或银行)向用户手机号发送短信.
- 用户填写接收到的短信验证码并提交.
- 商户向UMF发起付款请求. 请求 确认付款.
- UMF向银行发起扣款请求.
- UMF接收扣款结果通知.
- UMF向商户推送结果.
- Merchant向用户展示结果.
2.3 微信/支付宝主扫支付
## 微信主扫下单请求:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM=" \
-d '{
"payer": {
"payment_method": "WECHAT_SCAN",
"interface_type": "SERVER_TO_SERVER",
"business_type": "B2C",
"payer_info": {
"name": "sHLA1BgpnUZDUWvgBPhMIRXnJI22IQhZWsfGrBwbiISHrShqLfU32+rSxpCPdQq69C32ekQRj4lUwrDpXQpURMElxN6vs4qEp/SQQ1FKVyMBH3vIqWhDRkhoJ43vV3SbVjaLf5Up0+oQ9/k0Okt0GQ6IIHRsV4/TLg2bil1V84g=",
"phone": "15210909812",
"qr_code_scan": {
"citizen_id_type": "1",
"citizen_id_number": "gog3+QWH5EsaEVa11pxdoGC/l9nHpDV66vhDyjMxyI4N9gNWArrGHhVJjBcpbQX4UmOsboRZ5KM9P73HFuv4mDHoNYoSrQfo/6YodBXciohxlT3h76oYUeLpQ4+xqL2vfvtTANnB+V1gIgH15re4VbY8ofJOwDuHT3+pGiWe6gY="
}
}
},
"order": {
"mer_reference_id": "201707280008",
"mer_date": "20170728",
"amount": {
"total": "0.03",
"currency": "CNY"
},
"order_summary": "maimaimai",
"expire_time ": "360",
"sub_orders": [
{
"mer_sub_reference_id": "072800081",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"trans_code": "01122030",
"is_customs": "TRUE",
"items": [
{
"mer_item_id": "0728000811",
"type": "FOOD",
"name": "yifu1",
"description": "yifu1",
"quantity": "2",
"amount": {
"total": "0.01",
"currency": "CNY"
}
},
{
"mer_item_id": "0728000812",
"type": "ELECTRONIC",
"name": "yifu2",
"description": "yifu2",
"quantity": "3",
"amount": {
"total": "0.01",
"currency": "CNY"
}
}
]
},
{
"mer_sub_reference_id": "072800082",
"amount": {
"total": "0.01",
"currency": "CNY"
},
"trans_code": "03223010"
}
]
},
"notify_url": "http://10.10.178.113:8071/cberest/v1/payments/test/mer",
"risk_info": {
"trans_type": "02",
"goods_type": "1",
"real_name": "0",
"business_type": "Y"
}
}'
## 微信主扫支付响应:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"id": "PAY_GI3TANZSHAYTQMBZGAYTMNJTGUZDAMJXGA3TEOGI",
"state": "TRADE_SUCCESS",
"notify_url": "",
"execute_success_time": "2017-07-28T18:12:58+0800",
"payer": {
"business_type": "B2C",
"interface_type": "SERVER_TO_SERVER",
"payment_method": "WECHAT_SCAN",
"payer_info": {
"qr_code_scan": {
"qr_code_url": "weixin://wxpay/bizpayurl?pr=xd5Jjuh"
},
"phone": ""
}
},
"order": {
"amount": {
"total": "0.03",
"currency": "CNY"
},
"sub_orders": [
{
"mer_sub_reference_id": "072800081",
"trans_code": "01122030",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"is_customs": "TRUE",
"items": [
{
"amount": {
"total": "0.01",
"currency": "CNY"
},
"quantity": "2",
"mer_item_id": "0728000811",
"name": "yifu1",
"description": "yifu1",
"type": "FOOD"
},
{
"amount": {
"total": "0.01",
"currency": "CNY"
},
"quantity": "3",
"mer_item_id": "0728000812",
"name": "yifu2",
"description": "yifu2",
"type": "ELECTRONIC"
}
]
},
{
"mer_sub_reference_id": "072800082",
"trans_code": "03223010",
"amount": {
"total": "0.01",
"currency": "CNY"
}
}
],
"mer_date": "20170728",
"mer_reference_id": "201707280008",
"order_summary": "maimaimai"
}
},
"links": [
{
"ref": "parent_payment",
"method": "GET",
"href": "http://10.10.179.92:8071/cberest/v1/payments/payment/PAY_GI3TANZSHAYTQMBZGAYTMNJTGUZDAMJXGA3TEOGI"
},
{
"ref": "apply_to_customs",
"method": "POST",
"href": "http://10.10.179.92:8071/cberest/v1/payment/PAY_GI3TANZSHAYTQMBZGAYTMNJTGUZDAMJXGA3TEOGI/apply_to_customs"
},
{
"ref": "self_payment_refund",
"method": "GET",
"href": "http://10.10.179.92:8071/cberest/v1/payments/payment//PAY_GI3TANZSHAYTQMBZGAYTMNJTGUZDAMJXGA3TEOGI/self_payment_refund"
},
{
"ref": "refund",
"method": "POST",
"href": "http://10.10.179.92:8071/cberest/v1/payment/PAY_GI3TANZSHAYTQMBZGAYTMNJTGUZDAMJXGA3TEOGI/refund"
}
]
}
## 支付宝主扫支付请求:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM=" \
-d '{
"payer": {
"payment_method": "ALIPAY_SCAN",
"interface_type": "SERVER_TO_SERVER",
"business_type": "B2C",
"payer_info": {
"name": "sHLA1BgpnUZDUWvgBPhMIRXnJI22IQhZWsfGrBwbiISHrShqLfU32+rSxpCPdQq69C32ekQRj4lUwrDpXQpURMElxN6vs4qEp/SQQ1FKVyMBH3vIqWhDRkhoJ43vV3SbVjaLf5Up0+oQ9/k0Okt0GQ6IIHRsV4/TLg2bil1V84g=",
"phone": "15210909812",
"qr_code_scan": {
"citizen_id_type": "1",
"citizen_id_number": "gog3+QWH5EsaEVa11pxdoGC/l9nHpDV66vhDyjMxyI4N9gNWArrGHhVJjBcpbQX4UmOsboRZ5KM9P73HFuv4mDHoNYoSrQfo/6YodBXciohxlT3h76oYUeLpQ4+xqL2vfvtTANnB+V1gIgH15re4VbY8ofJOwDuHT3+pGiWe6gY="
}
}
},
"order": {
"mer_reference_id": "201707280008",
"mer_date": "20170728",
"amount": {
"total": "0.03",
"currency": "CNY"
},
"order_summary": "maimaimai",
"expire_time ": "360",
"sub_orders": [
{
"mer_sub_reference_id": "072800081",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"trans_code": "01122030",
"is_customs": "TRUE",
"items": [
{
"mer_item_id": "0728000811",
"type": "FOOD",
"name": "yifu1",
"description": "yifu1",
"quantity": "2",
"amount": {
"total": "0.01",
"currency": "CNY"
}
},
{
"mer_item_id": "0728000812",
"type": "ELECTRONIC",
"name": "yifu2",
"description": "yifu2",
"quantity": "3",
"amount": {
"total": "0.01",
"currency": "CNY"
}
}
]
},
{
"mer_sub_reference_id": "072800082",
"amount": {
"total": "0.01",
"currency": "CNY"
},
"trans_code": "03223010"
}
]
},
"notify_url": "http://10.10.178.113:8071/cberest/v1/payments/test/mer",
"risk_info": {
"trans_type": "02",
"goods_type": "1",
"real_name": "0",
"business_type": "Y"
}
}'
## 支付宝主扫支付响应:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"id": "PAY_GI3TANZSHAYTQMBZGAYTMNJTGUZDAMJXGA3TEOGI",
"state": "TRADE_SUCCESS",
"notify_url": "",
"execute_success_time": "2017-07-28T18:12:58+0800",
"payer": {
"business_type": "B2C",
"interface_type": "SERVER_TO_SERVER",
"payment_method": "ALIPAY_SCAN",
"payer_info": {
"qr_code_scan": {
"qr_code_url": "weixin://wxpay/bizpayurl?pr=xd5Jjuh"
},
"phone": ""
}
},
"order": {
"amount": {
"total": "0.03",
"currency": "CNY"
},
"sub_orders": [
{
"mer_sub_reference_id": "072800081",
"trans_code": "01122030",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"is_customs": "TRUE",
"items": [
{
"amount": {
"total": "0.01",
"currency": "CNY"
},
"quantity": "2",
"mer_item_id": "0728000811",
"name": "yifu1",
"description": "yifu1",
"type": "FOOD"
},
{
"amount": {
"total": "0.01",
"currency": "CNY"
},
"quantity": "3",
"mer_item_id": "0728000812",
"name": "yifu2",
"description": "yifu2",
"type": "ELECTRONIC"
}
]
},
{
"mer_sub_reference_id": "072800082",
"trans_code": "03223010",
"amount": {
"total": "0.01",
"currency": "CNY"
}
}
],
"mer_date": "20170728",
"mer_reference_id": "201707280008",
"order_summary": "maimaimai"
}
},
"links": [
{
"ref": "parent_payment",
"method": "GET",
"href": "http://10.10.179.92:8071/cberest/v1/payments/payment/PAY_GI3TANZSHAYTQMBZGAYTMNJTGUZDAMJXGA3TEOGI"
},
{
"ref": "apply_to_customs",
"method": "POST",
"href": "http://10.10.179.92:8071/cberest/v1/payment/PAY_GI3TANZSHAYTQMBZGAYTMNJTGUZDAMJXGA3TEOGI/apply_to_customs"
},
{
"ref": "self_payment_refund",
"method": "GET",
"href": "http://10.10.179.92:8071/cberest/v1/payments/payment//PAY_GI3TANZSHAYTQMBZGAYTMNJTGUZDAMJXGA3TEOGI/self_payment_refund"
},
{
"ref": "refund",
"method": "POST",
"href": "http://10.10.179.92:8071/cberest/v1/payment/PAY_GI3TANZSHAYTQMBZGAYTMNJTGUZDAMJXGA3TEOGI/refund"
}
]
}
UMF返回二维码字符串. 用户使用微信扫描二维码完成付款.
sequenceDiagram
participant 用户
participant 商户
participant UMF
participant 微信/支付宝
用户-->>商户: 1. 下单
商户-->>用户: 2. 生成订单
用户-->>商户: 3. 确认订单
Note right of 商户: 使用有效的access token发起API请求
商户-->>UMF: 4. 可选. 获取access token
UMF-->>商户: 5. 返回access_token
Note right of 商户: 使用access token调用API
商户-->>UMF: 6. 下单
UMF-->>微信/支付宝: 7. 发起下单请求
微信/支付宝-->>UMF: 8. 返回二维码字符串
UMF-->>商户: 9. 返回扫码对象
商户-->>用户: 10. 将字符串转换为二维码展示给用户
用户-->>微信/支付宝: 11. 扫码支付完成
微信/支付宝-->>UMF: 12. 返回扣款通知
UMF-->>商户: 13. 返回支付结果
商户-->>用户: 14. 返回支付结果
Explanation of the sequence chart：
- 用户在商户平台下单.
- 商户生成订单.
- 用户确认订单.
- 可选. 商户 获取access token. 该步骤是可选的. 如果商户已经拥有可以正常调用API的access token, 请忽略步骤4和5.
- UMF返回access token.
- 商户向UMF提交订单数据. 调用 下单,请参见右边示例.
- UMF向微信/支付宝发送支付请求.
- 微信/支付宝向UMF返回二维码字符串.
- UMF返回扫码对象.
- 商户将字符串转换为二维码展示给用户.
- 用户扫码支付完成.
- UMF接收扣款通知.
- UMF向商户返回支付结果.
- 商户向用户展示支付结果.
2.4 微信公众号支付(关注商户公众号)
下单
## 请求数据:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/PAY_GI3TAOBQGEYDQMRQHAYTMMJRGEZDAMJXGA3TGMKN/execute \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:a/1A+rSDh2EBPGgiqRcET1hNcUtPBjSjQOYZmkqLx1n+IPAeM2p5c29XkB64jMy0fHfzFaK/cCj3vvq/f+o2fqC+WsLWnby34ByxdH+sgTK+I+bkzEdvwD7S9NCWwdMxejwuhBu+HcUn7uLhYgeRdOXfLIH/aThssRoBMTcmeZc="
-d '{
"payer": {
"payment_method": "WECHAT_WEB",
"payer_info": {
"phone": "15712889715",
"name": "田永辉",
"wechat_in_app_web": {
"app_id":"W123432345435234125"
"citizen_id_type": "IDENTITY_CARD",
"citizen_id_number": "370124197111250021",
"open_id": "oEufkwGogWxfOlYilVepVpX4sUcs"
}
},
"interface_type": "SERVER_TO_SERVER",
"business_type": "B2C"
},
"order": {
"mer_reference_id": "150234403956",
"mer_date": "20170810",
"amount": {
"total": "0.1",
"currency": "CNY"
},
"order_summary": "卡卡卡",
"expire_time": "1800",
"user_ip": "106.38.123.141",
"sub_orders": [
{
"mer_sub_reference_id": "150234403956",
"trans_code": "02223022",
"amount": {
"total": "0.1",
"currency": "CNY"
},
"is_customs": "FALSE"
}
]
},
"notify_url": "http://hsk9715.vicp.io/api/shop/so_umfwxpayPlugin_payment-callback/execute.do",
"risk_info": {
"trans_type": "02",
"goods_type": "1",
"real_name": "0",
"business_type": "Y"
}
}'
## 响应数据:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"id": "PAY_GM3TAOBRGAYTGNBYGU2DSMZUGQZDAMJXGA4DCMGJ",
"state": "TRADE_SUCCESS",
"notify_url": "",
"execute_success_time": "2017-08-10T13:48:50+0800",
"payer": {
"business_type": "B2C",
"interface_type": "SERVER_TO_SERVER",
"payment_method": "WECHAT_WEB",
"payer_info": {
"wechat_in_app_web": {
"pay_info": {
"nonce_str": "1etJka9rTTvUs4p4YfNZBwGhIVa0XL",
"package": "prepay_id=wx201708101348505fcfd48f770096656564",
"time_stamp": "1502344130",
"app_id": "wx740a066b0a94fa6d",
"sign_type": "MD5",
"pay_sign": "DB5A4E01615A591497AEBB6181911007"
}
}
}
},
"order": {
"user_ip": "106.38.123.141",
"amount": {
"total": "0.1",
"currency": "CNY"
},
"sub_orders": [
{
"mer_sub_reference_id": "150234403956",
"trans_code": "02223022",
"amount": {
"total": "0.1",
"currency": "CNY"
},
"is_customs": "FALSE"
}
],
"mer_date": "20170810",
"expire_time": "1800",
"mer_reference_id": "150234403956",
"order_summary": "卡卡卡"
}
},
"links": [
{
"ref": "parent_payment",
"method": "GET",
"href": "http://uatfx.soopay.net/cberest/v1/payments/payment/PAY_GM3TAOBRGAYTGNBYGU2DSMZUGQZDAMJXGA4DCMGJ"
},
{
"ref": "apply_to_customs",
"method": "POST",
"href": "http://uatfx.soopay.net/cberest/v1/payment/PAY_GM3TAOBRGAYTGNBYGU2DSMZUGQZDAMJXGA4DCMGJ/apply_to_customs"
},
{
"ref": "self_payment_refund",
"method": "GET",
"href": "http://uatfx.soopay.net/cberest/v1/payments/payment//PAY_GM3TAOBRGAYTGNBYGU2DSMZUGQZDAMJXGA4DCMGJ/self_payment_refund"
},
{
"ref": "refund",
"method": "POST",
"href": "http://uatfx.soopay.net/cberest/v1/payment/PAY_GM3TAOBRGAYTGNBYGU2DSMZUGQZDAMJXGA4DCMGJ/refund"
}
]
}
商户可以在微信公众账号向用户推送商品. 商户的购物页面加入微信支付后, 用户便可以在购物页面购买商品.
sequenceDiagram
participant 用户
participant 微信浏览器
participant 商户
participant UMF
participant 微信
用户-->>商户: 1. 下单
商户-->>用户: 2. 生成订单
用户-->>微信浏览器: 3. 确认订单
微信浏览器-->>UMF: 4. 请求认证页面(html和javascript)
UMF-->>微信浏览器: 5. 返回认证页面.
微信浏览器-->>微信: 6. 商户使用自己的app_id请求微信获取open_id
微信-->>微信浏览器: 7. 返回open_id
微信浏览器-->>商户: 8. 跳转到通知地址
商户-->>微信浏览器: 9. 返回正在处理页面.
微信浏览器-->>商户: 10. 发起微信支付.
Note right of 商户: 带着access token请求API
商户-->>UMF: 11. 付款请求(app_id必传)
UMF-->>微信: 12. 付款请求
微信-->>UMF: 13. 返回支付信息
UMF-->>商户: 14. 返回WeChat_in_app_web对象
商户-->>微信浏览器: 15. 唤醒支付插件
微信浏览器-->>微信浏览器: 16. 请求微信JS-API
用户-->>微信: 17. 输入密码, 完成支付
微信-->>微信浏览器: 18. 返回等待信息.
微信浏览器-->>微信浏览器: 19. 跳转到ret_url.
微信-->>UMF: 20. 扣款结果通知.
UMF-->>商户: 21. 返回支付结果.
时序图描述：
- 用户在商户平台下单.
- 商户生成订单.
- 用户确认订单.
- 可选. 商户 获取access token. 该步骤是可选的. 如果商户已经拥有可以正常调用API的access token, 请忽略步骤4和5.
- UMF返回认证页面.
- 认证页面请求获取open_id.
- 微信返回当前微信用户的open_id.
- 认证页面跳转到通知地址(步骤4).
- 可选. 商户返回正在处理页面.
- 可选. 正在处理页面请求付款.
- 商户向UMF发送支付请求.调用 下单.app_id必传
- UMF向微信发起支付请求.
- 微信向UMF返回支付信息.
- UMF返回WeChat_in_app_web对象.
- 商户向浏览器返回WeChat_in_app_web对象.
- 返回页唤醒微信支付插件(微信JS-API).
- 用户在微信浏览器输入密码完成支付.
- 微信返回正在处理页面.
- 正在处理页面ret_url(步骤11).
- WeChat向UMF返回支付结果.
- UMF向商户发送支付结果.
2.5 微信公众号支付(关注联动公众号)
下单
## 请求数据:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/PAY_GI3TAOBQGEYDQMRQHAYTMMJRGEZDAMJXGA3TGMKN/execute \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:a/1A+rSDh2EBPGgiqRcET1hNcUtPBjSjQOYZmkqLx1n+IPAeM2p5c29XkB64jMy0fHfzFaK/cCj3vvq/f+o2fqC+WsLWnby34ByxdH+sgTK+I+bkzEdvwD7S9NCWwdMxejwuhBu+HcUn7uLhYgeRdOXfLIH/aThssRoBMTcmeZc="
-d '{
"payer": {
"payment_method": "WECHAT_WEB",
"payer_info": {
"phone": "15712889715",
"name": "田永辉",
"wechat_in_app_web": {
"citizen_id_type": "IDENTITY_CARD",
"citizen_id_number": "370124197111250021",
"open_id": "oEufkwGogWxfOlYilVepVpX4sUcs"
}
},
"interface_type": "SERVER_TO_SERVER",
"business_type": "B2C"
},
"order": {
"mer_reference_id": "150234403956",
"mer_date": "20170810",
"amount": {
"total": "0.1",
"currency": "CNY"
},
"order_summary": "卡卡卡",
"expire_time": "1800",
"user_ip": "106.38.123.141",
"sub_orders": [
{
"mer_sub_reference_id": "150234403956",
"trans_code": "02223022",
"amount": {
"total": "0.1",
"currency": "CNY"
},
"is_customs": "FALSE"
}
]
},
"notify_url": "http://hsk9715.vicp.io/api/shop/so_umfwxpayPlugin_payment-callback/execute.do",
"risk_info": {
"trans_type": "02",
"goods_type": "1",
"real_name": "0",
"business_type": "Y"
}
}'
## 响应数据:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"id": "PAY_GM3TAOBRGAYTGNBYGU2DSMZUGQZDAMJXGA4DCMGJ",
"state": "TRADE_SUCCESS",
"notify_url": "",
"execute_success_time": "2017-08-10T13:48:50+0800",
"payer": {
"business_type": "B2C",
"interface_type": "SERVER_TO_SERVER",
"payment_method": "WECHAT_WEB",
"payer_info": {
"wechat_in_app_web": {
"pay_info": {
"nonce_str": "1etJka9rTTvUs4p4YfNZBwGhIVa0XL",
"package": "prepay_id=wx201708101348505fcfd48f770096656564",
"time_stamp": "1502344130",
"app_id": "wx740a066b0a94fa6d",
"sign_type": "MD5",
"pay_sign": "DB5A4E01615A591497AEBB6181911007"
}
}
}
},
"order": {
"user_ip": "106.38.123.141",
"amount": {
"total": "0.1",
"currency": "CNY"
},
"sub_orders": [
{
"mer_sub_reference_id": "150234403956",
"trans_code": "02223022",
"amount": {
"total": "0.1",
"currency": "CNY"
},
"is_customs": "FALSE"
}
],
"mer_date": "20170810",
"expire_time": "1800",
"mer_reference_id": "150234403956",
"order_summary": "卡卡卡"
}
},
"links": [
{
"ref": "parent_payment",
"method": "GET",
"href": "http://uatfx.soopay.net/cberest/v1/payments/payment/PAY_GM3TAOBRGAYTGNBYGU2DSMZUGQZDAMJXGA4DCMGJ"
},
{
"ref": "apply_to_customs",
"method": "POST",
"href": "http://uatfx.soopay.net/cberest/v1/payment/PAY_GM3TAOBRGAYTGNBYGU2DSMZUGQZDAMJXGA4DCMGJ/apply_to_customs"
},
{
"ref": "self_payment_refund",
"method": "GET",
"href": "http://uatfx.soopay.net/cberest/v1/payments/payment/PAY_GM3TAOBRGAYTGNBYGU2DSMZUGQZDAMJXGA4DCMGJ/self_payment_refund"
},
{
"ref": "refund",
"method": "POST",
"href": "http://uatfx.soopay.net/cberest/v1/payment/PAY_GM3TAOBRGAYTGNBYGU2DSMZUGQZDAMJXGA4DCMGJ/refund"
}
]
}
商户可以在微信公众账号向用户推送商品. 商户的购物页面加入微信支付后, 用户便可以在购物页面购买商品.
sequenceDiagram
participant 用户
participant 微信浏览器
participant 商户
participant UMF
participant 微信
用户-->>商户: 1. 下单
商户-->>用户: 2. 生成订单
用户-->>微信浏览器: 3. 确认订单
微信浏览器-->>UMF: 4. 请求认证页面(html和javascript)
UMF-->>微信浏览器: 5. 返回认证页面.
微信浏览器-->>UMF: 6. 商户请求联动获取open_id
UMF-->>微信: 7. 联动请求微信获取open_id
微信-->>UMF: 8. 返回open_id
UMF-->>微信浏览器: 9. 返回open_id
微信浏览器-->>商户: 10. 跳转到通知地址
商户-->>微信浏览器: 11. 返回正在处理页面.
微信浏览器-->>商户: 12. 发起微信支付.
Note right of 商户: 带着access token请求API
商户-->>UMF: 13. 付款请求
UMF-->>微信: 14. 付款请求
微信-->>UMF: 15. 返回支付信息
UMF-->>商户: 16. 返回WeChat_in_app_web对象
商户-->>微信浏览器: 17. 唤醒支付插件
微信浏览器-->>微信浏览器: 18. 请求微信JS-API
用户-->>微信: 19. 输入密码, 完成支付
微信-->>微信浏览器: 20. 返回等待信息.
微信浏览器-->>微信浏览器: 21. 跳转到ret_url.
微信-->>UMF: 22. 扣款结果通知.
UMF-->>商户: 23. 返回支付结果.
时序图描述：
- 用户在商户平台下单.
- 商户生成订单.
- 用户确认订单.
- 可选. 商户 获取access token. 该步骤是可选的. 如果商户已经拥有可以正常调用API的access token, 请忽略步骤4和5.
- UMF返回认证页面.
- 商户请求UMF获取open_id.
- UMF请求微信获取open_id.
- 微信返回open_id.
- UMF返回open_id.
- 认证页面跳转到通知地址(步骤4).
- 可选. 商户返回正在处理页面.
- 可选. 正在处理页面请求付款.
- 商户向UMF发送支付请求.调用 下单.
- UMF向微信发起支付请求.
- 微信向UMF返回支付信息.
- UMF返回WeChat_in_app_web对象.
- 商户向浏览器返回WeChat_in_app_web对象.
- 返回页唤醒微信支付插件(微信JS-API).
- 用户在微信浏览器输入密码完成支付.
- 微信返回正在处理页面.
- 正在处理页面ret_url(步骤11).
- WeChat向UMF返回支付结果.
- UMF向商户发送支付结果.
2.6 微信App支付
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM=" \
-d '{
"payer": {
"payment_method": "WECHAT_IN_APP",
"payer_info": {
"phone": "13552105741",
"name": "omkW1FPZP5Agow/WBn8yXks/QJa6/KlYW3N0dfLzWgA2UDlT4AlG02KD/aTAst370+DxTpyzqeYoAU3Z3qjKQZs5UlKyh6iczK7dIsJurJ9VaY0iZkNBHG4gDC9GvoikzAN94qaieS9E7vsO2PgSsfKjCmsUGUDAXUA0FpkBnvU\u003d",
"wechat_in_app": {
"citizen_id_type": "IDENTITY_CARD",
"citizen_id_number": "p84fe8uw8uDr6sarv1NAVfLpNbO80/e0qYgy7ySbuVDkwFXf1wCevj4X03sZcEOoed+i9iK6I7M/a9LBv/BPxSou/IgOlaamr/H79Lb0H1afZhcfCE159OK9pjrdhvjCI+5jIdqp11Fe9Pa69Fncq1d11u0bjY2cgBlEhxq0Z94\u003d",
"app_id": "wxc03854ecf3af1b0a"
}
},
"interface_type": "SERVER_TO_SERVER",
"external_customer_id": "UMP1499826888843602",
"business_type": "B2C"
},
"order": {
"mer_reference_id": "0202161650404101",
"mer_date": "20180202",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"order_summary": "CrossBorderOrderSummary",
"expire_time": "360",
"user_ip": "10.10.70.134",
"sub_orders": [{
"mer_sub_reference_id": "0202161650405102",
"trans_code": "03223010",
"amount": {
"total": "0.01",
"currency": "CNY"
},
"is_customs": "False",
"invoice_id": "123456"
},
{
"trans_code": "01122030",
"amount": {
"total": "0.01",
"currency": "CNY"
},
"is_customs": "False",
"invoice_id": "123456",
"items": [{
"mer_item_id": "0202161650405103",
"type": "FOOD",
"name": "banana",
"quantity": "2",
"description": "banana",
"amount": {
"total": "0.01",
"currency": "CNY"
}
}]
}],
"sub_mer_id": "umfsubmer001"
},
"notify_url": "http://10.10.38.49:2216/spay_rest/payments/test/mer",
"ret_url": "http://10.10.38.49:2213/notify0000V4.jsp",
"risk_info": {
"trans_type": "02"
}
}'
## Response data:
{
"meta": {
"ret_msg": "return of bank failure",
"ret_code": "00080557"
},
"payment": {
"risk_info": {
"trans_type": "02"
},
"notify_url": "http://10.10.38.49:2216/spay_rest/payments/test/mer",
"payer": {
"external_customer_id": "UMP1499826888843602",
"business_type": "B2C",
"interface_type": "SERVER_TO_SERVER",
"payment_method": "WECHAT_IN_APP",
"payer_info": {
"wechat_in_app": {
"citizen_id_number": "s3NvVUiE9lM+q++zzeQkaMiAHjOGp28BDE2qq/OOMnunSdj95kiNODBjg7PGUVg7+jHZqMjtFVJflhYUsQtu9ke3aJOyPVjOz1dp0FgrdBY6ttniM2AgeHgU8gP+sGKeBbzrmZsmIlZAc3PmO1eHHCHg+BrbZgx98Rd4XWT9MOI=",
"citizen_id_type": "IDENTITY_CARD",
"app_id": "wxc03854ecf3af1b0a"
},
"phone": "13552105741",
"name": "XkIQ7CjKj44SGKvk7La7rmq4LEG8xRLhCb+11ylaC3x5m8DpSgOIvUzzYsMg15dRVM2PjEHP2qvb3zJP4l0uDrZsfrLPSjaBoKqh4uFx+ezSVJ7/AJIwEAIjVO1Yb8/av0ymKxXik5hewIVTITPfOS+gcYgYdB9qREkFpGt4Nwg="
}
},
"ret_url": "http://10.10.38.49:2213/notify0000V4.jsp",
"is_from_US": "N",
"order": {
"user_ip": "10.10.70.134",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"sub_orders": [{
"mer_sub_reference_id": "0202161650405102",
"trans_code": "03223010",
"amount": {
"total": "0.01",
"currency": "CNY"
},
"invoice_id": "123456",
"is_customs": "False"
},
{
"mer_sub_reference_id": "0202161646695122",
"trans_code": "01122030",
"amount": {
"total": "0.01",
"currency": "CNY"
},
"invoice_id": "123456",
"is_customs": "False",
"items": [{
"amount": {
"total": "0.01",
"currency": "CNY"
},
"quantity": "2",
"mer_item_id": "0202161650405103",
"name": "banana",
"description": "banana",
"type": "FOOD"
}]
}],
"sub_mer_id": "umfsubmer001",
"mer_date": "20180202",
"expire_time": "360",
"mer_reference_id": "0202161650404101",
"order_summary": "CrossBorderOrderSummary"
}
}
}
商户可以整合微信支付SDK到自己的APP里.当用户在其他的app里发起付款时, 微信可以处理此次付款. 一旦交易完成, 当前页面将跳转到用户的app.
sequenceDiagram
participant 用户
participant 商户APP客户端
participant 商户APP服务端
participant UMF
participant 微信
用户-->> 商户APP客户端: 1. 下单
商户APP客户端-->>用户: 2. 生成订单
用户-->>商户APP客户端: 3. 确认订单
商户APP客户端-->>商户APP服务端: 4. 发起付款请求
Note right of 商户APP服务端: 使用有效的access token发起API请求
商户APP服务端-->>UMF: 5. 可选. 获取access token
UMF-->>商户APP服务端: 6. 返回access_token
Note right of 商户APP服务端: 使用access token请求API
商户APP服务端-->>UMF: 7. 下单(app_id必传)
UMF-->>微信: 8. 发起微信APP支付
微信-->>UMF: 9. 返回JSON字符串, 支付信息
UMF-->>商户APP服务端: 10. 返回WeChat_in_app对象
商户APP服务端-->>微信: 11. 唤醒支付插件
微信-->>用户: 12. 支付插件唤起
用户-->>微信: 13. 输入密码, 完成支付
微信-->>UMF: 14. 扣款结果通知
UMF-->>商户APP服务端: 15. 返回支付结果
商户APP服务端-->>商户APP客户端: 16. 返回支付结果
商户APP客户端-->>用户: 17. 返回支付结果
时序图描述：
- 用户在商户平台下单.
- 商户APP客户端生成订单.
- 用户在APP里确认订单.
- 商户APP客户端向商户APP服务端发起付款.
- 可选. 商户 获取access token. 该步骤是可选的. 如果商户已经拥有可以正常调用API的access token, 请忽略步骤4和5.
- UMF返回access token.
- 商户向UMF提交订单数据.app_id必传. 调用 下单,请参见右边示例.
- UMF向微信发送支付请求.
- 微信向UMF返回支付信息.
- UMF向商户app服务端返回WeChat_in_app对象.
- 商户app服务端唤醒微信支付插件.
- 微信支付插件唤起.
- 用户在微信浏览器里输入密码并完成支付.
- UMF接收到扣款通知.
- UMF向商户app服务端返回支付结果.
- 商户app服务端发送结果给商户app客户端.
- 商户app客户端向用户展示支付结果.
2.7 支付宝H5支付
sequenceDiagram
participant 用户
participant 商户
participant UMF
participant 支付宝
用户-->>商户: 1. 选购商品
商户-->>用户: 2. 生成订单
用户-->>商户: 3. 确认订单
Note right of 商户: 使用有效的access token发起API请求
商户-->>UMF: 4. 可选. 获取access token
UMF-->>商户: 5. 返回access_token
Note right of 商户: 使用access token调用API
商户-->>UMF: 6. 付款请求
UMF-->>支付宝: 7. 付款退款
支付宝-->>UMF: 8. 返回支付链接
UMF-->>商户: 9. 返回支付链接
商户-->>商户: 10. 商户在H5浏览器重定向到此链接
用户-->>支付宝: 11. 支付
支付宝-->>UMF: 12. 返回扣款结果
UMF-->>商户: 13. 返回支付结果
商户-->>用户: 14. 返回支付结果
时序图描述：
- 用户在商户平台选购商品.
- 商户平台生成订单.
- 用户确认订单.
- 可选. 商户 获取 access token. 该步骤是可选的. 如果商户已经拥有可以正常调用API的access token, 请忽略步骤4和5.
- UMF返回access token.
- 商户向UMF提交订单数据. 调用 下单.
- UMF向支付宝发送支付请求.
- 支付宝向UMF返回支付链接.
- UMF向商户返回支付链接.
- 商户在H5浏览器重定向到此链接.
- 用户在支付页面确认完成支付.
- 支付宝向UMF返回扣款结果.
- UMF向商户返回支付结果.
- 商户向用户展示支付结果.
2.8 微信H5支付
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM=" \
-d '{
"payer": {
"payment_method": "WECHAT_H5",
"interface_type": "SERVER_TO_SERVER",
"business_type": "B2C",
"payer_info": {
"name": "vOFkjpIvPwrROXTwR+AIpesiOKRtVosDlwgzkmcUFfY/apC/wlbq9DSJzGFyjhpvYFevfLr9gJ2ML/H1DNPz38tSPYb6O4LpAxCvImYuknDNnrCtp5eiweQdVV8N5Uw7h4pyrsO+ZRt+zxtsdDgCfgHhEH5rewNwAVf4l58dkO8=",
"phone": "*",
"wechat_H5": {
"citizen_id_type": "IDENTITY_CARD",
"citizen_id_number": "ei5fjg/2qRGlObHlp4kcMBJXbSGs67MkoR6CZXgUyLBjIsYskLyXvqLADNZ2/6DttHbMhdiNF3Qt3CetAe8pdChY1J+XVf5sfWV3CEwlzrttgOAGTy+d7BCtg6rUQmOIYn9VbDd3g47mCdRQfLeEBubrfjzD4QwMTCWPLidzLrY="
}
}
},
"order": {
"mer_reference_id": "20171121155725",
"mer_date": "20171121",
"user_ip": "*",
"amount": {
"total": "0.03",
"currency": "CNY"
},
"order_summary": "maimaimai",
"expire_time ": "360",
"sub_orders": [{
"mer_sub_reference_id": "201711211557251",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"trans_code": "01122030",
"sub_trans_type": "1",
"is_customs": "TRUE",
"items": [{
"mer_item_id": "112115572511",
"type": "FOOD",
"name": "yifu1",
"description": "yifu1",
"quantity": "2",
"amount": {
"total": "0.01",
"currency": "CNY"
}
},
{
"mer_item_id": "112115572512",
"type": "ELECTRONIC",
"name": "yifu2",
"description": "yifu2",
"quantity": "3",
"amount": {
"total": "0.01",
"currency": "CNY"
}
}]
},
{
"mer_sub_reference_id": "201711211557252",
"amount": {
"total": "0.01",
"currency": "CNY"
},
"trans_code": "03223010",
"sub_trans_type": "3"
}]
},
"notify_url": "http://uatfx.soopay.net/page-test/notify.do",
"risk_info": {
"trans_type": "02",
"goods_type": "1",
"real_name": "0",
"business_type": "Y"
}
}'
## Response data:
{
"meta":{
"ret_msg":"successful transaction",
"ret_code":"0000"
},
"payment":{
"id":"PAY_GM3TCMJSGQYTKMBUGY3TCMBYGUZDAMJXGEYTENEP",
"state":"WAIT_BUYER_PAY",
"notify_url":"",
"execute_success_time":"2017-11-24T15:04:11+0800",
"payer":{
"business_type":"B2C",
"interface_type":"SERVER_TO_SERVER",
"payment_method":"WECHAT_H5",
"payer_info":{
"wechat_H5":{
"wechat_H5_url":"https%3A%2F%2Fwx.tenpay.com%2Fcgi-bin%2Fmmpayweb-bin%2Fcheckmweb%3Fprepay_id%3Dwx201711241504110aaabd9ebe0170192378%26package%3D768167383"
},
"phone":"*"
}
},
"is_from_US":"N",
"order":{
"user_ip":"*",
"amount":{
"total":"0.03",
"currency":"CNY"
},
"sub_orders":[
{
"mer_sub_reference_id":"2017112415491",
"trans_code":"01122030",
"amount":{
"total":"0.02",
"currency":"CNY"
},
"is_customs":"TRUE",
"items":[
{
"amount":{
"total":"0.01",
"currency":"CNY"
},
"quantity":"2",
"mer_item_id":"1124154911",
"name":"yifu1",
"description":"yifu1",
"type":"FOOD"
},
{
"amount":{
"total":"0.01",
"currency":"CNY"
},
"quantity":"3",
"mer_item_id":"1124154912",
"name":"yifu2",
"description":"yifu2",
"type":"ELECTRONIC"
}
]
},
{
"mer_sub_reference_id":"2017112415492",
"trans_code":"03223010",
"amount":{
"total":"0.01",
"currency":"CNY"
}
}
],
"mer_date":"20171124",
"mer_reference_id":"201711241549",
"order_summary":"maimaimai"
}
},
"links":[
{
"ref":"parent_payment",
"method":"GET",
"href":"http://fx.soopay.net/cberest/v1/payments/payment/PAY_GM3TCMJSGQYTKMBUGY3TCMBYGUZDAMJXGEYTENEP"
},
{
"ref":"apply_to_customs",
"method":"POST",
"href":"http://fx.soopay.net/cberest/v1/payments/payment/PAY_GM3TCMJSGQYTKMBUGY3TCMBYGUZDAMJXGEYTENEP/apply_to_customs"
},
{
"ref": "self_payment_refund",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GM3TCMJSGQYTKMBUGY3TCMBYGUZDAMJXGEYTENEP/self_payment_refund"
},
{
"ref":"refund",
"method":"POST",
"href":"http://fx.soopay.net/cberest/v1/payments/payment/PAY_GM3TCMJSGQYTKMBUGY3TCMBYGUZDAMJXGEYTENEP/refund"
}
]
}
sequenceDiagram
participant 用户
participant 商户
participant UMF
participant 微信
用户-->>商户: 1. 选购商品
商户-->>用户: 2. 生成订单
用户-->>商户: 3. 确认订单
Note right of 商户: 使用有效的access token发起API请求
商户-->>UMF: 4. 可选. 获取access token
UMF-->>商户: 5. 返回access_token
Note right of 商户: 使用access token调用API
商户-->>UMF: 6. 付款请求
UMF-->>微信: 7. 付款退款
微信-->>UMF: 8. 返回支付链接
UMF-->>商户: 9. 返回支付链接
商户-->>商户: 10. 商户在H5浏览器重定向到此链接
用户-->>微信: 11. 支付
微信-->>UMF: 12. 返回扣款结果
UMF-->>商户: 13. 返回支付结果
商户-->>用户: 14. 返回支付结果
时序图描述：
- 用户在商户平台选购商品.
- 商户平台生成订单.
- 用户确认订单.
- 可选. 商户 获取 access token. 该步骤是可选的. 如果商户已经拥有可以正常调用API的access token, 请忽略步骤4和5.
- UMF返回access token.
- 商户向UMF提交订单数据. 调用 下单.
- UMF向微信发送支付请求.
- 微信向UMF返回支付链接.
- UMF向商户返回支付链接.
- 商户在H5浏览器重定向到此链接.
- 用户在支付页面确认完成支付.
- 微信向UMF返回扣款结果.
- UMF向商户返回支付结果.
- 商户向用户展示支付结果.
2.9 微信小程序支付
商户可以在微信小程序向用户推送商品. 商户的购物页面加入微信支付后, 用户便可以在购物页面购买商品.
sequenceDiagram
participant 用户
participant 微信浏览器
participant 商户
participant UMF
participant 微信
用户-->>商户: 1. 下单
商户-->>用户: 2. 生成订单
用户-->>微信浏览器: 3. 确认订单
微信浏览器-->>UMF: 4. 请求认证页面(html和javascript)
UMF-->>微信浏览器: 5. 返回认证页面.
微信浏览器-->>微信: 6. 商户使用自己小程序的app_id请求微信获取open_id
微信-->>微信浏览器: 7. 返回open_id
微信浏览器-->>商户: 8. 跳转到通知地址
商户-->>微信浏览器: 9. 返回正在处理页面.
微信浏览器-->>商户: 10. 发起微信支付.
Note right of 商户: 带着access token请求API
商户-->>UMF: 11. 付款请求(小程序app_id必传)
UMF-->>微信: 12. 付款请求
微信-->>UMF: 13. 返回支付信息
UMF-->>商户: 14. 返回wechat_mp对象
商户-->>微信浏览器: 15. 唤醒支付插件
微信浏览器-->>微信浏览器: 16. 请求微信JS-API
用户-->>微信: 17. 输入密码, 完成支付
微信-->>微信浏览器: 18. 返回等待信息.
微信浏览器-->>微信浏览器: 19. 跳转到ret_url.
微信-->>UMF: 20. 扣款结果通知.
UMF-->>商户: 21. 返回支付结果.
时序图描述：
- 用户在商户平台下单.
- 商户生成订单.
- 用户确认订单.
- 可选. 商户 获取access token. 该步骤是可选的. 如果商户已经拥有可以正常调用API的access token, 请忽略步骤4和5.
- UMF返回认证页面.
- 认证页面请求获取open_id.
- 微信返回当前微信用户的open_id.
- 认证页面跳转到通知地址(步骤4).
- 可选. 商户返回正在处理页面.
- 可选. 正在处理页面请求付款.
- 商户向UMF发送支付请求.调用 下单.app_id必传
- UMF向微信发起支付请求.
- 微信向UMF返回支付信息.
- UMF返回wechat_mp对象.
- 商户向浏览器返回wechat_mp对象.
- 返回页唤醒微信支付插件(微信JS-API).
- 用户在微信浏览器输入密码完成支付.
- 微信返回正在处理页面.
- 正在处理页面ret_url(步骤11).
- WeChat向UMF返回支付结果.
- UMF向商户发送支付结果.
2.10 B2C个人网银直连
Create a payment
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM="
-d '{
"payer": {
"payment_method": "NOT_APPLICABLE",
"bank_code": "BOC",
"payer_info": {
"bank_card": {
"citizen_id_number": "EUXWrsaH49Ed4ECyyP+4xRAchotGF+cLAyMht6xU1kGfyCIbp4rDzthL+5tBvvG6GaKANhyINffbo/OHywEelesfoqg0mgSW77abXF1ZUQ4uNd2mCHnj/J47/4IPOO1pSrYtZ6OfFgovygNBAm6w9xj/IfDjhEfMvbZFoffVvMs\u003d",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "pvo7/bDw3BCqfynAv6rZcbuM9YUhgtXMLSkQPkJRZqEZdDTETJMMGc2ao6XdAxP05nODHzzugOmkYAPE0pUhexB7Luf4a6/ANBz1j6EgKiZdlaU884ms4Cs5USHOqLIpR6KbNgzYOl/N10lCQasByASlBch/3SUvsY2HtzaWrLs\u003d",
"phone": "18234048022"
}
},
"interface_type": "DIRECT_TO_BANK",
"business_type": "B2C"
},
"order": {
"mer_reference_id": "1227114104261101",
"mer_date": "20181227",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"order_summary": "CrossBorderOrderSummary",
"expire_time": "360",
"user_ip": "10.10.70.134",
"sub_orders": [{
"mer_sub_reference_id": "1227114104262102",
"trans_code": "03223010",
"amount": {
"total": "0.01",
"currency": "CNY"
},
"is_customs": "False",
"invoice_id": "123456"
},
{
"trans_code": "01122030",
"amount": {
"total": "0.01",
"currency": "CNY"
},
"is_customs": "False",
"invoice_id": "123456",
"items": [{
"mer_item_id": "1227114104262103",
"type": "FOOD",
"name": "banana",
"quantity": "2",
"description": "banana",
"amount": {
"total": "0.01",
"currency": "CNY"
}
}]
}],
"sub_mer_id": "umfsubmer001"
},
"notify_url": "http://1o8916706x.imwork.net/SCA_WEB/reciveUmfNotify/commonPost",
"ret_url": "http://10.10.38.49:2213/notify0000V4.jsp",
"risk_info": {
"trans_type": "02"
}
}'
## Response data:
{
"payment": {
"id": "PAY_GY4DCMRSG4YTCNBQGU4DKMRTGQZDAMJYGEZDEN4O",
"order": {
"amount": {
"total": "0.02",
"currency": "CNY"
},
"mer_date": "20181227",
"sub_mer_id": "umfsubmer001",
"sub_orders": [{
"amount": {
"total": "0.01",
"currency": "CNY"
},
"trans_code": "03223010",
"invoice_id": "123456",
"is_customs": "False",
"mer_sub_reference_id": "1227114104262102"
},
{
"amount": {
"total": "0.01",
"currency": "CNY"
},
"trans_code": "01122030",
"items": [{
"amount": {
"total": "0.01",
"currency": "CNY"
},
"mer_item_id": "1227114104262103",
"description": "banana",
"name": "banana",
"quantity": "2",
"type": "FOOD"
}],
"invoice_id": "123456",
"is_customs": "False",
"mer_sub_reference_id": "1227114105013001"
}],
"expire_time": "2018-12-27T17:40:24+0800",
"order_summary": "CrossBorderOrderSummary",
"mer_reference_id": "1227114104261101",
"user_ip": "10.10.70.134"
},
"payer": {
"payer_info": {
"bank_card": {
"phone": "",
"payer_name": "jECG6bH4GYb5I3B0MDkHjQWvlAYNaJ/4sehP8gnQ+Ay869ls3V/ExOw6nbiPwFsn37KeW1srYgKO6/opJjzTxXBPdUjkGty6cTPoSOpa4f1QP4MfA0P1VKH5dqc9F2wX1m0WeaTzNDMCxmhWPf31K4J/erqta7jzDYsaOP7TcC8=",
"citizen_id_type": "IDENTITY_CARD",
"valid_date": "",
"number": "",
"cvv2": "",
"citizen_id_number": "GEeS3AheAkeeTZ++jZPWLVTpUbW1jsCT4mjLLn0SC+rsKaObEp+hst3x64yrp3/V5rMwuZXX9CQuA8kOQQYQ6Tfvg4wkEvlaub3CE234ecRnuiacz1YGof3h/rwskOnd3v1gsVOPZK6kAhTMPejO01uhPkcYmeS/guqUA4NF6vk="
}
},
"interface_type": "DIRECT_TO_BANK",
"business_type": "B2C",
"bank_code": "BOC",
"payment_method": "NOT_APPLICABLE"
},
"state": "WAIT_BUYER_PAY",
"notify_url": "http://1o8916706x.imwork.net/SCA_WEB/reciveUmfNotify/commonPost",
"risk_info": {
"trans_type": "02"
},
"is_from_US": "Y",
"ret_url": "http://10.10.38.49:2213/notify0000V4.jsp"
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4DCMRSG4YTCNBQGU4DKMRTGQZDAMJYGEZDEN4O"
},
{
"ref": "refund",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4DCMRSG4YTCNBQGU4DKMRTGQZDAMJYGEZDEN4O/refund"
},
{
"ref": "asynchronous_refund",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4DCMRSG4YTCNBQGU4DKMRTGQZDAMJYGEZDEN4O/asynchronous_refund"
},
{
"ref": "self_payment_refund",
"method": "GET",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4DCMRSG4YTCNBQGU4DKMRTGQZDAMJYGEZDEN4O/self_payment_refund"
},
{
"ref": "apply_to_customs",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4DCMRSG4YTCNBQGU4DKMRTGQZDAMJYGEZDEN4O/apply_to_customs"
},
{
"ref": "apply_to_ciq",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4DCMRSG4YTCNBQGU4DKMRTGQZDAMJYGEZDEN4O/apply_to_ciq"
},
{
"ref": "upay",
"method": "GET",
"href": "http://10.10.178.36:8081/fx_upay/cbPluginPay.do?isShowFrame=Y&busiId=06&expireTime=2018-12-27+17%3A40%3A24.915&interfaceType=02&exchangeRate=1&oriAmount=2&rpid=PSP1141042d61d4b&busiPayUrl=http%3A%2F%2F10.10.178.36%3A8087%2Ffx_paybusi%2FA01002¤cy=CNY&amount=2&isShowTransUse=N&retUrl=http%3A%2F%2F10.10.178.36%3A8081%2Ffx_upay%2FcbPluginPayReturn.do&payDate=20181227¬ifyUrl=http%3A%2F%2F10.10.178.36%3A8071%2Fspay_rest%2Fpayments%2Fpayment%2Fnotify%2FY&orderId=1227114104261101&instId=20000001&orderDate=20181227&trace=6812271140746804&merId=70510000&isCollectUserInf=N&idenCheckFlag=N&goodsInf=CrossBorderOrderSummary&isShowCustomServiceInf=Y&binBankId=B001&cbAmount=0.02&merName=%E8%B7%A8%E5%A2%83%E6%94%B6%E9%93%B6%E5%8F%B0%E6%B5%8B%E8%AF%95%E5%95%86%E6%88%B700&payType=2&sign=632d35f76addc4ad2611a6f4004dd8eb3b5fdee8"
}],
"meta": {
"ret_code": "0000",
"ret_msg": "successful transaction"
}
}
网银直连时序图.
sequenceDiagram
participant 用户
participant 商户
participant UMF
participant 银行
用户-->>商户: 1. 下单.
商户-->>UMF: 2.下单.
UMF-->>商户: 3. 返回付款对象.
商户-->>银行: 4. 跳转到网银付款页面.
银行-->>用户: 5. 展示付款页面.
用户-->>银行: 6. 在线付款.
银行-->>UMF: 7. 付款结果通知.
UMF-->>商户: 8. 付款结果通知.
时序图描述：
- 用户选择商品并发起付款.
- 商户平台请求UMF下单.
- UMF返回已创建的付款对象. 付款对象包含UMF支付的地址. 商户应该打开一个新的页面展示UMF付款.
- 商户为支付地址打开一个新的页面. 最终页面属于银行.
- 银行向用户返回网银支付页面.
- 用户填写所有信息并补全. 必须使用用户银行账号付款.
- 银行向UMF发送支付结果通知.
- UMF向商户返回支付结果.
2.11 退款
UMF支持全额或部分退款.
sequenceDiagram
participant 用户
participant 商户
participant UMF
participant 银行
用户-->>商户: 1. 选择要退款商品,发起退款
商户-->>用户: 2. 生成退款单
用户-->>商户: 3. 确认退款单
Note right of 商户: 使用有效的access token发起API请求
商户-->>UMF: 4. 可选. 获取access token
UMF-->>商户: 5. 返回access_token
Note right of 商户: 使用access token调用API
商户-->>UMF: 6. 发起退款请求
UMF-->>银行: 7. 请求退款
银行-->>UMF: 8. 返回退款结果
UMF-->>商户: 9. 返回退款对象
商户-->>用户: 10. 退款结果通知
时序图描述：
- 用户在商户平台选择需要退款的商品并发起退款.
- 商户平台生成退款单.
- 用户确认退款单.
- 可选. 商户 获取 access token. 该步骤是可选的. 如果商户已经拥有可以正常调用API的access token, 请忽略步骤4和5.
- UMF返回access token.
- 商户向UMF提交退款单数据. 调用 退费/异步退费.
- UMF向银行发起退款请求.
- 银行向UMF返回退款结果.
- UMF向商户返回退款对象.
- 商户向用户返回退款结果.
2.12 网银直连
网银直连时序图.
sequenceDiagram
participant 用户
participant 商户
participant UMF
participant 银行
用户-->>商户: 1. 下单.
商户-->>UMF: 2.下单.
UMF-->>商户: 3. 返回付款对象.
商户-->>银行: 4. 跳转到网银付款页面.
银行-->>用户: 5. 展示付款页面.
用户-->>银行: 6. 在线付款.
银行-->>UMF: 7. 付款结果通知.
UMF-->>商户: 8. 付款结果通知.
时序图描述：
- 用户选择商品并发起付款.
- 商户平台请求UMF下单.
- UMF返回已创建的付款对象. 付款对象包含UMF支付的地址. 商户应该打开一个新的页面展示UMF付款.
- 商户为支付地址打开一个新的页面. 最终页面属于银行.
- 银行向用户返回网银支付页面.
- 用户填写所有信息并补全. 必须使用用户银行账号付款.
- 银行向UMF发送支付结果通知.
- UMF向商户返回支付结果.
2.13 收银台
Create a payment
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM="
-d '{
"payer": {
"payment_method": "NOT_APPLICABLE",
"bank_code": "CCB",
"payer_info": {
},
"interface_type": "SERVER_TO_WEB",
"external_customer_id": "UMP1499826888843602",
"business_type": "B2C"
},
"order": {
"mer_reference_id": "1126153144321101",
"mer_date": "20181126",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"order_summary": "CrossBorderOrderSummary",
"expire_time": "360",
"user_ip": "10.10.70.134",
"sub_orders": [{
"mer_sub_reference_id": "0318145603291164",
"trans_code": "01122030",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"is_customs": "TRUE",
"invoice_id": "123456",
"items": [{
"mer_item_id": "1126153144322102",
"type": "FOOD",
"name": "banana",
"quantity": "2",
"description": "banana",
"amount": {
"total": "0.02",
"currency": "CNY"
}
}]
}],
"sub_mer_id": "umfsubmer001"
},
"notify_url": "http://1o8916706x.imwork.net/SCA_WEB/reciveUmfNotify/commonPost",
"ret_url": "http://10.10.38.49:2213/notify0000V4.jsp",
"risk_info": {
"trans_type": "02"
}
}'
## Response data:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"risk_info": {
"trans_type": "02"
},
"id": "PAY_GY4DCMJSGYYTKMZRHE4TEMZXGEZDAMJYGEYTENV2",
"state": "WAIT_BUYER_PAY",
"notify_url": "http://1o8916706x.imwork.net/SCA_WEB/reciveUmfNotify/commonPost",
"payer": {
"bank_code": "CCB",
"external_customer_id": "UMP1499826888843602",
"business_type": "B2C",
"interface_type": "SERVER_TO_WEB",
"payment_method": "NOT_APPLICABLE",
"payer_info": {
}
},
"ret_url": "http://10.10.38.49:2213/notify0000V4.jsp",
"is_from_US": "N",
"order": {
"user_ip": "10.10.70.134",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"sub_orders": [{
"mer_sub_reference_id": "1126153137486112",
"trans_code": "01122030",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"invoice_id": "123456",
"is_customs": "TRUE",
"items": [{
"amount": {
"total": "0.02",
"currency": "CNY"
},
"quantity": "2",
"mer_item_id": "1126153144322102",
"name": "banana",
"description": "banana",
"type": "FOOD"
}]
}],
"sub_mer_id": "umfsubmer001",
"mer_date": "20181126",
"expire_time": "2018-11-26T21:31:37+0800",
"mer_reference_id": "1126153144321101",
"order_summary": "CrossBorderOrderSummary"
}
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTKMZRHE4TEMZXGEZDAMJYGEYTENV2"
},
{
"ref": "refund",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTKMZRHE4TEMZXGEZDAMJYGEYTENV2/refund"
},
{
"ref": "asynchronous_refund",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTKMZRHE4TEMZXGEZDAMJYGEYTENV2/asynchronous_refund"
},
{
"ref": "self_payment_refund",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTKMZRHE4TEMZXGEZDAMJYGEYTENV2/self_payment_refund"
},
{
"ref": "apply_to_customs",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTKMZRHE4TEMZXGEZDAMJYGEYTENV2/apply_to_customs"
},
{
"ref": "apply_to_ciq",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTKMZRHE4TEMZXGEZDAMJYGEYTENV2/apply_to_ciq"
},
{
"ref": "update_express_info",
"method": "POST",
"href": "http://10.10.81.240:8080/spay_rest/payments/payment/PAY_GYYDANZQHAYTMMRYHEZDSOJXGMZDAMRQGA3TAOGC/update_express_info"
},
{
"ref": "upay",
"method": "GET",
"href": "https://fx.soopay.net/fx_upay/cbPluginPay.do?cbAmount=0.02&retUrl=https%3A%2F%2Ffx.soopay.net%2Ffx_upay%2FcbPluginPayReturn.do&busiId=06&orderId=1126153144321101&isShowTransUse=N&merName=%E8%B7%A8%E5%A2%83%E6%94%AF%E4%BB%98&isShowFrame=Y&isCollectUserInf=Y&interfaceType=01&trace=6811261531019561&exchangeRate=1¤cy=CNY&cbOrderType=&oriAmount=2&amount=2&goodsInf=CrossBorderOrderSummary&idenCheckFlag=N&rpid=PSP1531375b04b55&instId=20000001&isShowCustomServiceInf=Y&expireTime=2018-11-26+21%3A31%3A37.613¬ifyUrl=http%3A%2F%2Ffx.soopay.net%2Fcberest%2Fv1%2Fpayments%2Fpayment%2Fnotify%2FN&merId=4907&busiPayUrl=http%3A%2F%2F172.16.31.202%3A8080%2Ffx_paybusi%2FA01002&orderDate=20181126&payDate=20181126&sign=70a6376a95e891231c645e63e1d309d3bba279a5"
}]
}
收银台时序图.
sequenceDiagram
participant 用户
participant 商户
participant UMF
participant 银行
用户-->>商户: 1. 下单.
商户-->>UMF: 2.下单.
UMF-->>商户: 3. 返回付款对象.
商户-->>UMF: 4. 跳转到UMF支付页面.
UMF-->>用户: 5. 展示UMF支付页面.
用户-->>UMF: 6.选择支付方式,确认支付.
UMF-->>银行: 7.请求扣款.
银行-->>UMF: 8. 推送结果.
UMF-->>商户: 9. 推送支付结果.
时序图描述：
- 用户选择商品并发起付款.
- 商户平台请求UMF下单.
- UMF返回已创建的付款对象. 付款对象包含UMF支付的地址. 商户应该打开一个新的页面展示UMF付款.
- 商户请求获取UMF的支付界面.
- UMF向用户返回支付页面.
- 用户选择支付方式,补全所有信息并确认支付.
- UMF向银行请求扣款.
- 银行向UMF推送支付结果通知.
- UMF向商户返回支付结果.
2.14 企业资质审查
- 录入企业为当前商户的用户.
- 使用网银支付.
企业资质审查时序图.
sequenceDiagram
participant 用户
participant 商户
participant UMF
participant 银行
用户-->>商户: 1. 提交文件.
商户-->>UMF: 2.提交文件.
UMF-->>银行: 3. 提交文件.
银行-->>UMF: 4. 返回校验结果.
UMF-->>UMF: 5. 更新企业状态.
商户-->>UMF: 6. 查询企业状态.
UMF-->>商户: 7. 返回企业状态.
时序图描述 (离线)：
- 用户向商户提交所需文件.
- 商户向UMF提交文件.
- UMF校验文件并把文件发送给银行.
- 银行校验企业资质, 向UMF发送结果.
- UMF向商户返回结果.
- 在线. 商户向UMF查询企业资质状态.
- 在线. UMF返回企业资质状态.
2.15 B2B收银台网银直连
sequenceDiagram
participant 商户
participant UMF
商户-->>UMF: 企业资质录入
商户-->>UMF: 网银直连
UMF-->>商户: 返回支付结果
商户-->>UMF: 上传明细文件
时序图描述：
- 商户向UMF录入企业资质,商户可以请求企业资质查询获取企业资质状态.
- 商户使用网银直连支付.
- UMF返回支付结果.
- 商户向UMF上传交易明细文件.
3. B2C
3.1 查询银行列表
## Request data:
curl -s -X GET https://uatfx.soopay.net/cberest/v1/bank?type=CREDIT_CARD \
-H "Content-Type:application/json" \
-H "Authorization:Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
## Response data:
{
"banks": [
{
"name_zh": "建设银行",
"types": [
"CREDIT_CARD"
],
"code": "CCB",
"logo_url": "baidu",
"name": "China Construction Bank"
},
{
"name_zh": "广发银行",
"types": [
"CREDIT_CARD"
],
"code": "GDB",
"logo_url": "baidu",
"name": "Guangdong Development Bank"
},
{
"name_zh": "上海银行",
"types": [
"CREDIT_CARD"
],
"code": "SHB",
"logo_url": "baidu",
"name": "Bank of Shanghai"
}
],
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
}
}
请求
GET: /bank?type=CREDIT_CARD
每个商户只能查看合同中包含的银行卡.
该API将返回商家可用的银行列表.
参数
| 参数 | 描述 |
|---|---|
| type | 枚举类型. 银行卡的类型. 可选值: CREDIT_CARD, DEBIT_CARD |
响应
| 参数 | 描述 |
|---|---|
| banks | 对象的列表. bank 对象列表. 请参见右边的示例. |
3.2 卡BIN查询
## Request data:
curl -s -X GET https://uatfx.soopay.net/cberest/v1/bank/cardbin?card=xU/rMnO3k01KQ5FC3mLHuVC7a0K8LbO5lEZw4EBBi247vuqMX5SkLZQabla9iLQQw0Ji+dEws07zxIrkNIiC+Ikad8Ae \+EZZ2LIQPiQdJISAgTlnvvQm38ttnMfZjZbV021KV2nUr/ISpeP+95aRN8dtirfZbBZvmRbwcai7g0w= \
-H "Content-Type:application/json" \
-H "Authorization:Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
## Response data:
{
"bank": {
"name_zh": "建设银行",
"types": ["DEBIT_CARD"],
"code": "CCB",
"logo_url": "baidu",
"is_support": "Y",
"name": "China Construction Bank"
},
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
}
}
请求
GET: bank/cardbin?card=BImaZ/etLmw5ykqFquMPWvytiHcue6HZjPxZKcmXc13h64r0zDxPo9wj5vCy09dYrxwGVIFgc73PZlpT/JoAD6/W2MvS7I5/OPxvXCIlu6xIOZz
根据卡号查询卡信息.
该API将返回卡信息.
参数
| 参数 | 描述 |
|---|---|
| card | 字符串. 卡号. 加密 |
响应
| 参数 | 描述 |
|---|---|
| bank | 银行信息. bank . 请参见右边示例. |
3.3 获取微信open_id
# Request
curl -s -X GET \
https://uatfx.soopay.net/cberest/v1/payments/wechat_openid?notify_url=https://www.baidu.com\
-H "Content-Type:application/json" \
-H "Authorization:Bearer 4a723d99be468d58695b0b9e5d2c94ae0974d983d6dd8f903df5d17006c84096"
#Response
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"links": [
{
"ref": "weChat",
"method": "GET",
"href": "https://open.weixin.qq.com/connect/oauth2/authorize?appid=wxddc9cfd7324f0fb0&redirect_uri=http%3A%2F%2Ftest3.soopay.net%2Febankpaydev%2FrecvweixinGZHCodeNew.htm%2F%3Freturn_url%3Dhttp%253A%252F%252F10.10.178.34%253A8081%252Fupay%252FcbNotifyMerOpenId.do%253FnotifyUrl%253Dhttp%253A%252F%252F10.10.178.93%253A8081%252Fspaytest%252FofficialAccount.jsp&response_type=code&scope=snsapi_base&state=c0e8d0e84e311ad46102da45009c703c6da034b5226777f771c1e6405771cb18#wechat_redirect"
}
]
}
请求
GET: /payments/wechat_openid?notify_url=https://www.baidu.com
如果payment type为WECHAT_WEB时，请求下单之前需要获取微信open_id.
参数
| 参数 | 描述 |
|---|---|
| notify_url | 异步通知地址, 交易完成后, 联动优势支付平台将通过http(s)将交易结果发送到通知地址. |
响应
响应结果为links对象列表. 请参见右边示例.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共部分. |
| links | 对象数组. 下一步操作链接. 请参见右边示例. |
3.4 汇率查询
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/exchange_rate?currency=USD \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f"
//response
{
"meta":{
"sign":"Alc9iDPd4P2z3LzeaZj73aC2fmeHZmlh59d7+MvZoDRYUsOF3lLGe92VhqWhRERvXCBBOK+SarPSI72pj1rHCqTcVd6/hagHKJa/j4k0CodwsrYXhoayLhu6Y/XG7JllyY2pa84J+xLCv/D81KvwWukOpK3MRNf5yq9zrVaVD5E=",
"ret_msg":"Success",
"ret_code":"0000"
},
"exchangeRates":[
{
"rate":"6.9023",
"currency":"USD"
}
]
}
GET: /exchange_rate?currency=USD
获取实时汇率. 返回币种相应数量的人民币.
请求
参数是currency币种代码.
| 参数 | 描述 |
|---|---|
| currency | 字符串. |
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共部分. |
| exchange_rate | 对象，汇率信息. |
3.5 下单
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM=" \
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"bank_code": "BOC",
"payer_info": {
"phone": "13552105741"
},
"interface_type": "SERVER_TO_SERVER",
"business_type": "B2C"
},
"order": {
"mer_reference_id": "1126144824929101",
"mer_date": "20181126",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"order_summary": "CrossBorderOrderSummary",
"expire_time": "360",
"user_ip": "10.10.70.134",
"sub_orders": [{
"mer_sub_reference_id": "1126144818140110",
"trans_code": "01122030",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"is_customs": "TRUE",
"invoice_id": "123456",
"items": [{
"mer_item_id": "1126144824930102",
"type": "FOOD",
"name": "banana",
"quantity": "2",
"description": "banana",
"amount": {
"total": "0.02",
"currency": "CNY"
}
}]
}],
"sub_mer_id": "umfsubmer001"
},
"notify_url": "http://10.10.38.49:2216/spay_rest/payments/test/mer",
"ret_url": "http://10.10.38.49:2213/notify0000V4.jsp",
"risk_info": {
"trans_type": "02"
}
}'
## Response data:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"risk_info": {
"trans_type": "02"
},
"id": "PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF",
"state": "WAIT_BUYER_PAY",
"notify_url": "http://10.10.38.49:2216/spay_rest/payments/test/mer",
"payer": {
"bank_code": "BOC",
"business_type": "B2C",
"interface_type": "SERVER_TO_SERVER",
"payment_method": "DEBIT_CARD",
"payer_info": {
"bank_card": {
"number": "",
"cvv2": "",
"valid_date": "",
"citizen_id_number": "",
"phone": "",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": ""
},
"payer_agreement": {
"usr_busi_agreement_id": "",
"usr_pay_agreement_id": ""
}
}
},
"ret_url": "http://10.10.38.49:2213/notify0000V4.jsp",
"is_from_US": "N",
"order": {
"user_ip": "10.10.70.134",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"sub_orders": [{
"mer_sub_reference_id": "1126144818140110",
"trans_code": "01122030",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"invoice_id": "123456",
"is_customs": "TRUE",
"items": [{
"amount": {
"total": "0.02",
"currency": "CNY"
},
"quantity": "2",
"mer_item_id": "1126144824930102",
"name": "banana",
"description": "banana",
"type": "FOOD"
}]
}],
"sub_mer_id": "umfsubmer001",
"mer_date": "20181126",
"expire_time": "2018-11-27T14:48:18+0800",
"mer_reference_id": "1126144824929101",
"order_summary": "CrossBorderOrderSummary"
}
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF"
},
{
"ref": "sms_verify",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF/verify"
},
{
"ref": "self_payment_refund",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF/self_payment_refund"
}]
}
请求
POST: /payments/payment
创建一个稍后或立即执行的支付单, 取决于付款类型.
下面的表格展示了UMF支持的支付类型, 所有的付款必须使用人民币支付:
接口类型为SERVER_TO_SERVER时，支付方式如下：
| 支付方式（payment_method） | 描述 |
|---|---|
| CREDIT_CARD | 信用卡支付 |
| DEBIT_CARD | 借记卡支付 |
| WECHAT_SCAN | 微信扫码支付.UMF返回一个二维码字符串. 用户使用他们的微信扫描二维码支付. |
| WECHAT_WEB | 微信公众号支付.用户在微信浏览器里支付订单. |
| WECHAT_IN_APP | 微信APP支付.用户在App应用里支付订单. |
| ALIPAY_SCAN | 支付宝扫码支付.UMF返回一个二维码字符串. 用户使用他们的支付宝扫描二维码支付. |
| WECHAT_H5 | 微信H5支付.UMF返回支付链接.用户使用浏览器打开此链接完成支付. |
| WECHAT_MP | 微信小程序支付.UMF返回支付链接.用户使用浏览器打开此链接完成支付. |
| B2C_BANK | 个人网银支付 |
| B2B_BANK | 企业网银支付 |
| 接口类型(interface_type) | 描述 |
|---|---|
| SERVER_TO_SERVER | API模式 |
| SERVER_TO_WEB | 收银台模式，接口类型为该值时，支付方式为：NOT_APPLICABLE |
| SERVER_TO_H5WEB | 快捷H5收银台模式,接口类型为该值时，支付方式为：NOT_APPLICABLE |
| DIRECT_TO_BANK | 银行直连 |
| 模式(business_type) | 描述 |
|---|---|
| B2B | B2B |
| B2C | B2C |
| 参数 | 描述 |
|---|---|
| payer | 对象. 支付信息. |
| order | 对象. 订单信息. 包含子订单. |
| notify_url | String. 商户服务器的url 接收支付结果. |
| risk_info | Object. The information of transaction. |
| subMchId_flag | String. 是否获取子商户 非必填. 有效值：Y（是）; N（否） |
响应:
响应结果包含meta信息和一个支付对象. 请参见右边的示例. 已创建的支付对象包含如下信息：
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| payment | 对象. 支付对象. |
| links | 对象数组. 下一步操作的链接. 取决于支付类型的状态. 链接是HATEOAS链接. |
3.6 短信验证码
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/PAY_GI3TAOBQGIYTMMJTGA2DENZXGMZDAMJXGA4DAMWF/verify \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"payer_info": {
"bank_card": {
"number": "AFz5NlZFjnYVPWHMi86Q84ULua8+HvRhyfAxYGWJQkg2tqwo571aPZQca8dBo+3/QO3yTFAURAjTZaYr77GunXlB8Nuow2wvyxX6QOa+Po8HXk1wzVvCxiHVUulbqGj4O4bZmTVawToMWphtksz4wuwAAWgxvjFqrWXQVEtAcE0\u003d",
"citizen_id_number": "OJEXNDY7yGyRASMItXir9td8taEoQnXlkVxkCvW72i5+L2lBzouQaXU4nGfsvLFbNa5Z5yMwscZnuUf6i+Hpu6LSTTzoYglIl26fbilVU4MEhDuCDbRuec6+FxHjIjSZkaxL8ctTJHgUtS/O+HE++QmNYWuVnfHK0+Yk83RpmuQ\u003d",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "RikJyJRehnpjlzpLcop14umK/FoE7h1FtpT9HXOfq2zDKd+eVa97pli/uWHYeQqVdTKuWY8YGlIYQCoImawbc19hbN4otEK5xtQmtB3wAVSsTFLzkoZWHebd+Y+2rRH+bnCc93ttlWWRYHqJca2z9SazCLvZn16C25tEsmRtnaI\u003d",
"valid_date": "",
"cvv2": "",
"phone": "15754314122"
}
},
"external_customer_id": "911886886911"
}
}'
//Response:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"id": "PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF",
"payer": {
"external_customer_id": "911886886911",
"payment_method": "DEBIT_CARD",
"payer_info": {
"bank_card": {
"number": "oPo8OMwavJJdjEHxtoHIMlS8bZcg4iImwiRNOe6P1Mhx40hKzMj5IzxF0a8VXIJWvkA2Xt2eaw+0hR2be1plRWQSE/f8kc4/sZed1+VNI+vpN2shdqXWdt4GMn3VZx68Be6AnbE/wl8DhfvGjxgKHY9tHMXNoM64oEof2uvH9ag=",
"cvv2": "",
"valid_date": "",
"citizen_id_number": "CT/3BoExrW2m6lHCGvdCCP2MU1DKbGTlg5+hSSXLv2YpXeA2Yt6zCQdbteJ4htcf+6Bda3n8yuXvNPWcohSVRMIT5L0KXf63GDJOtlB8tJFXXKLODGfLRdOOuOKLfN752u3/lrusKDFwN7fuKA5WFJgcn4tG7lKnyXwznuND3XA=",
"phone": "15754314122",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "kT5a+zj+FTwLBTMXdF5m6va0IoNDFnvChA/AkfxPcPTWAwffjuEfKOikkOJ4cmSlERAhnnA8YYFqaqWQ8404Wh2Rv/+uhXjFPIfkosf288ksPWv7M3Nno8z1dxgBjWHJUtSNxbWptj5r6lntT4y325F1Qd3SlV0Wo1TNYnNUTNs="
}
}
}
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF"
},
{
"ref": "confirm",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF/execute"
}]
}
只有银行卡支付才会下发短信验证码.
在这个过程中, 商户发送银行卡信息, UMF(或者银行) 将向用户手机发送短信验证码. 短信验证码是完成支付过程参数的一部分.
请求
POST:/payments/payment/{payment_id}/verify
请求url中的payment_id是在上一步创建的真实payment_id(下单).
可用的支付对象
| 参数 | 描述 |
|---|---|
| payer | 对象. 支付信息.某些参数应该使用 UMF公钥加密. 看支付对象的描述信息. |
响应
响应结果仅仅包含下一步操作的链接. 看右边的示例. 如果请求合法, 短信将发送到用户手机.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| links | 对象数组. 下一步操作的链接. |
错误码:
| 返回码 | 返回码描述 |
|---|---|
| 00060700 | 参数错误 |
| 00200025 | 银行卡信息不正确. |
| 00200026 | 银行卡过期. |
| 00060999 | 系统忙. |
| 00080706 | 请求获取验证码频繁. |
| 00060875 | 验证卡bin失败 (卡号不正确). |
| 00080707 | 订单的验证码请求数量超过最大值. |
| 00200027 | 商户没有配置通道. |
| 00060869 | 在UMF平台上没有注册商品. |
3.7 确认支付
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/PAY_GI3TAOBQGEYDQMRQHAYTMMJRGEZDAMJXGA3TGMKN/execute \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:a/1A+rSDh2EBPGgiqRcET1hNcUtPBjSjQOYZmkqLx1n+IPAeM2p5c29XkB64jMy0fHfzFaK/cCj3vvq/f+o2fqC+WsLWnby34ByxdH+sgTK+I+bkzEdvwD7S9NCWwdMxejwuhBu+HcUn7uLhYgeRdOXfLIH/aThssRoBMTcmeZc="
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"bank_code": "BOC",
"payer_info": {
"bank_card": {
"number": "lFBjnhkXxUXveXJWC92aOnQkKf9aBIbt2fkbk2EJGvzBoF/ddCe/haw9Lb7vT8A9GnVPcrVC+mcwW4Xiu9B4Us7JaQk91Zr6cTCySCIY9CT9t2rb3+dmOwgnJdJsDpc4rk8WdEVxeV36JfFxEGGbarJR9WeVOg90k5a3V6VZWrY\u003d",
"citizen_id_number": "okJyL92gqUjRoU7UCcVnlqEeF+t3pmGbgR/BqGALLIpPXcq3CnPHKI4qSRFArQ2S1/Xw2y4rxUNIZaBAVQUE30mifmYZcJNQo2txCp70RREKo7hRbKH9YVqvCFfMpp40pkJgRnmMKGzSoLlsCPUCbv05Hyq88dbNRAaCdW9i6A8\u003d",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "i4boOVtg1xPuALmKqH9fJG7Jz+zqmqnsPAsjDTYQZgN+nl6paR20hTjDonCP9OSEgvK/DzDHarMKBoP3YWRSvIowrhg0JH6XkOc8LZvXeemuIp4UEAFmT4s7medJEBp7FVlWJ70oCLVBspjbapsJbJEHwND2m7eprGJNvooPa6E\u003d",
"valid_date": "",
"cvv2": "",
"phone": "15754314122",
"verify_code": "409387"
}
},
"external_customer_id": "911886886911"
}
}'
## Response data:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"settle_date": "20181126",
"id": "PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF",
"state": "TRADE_SUCCESS",
"execute_success_time": "2018-11-26T14:50:56+0800",
"payer": {
"bank_code": "BOC",
"external_customer_id": "911886886911",
"payment_method": "DEBIT_CARD",
"payer_info": {
"bank_card": {
"number": "lBHNHslsTZrwpaSpYw/YecKc7W9zPtivVzw6nwnD4JwY63m9vw6oG4q965B6jsr+SEw3/0e9c6uBIf5qCdl7zBp+Odq9z85ZPG33qB3QSlpn900oP6GawHWMx8y+M8Ev/l2lSXEiwo4jukSNCVKtWkdW6A+X7WxHhErAAdEgb0s=",
"cvv2": "",
"valid_date": "",
"citizen_id_number": "xNeK9I9fZ+pOOCKMYBGda0QkYr742DPvX/w7NwQRLfHaas/xBi/nD7RwbmIXTzBhwq9jASLkgOot4mE9Ozu2B5jq73Vu45IO1bU/VplyM6v3d5uEISJIyKfmuPHSv71MSGbijyzkTbPlxeJVzBVRZWRMoe9vpgc6ro9X78opiwg=",
"phone": "15754314122",
"citizen_id_type": "IDENTITY_CARD",
"verify_code": "409387",
"payer_name": "TRqx2/7sTWernXUV5qRWxEmQ0s+UweQV6OaX5rqLIVazrXMvrGGic3W4jiQDdd5g0hzgwfMxJ+G9kA8bVmoKvihtXO8ldcFLi5u/8eVg9/KsNvs9FlEN1GbPpNM58OTQScvf1wbtZPB8TNh7RNioL9rYywowFsjWcWi3g16oDlI="
},
"payer_agreement": {
"usr_busi_agreement_id": "UB201811261450560000000033862892",
"usr_pay_agreement_id": "P2018080109324500000000041329281"
}
}
}
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF"
},
{
"ref": "apply_to_customs",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF/apply_to_customs"
},
{
"ref": "refund",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF/refund"
},
{
"ref": "asynchronous_refund",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF/asynchronous_refund"
},
{
"ref": "apply_to_ciq",
"method": "POST",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF/apply_to_ciq"
}]
}
处理完支付单,并且交易完成后. 资金从用户账户转移到UMF商户账户.
要执行支付单, 请在请求url中添加payment ID参数, 在请求的JSON body中包含一个payer对象.
处理结果不会立即返回. 商户想要获取结果有两种方式，方式如下:
– 查询付款结果. 支付成功的状态为"TRADE_SUCCESS". – 等待UMF通知. 商户需要开发http(s)服务. 支付产生结果时,UMF请求到这个服务.
请求
POST:/payments/payment/{payment_id}/execute
请求url中的payment_id是在上一步创建的真实payment_id(下单).
参数
| 参数 | 描述 |
|---|---|
| payer | 对象. 支付信息. 一些参数应该用UMF公钥加密. 参见payer对象的描述. 若支付类型是银行卡或者信用卡, payer对象应该包含手机验证码. |
响应
响应结果包含payment对象. 银行卡信息不将返回, 例如card number, cvv2, citizen_id, 等等.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| payment | 对象. 支付对象. |
| links | 对象数组. 下一步操作的链接. 链接是HATEOAS链接. |
3.8 支付结果通知
## Notification request(modify the follow url address to get demo notification):
curl -s -X POST https://dev.restdemo.umftech.com/restdemo/demo/notifyResultRest \
-H "Content-Type:application/json" \
-H "Signature:U1TE7d24ZeWbzbsNl63/140jzq83BplOQ5JZxQw/elEjO/fNp7L0dpeCiHdgGsLFou/O6Eh8VtH+/fxwmpejmpQa1rpjR2XaI82SGNwEPGvATYquS5UI6rFyiG8BdiRjBxLWcH+yOa6Kw6MsCSsJKmq+kJrRf2Iiu/jYLxJAvh8=" \
-d '{"meta":{"ret_code":"0000","ret_msg":["SUCCESS"]},"payment":{"payer":{"bank_code":"","payer_info":{"payer_agreement":{"gate_id":"","last_four_cardid":"","usr_pay_agreement_id":"","usr_busi_agreement_id":""}}},"order":{"mer_reference_id":"4b37lysdimy","mer_date":"20170912","amount":{"total":"0.01","currency":"CNY","total_cny":"0.01"},"mer_priv":""},"state":"TRADE_SUCCESS","settle_date":"20170913","execute_success_time":"20170913"},"links":[{"href":"https://fx.soopay.net/cberest/v1/payments/payment/PAY_GM3TAOJRGMYDOMJWG42DEMZXGIZDAMJXGA4TCMXX","ref":"self","method":"GET"},{"href":"https://fx.soopay.net/cberest/v1/payments/payment/PAY_GM3TAOJRGMYDOMJWG42DEMZXGIZDAMJXGA4TCMXX/refund","ref":"refund","method":"POST"},{"href":"https://fx.soopay.net/cberest/v1/payments/PAY_GM3TAOJRGMYDOMJWG42DEMZXGIZDAMJXGA4TCMXX/apply_to_customs","ref":"apply_to_customs","method":"POST"}]}'
## Notification data:
{
"meta": {
"ret_code": "0000",
"ret_msg": ["SUCCESS"]
},
"payment": {
"id": "PAY_GY4TASDFASDYTGNJQGE2DMOBQGEZDAMJZGA3DAM5X",
"payer": {
"payment_method": "WECHAT_MP",
"bank_code": "",
"payer_info": {
"payer_agreement": {
"gate_id": "",
"last_four_cardid": "",
"usr_pay_agreement_id": "",
"usr_busi_agreement_id": ""
}
}
},
"order": {
"mer_reference_id": "1654SADF13A4SDASDF",
"mer_date": "20190603",
"amount": {
"total": "0.04",
"currency": "CNY",
"total_cny": "0.04",
"exchange_rate": {
"currency": "CNY",
"rate": "1.0"
}
},
"mer_priv": "",
"verify_department_pay_trace": "102019060355554000043808000000",
"verify_department": "UnionPay"
},
"state": "TRADE_SUCCESS",
"settle_date": "20190603",
"execute_success_time": "20190603"
},
"links": [{
"href": "https://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4TASDFASDYTGNJQGE2DMOBQGEZDAMJZGA3DAM5X",
"ref": "self",
"method": "GET"
},
{
"href": "https://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4TASDFASDYTGNJQGE2DMOBQGEZDAMJZGA3DAM5X/refund",
"ref": "refund",
"method": "POST"
},
{
"href": "https://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4TASDFASDYTGNJQGE2DMOBQGEZDAMJZGA3DAM5X/asynchronous_refund",
"ref": "asynchronous_refund",
"method": "POST"
},
{
"href": "https://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4TASDFASDYTGNJQGE2DMOBQGEZDAMJZGA3DAM5X/apply_to_customs",
"ref": "apply_to_customs",
"method": "POST"
},
{
"href": "https://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4TASDFASDYTGNJQGE2DMOBQGEZDAMJZGA3DAM5X/apply_to_ciq",
"ref": "apply_to_ciq",
"method": "POST"
},
{
"href": "https://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4TASDFASDYTGNJQGE2DMOBQGEZDAMJZGA3DAM5X/self_payment_refund",
"ref": "self_payment_refund",
"method": "GET"
}]
}
}
处理完商户的付款请求数据后, UMF将支付结果回调商户服务.
接收回调后商户将作出响应.
请求
UMF调用商户提供的服务. 服务的url即为商户配置的服务url.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共信息. |
| payment | 对象. 付款对象. |
响应
商户发送到UMF的响应结果.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应信息. |
3.9 订单查询
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/payments/payment/PAY_GI3TAOBQGIYTMMJTGA2DENZXGMZDAMJXGA4DAMWF \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-d '{
"meta":{
"error_code":"",
"ret_msg":"successful transaction",
"ret_code":"0000"
},
"payment":{
"id":"PAY_GI3TANZSHAYTQMBZGAYTMNJTGUZDAMJXGA3TEOGI",
"settle_date":"20170424",
"state":"TRADE_SUCCESS",
"execute_success_time":"20170424",
"payer":{
"payment_method":"CREDIT_CARD"
},
"order":{
"user_ip":"",
"amount":{
"total":"100.02",
"exchange_rate":{
"rate":"6.9023",
"currency":"USD"
},
"currency":"USD",
"total_cny":"690.37"
},
"mer_date":"20170424",
"expire_time":"",
"mer_reference_id":"201704245435022"
}
}
}'
请求
GET: payments/payment/{payment_id}
请求url中的payment_id是在上一步创建的真实payment_id(下单).
你可以随时请求该url. UMF将返回一个支付对象.
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| payment | 对象. 支付对象. |
3.10 退费
## 退费请求数据:
$ curl -s -X POST https://fxus.soopay.net/cberest/v1/payments/payment/PAY_GI3TAOBQGIYTMMJTGA2DENZXGMZDAMJXGA4DAMWF/refund \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"refund_info":{
"mer_reference_id":"1753176072",
"amount":{
"total":"0.01",
"currency":"CNY"
},
"sub_orders":[
{
"mer_sub_reference_id": "b59nrj39k",
"trans_code": "03223010",
"amount":{
"total": "0.01",
"currency":"CNY"
}
}
]
},
"notify_url": "https://dev.restdemo.umftech.com/restdemo/demo/notifyResultRest"
}'
## 响应:
{
"meta":{
"ret_msg":"financial management",
"ret_code":"0000"
},
"refund":{
"id":"REFUND_AAAAAAQZBJGT2AJTY24KS",
"refund_info":{
"mer_reference_id":"1753176072",
"amount":{
"total":"0.01",
"currency":"CNY"
},
"sub_orders":[
{
"mer_sub_reference_id":"0615543100011",
"amount":{
"total":"0.01",
"currency":"CNY"
}
}
]
},
"state":"REFUND_PROCESS"
},
"links":[
{
"ref":"self",
"method":"GET",
"href":"https://uatfx.soopay.net/cberest/v1/payments/refund/REFUND_AAAAAAQZBJGT2AJTY24KS"
}
]
}
请求
退费：POST:/payments/payment/{payment_id}/refund
请求url中的payment_id是在上一步创建的真实payment_id(下单).
该请求创建并发送一个退款对象. 响应结果是UMF创建的退款对象.
UMF支持全额或部分退款. 部分退款可以多次执行.
退款和付款的货币必须一致, 退款金额一定不能大于付款总金额.
| 参数 | 描述 |
|---|---|
| refund | 对象. 退款对象. 应该输入订单、金额和nofify_url. |
响应
响应结果包含支付对象. 退款对象包含refund_id和state.
若state是"REFUND_SUCCESS", 表示交易完成，退款成功. 若state是"REFUND_PROCESS", 表示交易正在处理, 交易完成后, UMF 将通知商户. 商户也可以查询退款状态 查询退款
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| refund | 对象. 退款对象. |
| links | 对象数组. 下一步操作的链接. 链接是HATEOAS链接. |
3.11 异步退费
## 异步退费请求数据:
$ curl -s -X POST https://fxus.soopay.net/cberest/v1/payments/payment/PAY_GI3TAOBQGIYTMMJTGA2DENZXGMZDAMJXGA4DAMWF/asynchronous_refund \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"refund_info": {
"mer_reference_id": "1721523878",
"amount": {
"total": "0.01",
"currency": "CNY"
},
"sub_orders": [{
"mer_sub_reference_id": "0310171153877102",
"trans_code": "03223010",
"amount": {
"total": "0.01",
"currency": "CNY"
}
}]
},
"notify_url": "baidu"
}'
## 响应:
{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"links": [{
"ref": "parent_payment",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GYYDAMZRGAYTOMJRGY2DGMBRGIZDAMRQGAZTCMDR"
},
{
"ref": "self",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/refund/REFUND_GE3TEMJVGIZTQNZYGIYDEMBQGMYTAOI"
}],
"refund": {
"refund_info": {
"amount": {
"total": "0.01",
"currency": "CNY"
},
"sub_orders": [{
"mer_sub_reference_id": "0310171153877102",
"trans_code": "03223010",
"amount": {
"total": "0.01",
"currency": "CNY"
}
}],
"mer_reference_id": "1721523878"
},
"id": "REFUND_GE3TEMJVGIZTQNZYGIYDEMBQGMYTAOI"
}
}
请求
异步退费：POST:/payments/payment/{payment_id}/asynchronous_refund
请求url中的payment_id是在上一步创建的真实payment_id(下单).
该请求创建并发送一个退款对象. 响应结果是UMF创建的退款对象.
UMF支持全额或部分退款. 部分退款可以多次执行.
退款和付款的货币必须一致, 退款金额一定不能大于付款总金额.
一旦发起异步退费，会每个整点去查商户账户的余额，余额充足就会进行退款； 余额不足就下个整点再去查询（这之中的状态为REFUND_RETRY），这样去执行10次，另外23:00-10:00之间是不处理退费的。
| 参数 | 描述 |
|---|---|
| refund | 对象. 退款对象. 应该输入订单、金额和nofify_url. |
响应
响应结果包含支付对象. 退款对象包含refund_id和state.
若ret_code是"0000", 表示退款受理成功. 退款交易完成后, UMF 将通知商户. 商户也可以查询退款状态 查询退款
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| refund | 对象. 退款对象. |
| links | 对象数组. 下一步操作的链接. 链接是HATEOAS链接. |
3.12 退费查询
## Request data:
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/payments/refund/REFUND_AAAAAAQZBJGT2AJTY24KS \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f"
## Response data:
{
{
"meta":{
"ret_msg":"successful transaction",
"ret_code":"0000"
},
"refund":{
"id":"REFUND_AAAAAAQZBJGT2AJTY24KS",
"state":"REFUND_SUCCESS"
}
}
}
GET: /payments/refund/refund_id
请求url中的refund_id是在上一步创建的真实payment_id(退款).
商户随时可以请求该url. UMF将返回退款对象. 若state是"REFUND_SUCCESS", 则退款成功.
3.13 订单及退费查询
## Request data:
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/payments/payment/PAY_GM4DAOJSHEYDSNBQHE3DCMZQGYZDAMJYGA4TEOOB/self_payment_refund \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f"
## Response data:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"settle_date": "20180928",
"id": "PAY_GM4DAOJSHAYTMMZSGAYDCNBUGUZDAMJYGA4TEOCF",
"state": "TRADE_SUCCESS",
"execute_success_time": "20180928",
"payer": {
"payment_method": "DEBIT_CARD"
},
"order": {
"user_ip": "",
"amount": {
"total": "5.00",
"exchange_rate": {
"rate": "1.0000",
"currency": "CNY"
},
"currency": "CNY",
"total_cny": "5.00"
},
"sub_orders": [{
"mer_sub_reference_id": "0928163208620107",
"trans_code": "01122030",
"amount": {
"total": "5.00",
"currency": "CNY"
},
"is_customs": "TRUE",
"items": [{
"amount": {
"total": "5.00",
"currency": "CNY"
},
"quantity": "2",
"mer_item_id": "0928163207949102",
"type": "FOOD"
}]
}],
"mer_date": "20180928",
"expire_time": "",
"mer_reference_id": "0928163207948101"
}
},
"refund": {
"refund_infos": [{
"amount": {
"total": "0.02",
"currency": "CNY"
},
"refund_time": "2019-07-19T11:08:38+0800",
"refund_state": "REFUND_PROCESS",
"mer_reference_id": "1635451329"
},
{
"amount": {
"total": "0.02",
"currency": "CNY"
},
"refund_time": "2019-07-19T11:08:38+0800",
"refund_state": "REFUND_PROCESS",
"mer_reference_id": "0938408263"
}]
}
}
GET: /payments/payment/payment_id/self_payment_refund
请求url中的payment_id是在上一步创建的真实payment_id(下单).
商户随时可以请求该url. UMF将返回支付对象及退款对象.
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| payment | 对象. |
3.14 协议查询
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/agreement?external_customer_id=911886886911 \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM=" \
## Response data:
{
"agreement_info": {
"payer_agreements": [{
"usr_busi_agreement_id": "UB201811261450560000000033862892",
"last_four_cardid": "6365",
"phone": "15754314122",
"gate_id": "BOC",
"usr_pay_agreement_id": "P2018080109324500000000041329281"
}]
},
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
}
}
请求
get: /agreement?external_customer_id=911886886911
或者 /agreement?usr_busi_agreement_id=UB201811261450560000000033862892
或者 /agreement?usr_busi_agreement_id=UB201708311351430000000000144944&external_customer_id=911886886911
或者 /agreement?usr_busi_agreement_id=UB201811261450560000000033862892&bank_type=DEBIT_CARD
或者 /agreement?external_customer_id=911886886911&bank_type=DEBIT_CARD
或者 /agreement?usr_busi_agreement_id=UB201811261450560000000033862892&external_customer_id=911886886911&bank_type=DEBIT_CARD
响应
| 参数 | 描述 |
|---|---|
| payer_agreements | 对象. 响应公共信息. |
| meta | 对象. 响应公共信息. |
3.15 协议解绑
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/agreement/unbundling \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM=" \
{
"external_customer_id": "911886886911",
"payer_agreements": [{
"usr_pay_agreement_id": "P2018080109324500000000041329281",
"usr_busi_agreement_id": "UB201811261450560000000033862892"
}]
}
## Response data:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
}
}
请求
POST: /agreement/unbundling
| 参数 | 描述 |
|---|---|
| payer_agreements | 对象. 响应公共信息. |
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共信息. |
3.16 报关
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/PAY_GI3TAOBQGIYTMMJTGA2DENZXGMZDAMJXGA4DAMWF/apply_to_customs \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"customs_id": "NB",
"mer_customs_code": "2342362435435",
"freight_amount": {
"total": 344.91,
"total_cny": 344.91,
"currency": "CNY"
},
"tax_amount": {
"total": 0,
"total_cny": 0,
"currency": "CNY"
},
"sub_order_amount": {
"total": 344.91,
"total_cny": 344.91,
"currency": "CNY"
},
"ec_plat_id": "2342362435435",
"notify_url": "https://www.abcd.com/api/ump-notify",
"sub_order": {
"mer_sub_reference_id": "04185439116",
"items": [
{
"mer_item_id": "041854391161"
},
{
"mer_item_id": "041854391162"
}
]
}
}'
//Response
{
"meta":{
"sign":"mIOSW4BHECZvK+d77VdmuutVMcbIpcN0fwZ4nAIItW8Y6tcqeampky5f+rdO+/NSYco+HnPM+XEwQYuHLisZiitps9FhOxNlmQdrKL/POR8PEZbnHN9jUbUE+7J4yXPlLTI89WJdCbuByVs1WxK7msGLBhWYmdfd54DUl6FMtCc=",
"ret_msg":"Success",
"ret_code":"0000"
},
"links":[
{
"ref":"parent_payment",
"method":"GET",
"href":"http://10.10.179.74:8071/cberest/v1/payments/payment/PAY_AAEZW4UOJZ6GKAJTY2Z2I"
},
{
"ref":"self",
"method":"GET",
"href":"http://10.10.179.74:8071/cberest/v1/payments/customs_ declarations/CUST_AAAAAAHZPC5YYAJTY2ZXC"
}
],
"customs_declarations": [{
"id": "CUST_GEYTEMJVGU2DSMBTGIZDAMJYGEYTEMP6",
"verify_department": "UnionPay",
"verify_department_pay_trace": "",
"ec_plat_id": "123456",
"mer_customs_code": "123456",
"customs_clearance_date": "",
"tax_amount": {
"total": "0.00",
"total_cny": "0.00",
"currency": "CNY"
},
"notify_url": "https://www.abcd.com/api/ump-notify",
"sub_order": {
"items": [{
"mer_item_id": "112155490322"
}],
"mer_sub_reference_id": "11215549032",
"sub_customs_trace": "6811211619424184"
},
"freight_amount": {
"total": "0.00",
"total_cny": "0.00",
"currency": "CNY"
},
"sub_order_amount": {
"total": "1.00",
"total_cny": "6.81",
"currency": "USD"
},
"customs_id": "HZHG"
}]
}
请求
POST: /payments/payment/{payment_id}/apply_to_customs
该接口是可选的. 当商户需要UMF将支付信息提交到海关时, 该接口被调用. 一旦商户请求该url, 支付信息将发送给海关.
在订购后一个月内,商户向UMF提供子订单数据,在收到订单后,UMF将子订单数据更新到海关系统.
在订购后一个月内,商户向UMF提供子订单数据,在收到订单后,UMF将子订单数据更新到海关系统.
| 参数 | 描述 |
|---|---|
| customs_declarations | 对象，报关信息。 |
响应
响应结果包含一个报关对象和meta信息.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共部分. |
| customs_declarations | 对象. 海关信息. |
| links | 对象数组. 下一步操作链接. |
3.17 报关状态查询
## Request data:
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/payments/customs_declarations/CUST_GA2TAOBRGYZTAMJTHE2TSMBUGQZDAMJZGA2TAOB4 \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f"
## Response data:
{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"customs_declarations": [{
"customs_clearance_date": "20190508",
"id": "CUST_GA2TAOBRGYZTAMJTHE2TSMBUGQZDAMJZGA2TAOB4",
"state": "SUCCESS"
}]
}
请求
GET: payments/customs_declarations/{customs_declaration_id}
url中的customs_ declaration_id是在上一步(报关)中创建的报关对象的id.
响应
| Parameter | Description |
|---|---|
| meta | 对象. 响应公共部分. |
| customs_declarations | 对象. 海关信息. |
返回码描述
| 编号 | 错误码 | 描述 |
|---|---|---|
| 1 | 0000 | 报送成功(SUCCESS). |
| 2 | 00280045 | 未报送(The order has not been sent). |
| 3 | 00280046 | 已报送待处理(The order has been sent to be treated). |
| 4 | 00280047 | 报送失败(The order failed to declaration custom). |
3.18 报国检
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/PAY_GI3TAOBQGIYTMMJTGA2DENZXGMZDAMJXGA4DAMWF/apply_to_ciq \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"sub_order": {
"mer_sub_reference_id": "05073219521"
},
"ciq_code": "GJHP",
"plat_supplier_no": "56546546"
}'
//Response
{
"meta":{
"sign":"mIOSW4BHECZvK+d77VdmuutVMcbIpcN0fwZ4nAIItW8Y6tcqeampky5f+rdO+/NSYco+HnPM+XEwQYuHLisZiitps9FhOxNlmQdrKL/POR8PEZbnHN9jUbUE+7J4yXPlLTI89WJdCbuByVs1WxK7msGLBhWYmdfd54DUl6FMtCc=",
"ret_msg":"Success",
"ret_code":"0000"
},
"links":[
{
"ref":"parent_payment",
"method":"GET",
"href":"https://uatfx.soopay.net/cberest/v1/payments/payment/PAY_AAEZW4UOJZ6GKAJTY2Z2I"
},
{
"ref":"self",
"method":"GET",
"href":"https://uatfx.soopay.net/cberest/v1/payments/ciq_declarations/
CIQ_GA2TANZTGIYTSNJSGEZDAMJYGA2TANYO"
}
],
"ciq_declarations": {
"id": "CIQ_GA2TANZTGIYTSNJSGEZDAMJYGA2TANYO",
"ciq_clearance_date": "20180523",
"plat_supplier_no": "56546546",
"sub_order": {
"mer_sub_reference_id": "05073219521",
"sub_ciq_trace": "3805071023254174"
},
"ciq_code": "GJHP"
},
}
请求
POST: /payments/payment/{payment_id}/apply_to_ciq
该接口是可选的. 当商户需要UMF将支付信息提交到国检时, 该接口被调用. 一旦商户请求该url, 支付信息将发送给国检.
在订购后一个月内,商户向UMF提供子订单数据,在收到订单后,UMF将子订单数据更新到国检系统.
| 参数 | 描述 |
|---|---|
| national_inspection | 对象，报关信息。 |
响应
响应结果包含一个报关对象和meta信息.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共部分. |
| national_inspection | 对象. 国检信息. |
| links | 对象数组. 下一步操作链接. |
3.19 报国检状态查询
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/ciq_declarations/
CIQ_GA2TANZTGIYTSNJSGEZDAMJYGA2TANYO \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
## Response data:
{
"ciq_declarations": {
"id": "CIQ_GA2TANZTGIYTSNJSGEZDAMJYGA2TANYO",
"ciq_clearance_date": "20180507",
"state": "SUCCESS"
},
"meta": {
"ret_code": "0000",
"ret_msg": "successful transaction"
}
}
请求
GET: payments/ciq_declarations/{ciq_declarations_id}
url中的ciq_declarations_id是在上一步(报国检)中创建的报国检对象的id.
响应
| Parameter | Description |
|---|---|
| meta | 对象. 响应公共部分. |
| national_inspection | 对象. 海关信息. |
3.20 结算信息下载（JSON）
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/payments/reconciliation_statement?settle_date=20180103 \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f"
//response
[
{
"pagination": {
"page_number": "1",
"total_count": "6",
"page_size": "500"
},
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"reconciliations": {
"refund_summaries": [
{
"amount": {
"total": "200.00",
"exchange_rate": {
"rate": "6.8088"
},
"currency": "USD",
"total_cny": "68.08"
},
"mer_sub_reference_id": "20180129355757",
"settle_date": "20180130",
"product_id": "PaymentGateway-Debitcard",
"payment_id ": "PAY_GI4DAMJSHEYTMMZRHA3DQOJYGEZDAMJYGAYTEOM2",
"state": "REFUND_SUCCESS",
"execute_success_time": "2018-01-29T17:38:52+08:00",
"refund_id": "REFUND_HEYDCMBRGI4TAMRSGAYTQMBRGI4XE"
},
{
"amount": {
"total": "200.00",
"exchange_rate": {
"rate": "6.8088"
},
"currency": "USD",
"total_cny": "68.08"
},
"mer_sub_reference_id": "20180129513666",
"settle_date": "20180130",
"product_id": "PaymentGateway-Debitcard",
"payment_id ": "PAY_GI4DAMJSHEYTMNJQHA3DSMRRGEZDAMJYGAYTEOJZ",
"state": "REFUND_SUCCESS",
"execute_success_time": "2018-01-29T17:47:29+08:00",
"refund_id": "REFUND_HEYDCMBRGI4TANJSGAYTQMBRGI4XK"
},
{
"amount": {
"total": "200.00",
"exchange_rate": {
"rate": "6.8088"
},
"currency": "USD",
"total_cny": "68.08"
},
"mer_sub_reference_id": "20180129199929",
"settle_date": "20180130",
"product_id": "PaymentGateway-Debitcard",
"payment_id ": "PAY_GI4DAMJSHEYTMNBSHA3DSMJSGEZDAMJYGAYTEOJX",
"state": "REFUND_SUCCESS",
"execute_success_time": "2018-01-29T17:43:11+08:00",
"refund_id": "REFUND_HEYDCMBRGI4TAMZSGAYTQMBRGI4XG"
}
],
"amount": {
"total": "602.79",
"exchange_rate": {
"rate": "6.8087"
},
"currency": "USD",
"total_cny": "4104.24"
},
"payment_summaries": [
{
"order_date": "20180129",
"amount": {
"total": "200.00",
"exchange_rate": {
"rate": "6.8088"
},
"currency": "USD",
"total_cny": "1361.76"
},
"payment_id": "PAY_GI4DAMJSHEYTMMZRHA3DQOJYGEZDAMJYGAYTEOM2",
"settle_date": "20180130",
"product_id": "PaymentGateway-Debitcard",
"service_fee": "61.76",
"exchange_date": "20180130",
"exchange_amount": {
"total": "190.93",
"exchange_rate": "6.8088",
"currency": "USD",
"total_cny": "1300.0"
},
"state": "TRADE_SUCCESS",
"execute_success_time": "2018-01-29T16:31:31+08:00",
"mer_reference_id": "20180129355757"
},
{
"order_date": "20180129",
"amount": {
"total": "200.00",
"exchange_rate": {
"rate": "6.8088"
},
"currency": "USD",
"total_cny": "1361.76"
},
"payment_id": "PAY_GI4DAMJSHEYTMNJQHA3DSMRRGEZDAMJYGAYTEOJZ",
"settle_date": "20180130",
"product_id": "PaymentGateway-Debitcard",
"service_fee": "61.76",
"exchange_date": "20180130",
"exchange_amount": {
"total": "190.93",
"exchange_rate": "6.8088",
"currency": "USD",
"total_cny": "1300.0"
},
"state": "TRADE_SUCCESS",
"execute_success_time": "2018-01-29T16:50:55+08:00",
"mer_reference_id": "20180129513666"
},
{
"order_date": "20180129",
"amount": {
"total": "200.00",
"exchange_rate": {
"rate": "6.8088"
},
"currency": "USD",
"total_cny": "1361.76"
},
"payment_id": "PAY_GI4DAMJSHEYTMNBSHA3DSMJSGEZDAMJYGAYTEOJX",
"settle_date": "20180130",
"product_id": "PaymentGateway-Debitcard",
"service_fee": "61.76",
"exchange_date": "20180130",
"exchange_amount": {
"total": "190.93",
"exchange_rate": "6.8088",
"currency": "USD",
"total_cny": "1300.0"
},
"state": "TRADE_SUCCESS",
"execute_success_time": "2018-01-29T16:42:11+08:00",
"mer_reference_id": "20180129199929"
}
],
"settle_date": "20180130"
}
}
]
请求
GET: /payments/reconciliation_statement?settle_date=20180103
GET: /payments/reconciliation_statement?settle_date=20180103&page_number=2
UMF将资金转移到商户的银行账户时会产生对账文件. 包含每一笔交易详情, 服务费和交易行为. 展示了资金转移的详情.
对账信息的日期以settle_date为准. 仅仅当UMF将资金转移到商户的银行账户时对账信息才会生成.
http get请求. 请求URL中必须带有settle_date参数.
| 参数 | 描述 |
|---|---|
| settle_date | 字符串. 将资金转移到商户的银行账户的日期. |
| page_number | 数字. 可选. 请求的页码 (从1开始). 默认值: 1 |
| page_size | 数字. 可选. 返回对象的最大值. 默认值: 500 |
响应
响应结果包含结算对象. 请参见右边示例.
| 参数 | 描述 |
|---|---|
| meta | Object. The common information of response. |
| reconciliations | Object. The information of reconciliations. |
3.21 结算文件下载(文件流)
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/payments/statement_download?settle_date=20180130 \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f"
//response
[
SETTLEDETAIL-START,70510000,20180130
2801291631868981,payment,success,PaymentGateway-Debitcard,20180129355757,20180129163131,USD,200.00,6.80880000,1361.76,61.76,20180130,BFUSD3705100002220241801290001,6.8088,USD,190.93,N/A,N/A
2801291631868981,refund,success,PaymentGateway-Debitcard,20180129355757,20180129173852,USD,200.00,6.80880000,68.08,0.00,20180130,BFUSD3705100002220241801290001,6.8088,USD,10.00,20180129355757,901012902,123456
2801291650869211,payment,success,PaymentGateway-Debitcard,20180129513666,20180129165055,USD,200.00,6.80880000,1361.76,61.76,20180130,BFUSD8705100002270201801290001,6.8088,USD,190.93,N/A,N/A
2801291650869211,refund,success,PaymentGateway-Debitcard,20180129513666,20180129174729,USD,200.00,6.80880000,68.08,0.00,20180130,BFUSD8705100002270201801290001,6.8088,USD,10.00,20180129513666,901012905,56894815
2801291642869121,payment,success,PaymentGateway-Debitcard,20180129199929,20180129164211,USD,200.00,6.80880000,1361.76,61.76,20180130,BFUSD9705100002280251801290001,6.8088,USD,190.93,N/A,N/A
2801291642869121,refund,success,PaymentGateway-Debitcard,20180129199929,20180129174311,USD,200.00,6.80880000,68.08,0.00,20180130,BFUSD9705100002280251801290001,6.8088,USD,10.00,20180129199929,901012903,185168156
SETTLEDETAIL-END,70510000,20180130,6,602.79,602.79,USD
]
GET: /payments/statement_download?settle_date=20180130
UMF会为每位商户创建每日交易列表. 该列表包含一天(settle_date)内所有成功的交易. 商户可以随时下载该列表.
交易列表日期即为商户的订单日期(settle_date).
请求
http get请求.settle_date必须在请求URL中.
响应
该接口是一个http下载接口, 交易列表被下载为一个文件.
除了第一行和最后一行，每一行都代表着一次交易.若交易数据某个字段为空，用N/A表示.若tranType值为payment时，该行的oriOrderId和refundNo字段为空
交易信息以逗号分隔并遵循以下的顺序列表:
SETTLEDETAIL-START,merId,settlement date
tradeNo,tranType,tranState,productName,mainOrderId,platDateTime,currency,cbAmount,rate,amount,comAmt,sendTime,buyForexNo,buyForexRate, buyCurrencyId,foreignAmount,oriOrderId,refundNo,refundAmountRequested
SETTLEDETAIL-END,merId,settlement date,the sum of transactions,total reference foreign amount,settlement amount,settlement currency
交易列表的属性介绍如下.
| 编号 | 字段 | 名称 | 描述 |
|---|---|---|---|
| 1 | tradeNo | 交易流水号 | UMF生成的交易流水号 |
| 2 | tranType | 交易类型 | payment或refund |
| 3 | tranState | 交易状态 | |
| 4 | productName | 产品名 | |
| 5 | mainOrderId | 主单号 | |
| 6 | platDateTime | 交易时间 | |
| 7 | currency | 标价币种 | |
| 8 | cbAmount | 标价金额 | 格式:小数点保留两位 |
| 9 | rate | 交易汇率 | |
| 10 | amount | 人民币金额 | 格式: 小数点保留两位，当tranType为refund时为已退金额 |
| 11 | comAmt | 手续费 | |
| 12 | sendTime | 购汇日期 | |
| 13 | buyForexNo | 购汇批次号 | |
| 14 | buyForexRate | 购汇汇率 | |
| 15 | buyCurrencyId | 购汇币种 | |
| 16 | foreignAmount | 参考外币金额 | |
| 17 | oriOrderId | 原单号 | 仅当tranType为refund时该字段有值，与主单号字段一致 |
| 18 | refundNo | 退款编号 | 仅当tranType为refund时该字段有值 |
| 19 | refundAmountRequested | 商户请求退款金额 |
3.22 对账信息下载（JSON）
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/payments/transactions?mer_date=20170213 \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f"
//response
{
"meta":{
"sign":"Alc9iDPd4P2z3LzeaZj73aC2fmeHZmlh59d7+MvZoDRYUsOF3lLGe92VhqWhRERvXCBBOK+SarPSI72pj1rHCqTcVd6/hagHKJa/j4k0CodwsrYXhoayLhu6Y/XG7JllyY2pa84J+xLCv/D81KvwWukOpK3MRNf5yq9zrVaVD5E=",
"ret_msg":"Success",
"ret_code":"0000"
},
"transactions":{
"payment_summaries":[
{
"payment_id":"SDSWEWSD23123143DSDFSDF234234",
"phone_number":"18710129807",
"order_date":"20170316",
"mer_reference_id":"20170316114145",
"amount":{
"total": 49.41,
"total_cny": 344.91,
"currency": "USD",
"exchange_rate":6.9800
},
"settle_date":"20170317",
"execute_success_time":"2017-03-17T19:20:30+08:00",
"state":"TRADE_SUCCESS",
"product_id":"Payment Gateway - Alipay QR code"
},
{
"payment_id":"768HIOUKJHTJHLKHYOIT",
"phone_number":"18710129807",
"order_date":"20170316",
"mer_reference_id":"20170316114145",
"amount":{
"total": 49.41,
"total_cny": 344.91,
"currency": "USD",
"exchange_rate":6.9800
},
"settle_date":"20170317",
"execute_success_time":"2017-03-17T19:20:30+08:00",
"state":"TRADE_SUCCESS",
"product_id":"Payment Gateway - Alipay QR code"
}
],
"refund_summaries":[
{
"refund_id":"IUIUYTHJY58765874KJHKUUTIUI",
"payment_id":"SDSWEWSD23123143DSDFSDF234234",
"phone_number":"18710129807",
"amount":{
"total": 49.41,
"total_cny": 344.91,
"currency": "USD",
"exchange_rate":6.9800
},
"settle_date":"20170317",
"execute_success_time":"2017-03-17T19:20:30+08:00",
"state":"REFUND_SUCCESS",
"mer_sub_reference_id":"Payment Gateway - Alipay QR code"
}
],
"pagination":{
"total_count":3,
"page_number":1,
"page_size":50
}
}
}
请求
GET: /payments/transactions?mer_date=20170213
GET: /payments/transactions?mer_date=20170213&page_number=2
http get请求. 在url中mer_date参数.当一次响应多个交易时，需要在url中添加page_number参数.
| 参数 | 描述 |
|---|---|
| mer_date | 字符串. 商户付款日期. |
| page_number | 数字. 可选. 请求的页码 (从1开始). 默认值: 1 |
| page_size | 数字. 可选. 返回对象的最大值. 默认值: 500 |
响应
响应结果包含一个对账 对象. 请参见右边示例.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共信息. |
| transactions | 对象数组. 对账信息. 请参见右边示例. |
3.23 对账文件下载(文件流)
GET: /payments/transactions_download?settle_date=20170213
对账文件是一个以商户在UMF中帐户余额的记录开始，增加或减少对账明细,调整第三方持有同一账户的账单的文件.
和交易列表下载是同一个业务逻辑. 对账文件日期以订单日期为准.
请求
http get请求. settle_date必须在请求的url中.
响应
该接口是一个http下载接口, 对账信息被下载为一个文件.
文件内容以逗号分隔并遵循以下的顺序列表:
TRANSDETAIL-START,商户号,结算日期
tradeno,mobileid,orderid,orderdate,platdate,plattime,currency,cbamount,amount,exchangerate,settledate, transtate,transtype,productid,merdate,refundno,prefundtradeno,cardholder,identifycode,comamt
TRANSDETAIL-END,商户号,结算日期,对账笔数
对账文件内容字段属性如下.
| No | field | name | description |
|---|---|---|---|
| 1 | tradeno | U付订单号 | String. |
| 2 | mobileid | 手机号 | String. |
| 3 | orderid | 订单号 | String. |
| 4 | orderdate | 订单日期 | YYYYMMDD. |
| 5 | platdate | 支付日期 | YYYYMMDD. |
| 6 | plattime | 支付成功时间 | HHmmss. |
| 7 | currency | 交易币种 | String. |
| 8 | cbamount | 交易外币金额 | 单位：元 |
| 9 | amount | 交易人民币金额 | 单位：元 |
| 10 | exchangerate | 交易汇率 | |
| 11 | settledate | 对账日期 | YYYYMMDD |
| 12 | transtate | 交易状态 | |
| 13 | transtype | 交易类型 | |
| 14 | productid | 支付产品号 | |
| 15 | merdate | 商户日期 | YYYYMMDD |
| 16 | refundno | 退款流水号 | |
| 17 | prefundtradeno | 退费原U付订单号 | String. |
| 18 | cardholder | 姓名 | String. |
| 19 | identifycode | 身份证号 | String. |
| 20 | comamt | 手续费 | 单位：元 |
3.24 生成月对账单
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/settle_month_create \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM=" \
-d '{
"settle_month": "201801"
}'
## Response data:
{
"links": [{
"ref": "settleMonthFileDownLoad",
"method": "GET",
"href": "https://uatfx.soopay.net/cberest/v1/payments/FILE_GIYDCOBQGEZDAMJYGAYTEOPX/settle_month_file_download"
}],
"meta": {
"ret_code": "0000",
"ret_msg": "successful transaction"
},
"settle_month_file": {
"settle_month": "201801"
}
}
请求
POST: /payments/settle_month_create
生成月对账单.
该接口将返回月对账下载链接.该链接24小时后允许下载
参数
| 参数 | 描述 |
|---|---|
| settle_month | 对账月份. |
响应
| 参数 | 描述 |
|---|---|
| links | 对象数组. 下一步操作的链接. |
| meta | 对象. 响应的公共信息. |
| settle_month_file | 对象. |
3.25 月对账单下载
GET: /payments/{file_id}/settle_month_file_download
请求url中的file_id为生成月对账单成功响应的链接中的file_id.
请求
http get请求.
响应
该接口是一个http下载接口, 月对账单被下载为一个文件.
文件内容以逗号分隔并遵循以下的顺序列表:
MONTHLYBILL_START,商户号,月份
order_id/refund_no,trade_no,order_form_time,order_finish_time,product_name,merchant_amount, merchant_currency,transaction_rate,transaction_amount,fee,net_amount,transaction_type, transaction_state,purchase_date,purchase_rate,reference_foreign_amount,settle_currency,settle_state,settle_date,origin_order_id
MONTHLYBILL_END,商户号,账单周期,交易笔数,结算币种,本月购汇总金额，本月已付汇总金额
月账单文件内容字段属性如下.
| 编号 | 字段 | 名称 | 描述 |
|---|---|---|---|
| 1 | order_id/refund_no | 订单号/退款流水号 | 当交易类型为支付时，该字段为订单号，为退款时，该字段为退款流水号 |
| 2 | trade_no | U付订单号 | 退费则为退费U付订单号 |
| 3 | order_form_time | 订单创建时间 | 支付订单的创建时间 |
| 4 | order_finish_time | 订单支付完成时间 | 订单支付完成时间 |
| 5 | product_name | 产品名称 | 支付产品名称 |
| 6 | merchant_amount | 订单金额 | 订单金额 |
| 7 | merchant_currency | 标价币种 | 订单标价币种 |
| 8 | transaction_rate | 交易汇率 | 标价币种为外币时的交易时汇率 |
| 9 | transaction_amount | 支付金额 | 支付人民币金额 |
| 10 | fee | 手续费 | 手续费金额 |
| 11 | net_amount | 支付净额 | 支付人民币净额 |
| 12 | transaction_type | 交易类型 | 支付/退款 |
| 13 | transaction_state | 交易状态 | 交易状态 |
| 14 | purchase_date | 购汇日期 | 购汇完成日期 |
| 15 | purchase_rate | 购汇汇率 | 购汇时汇率 |
| 16 | reference_foreign_amount | 参考外币金额 | 参考外币金额 |
| 17 | settle_currency | 结算币种 | 计算外币币种 |
| 18 | settle_state | 结算状态 | 结算状态，Y：已结算 N：未结算 |
| 19 | settle_date | 结算日期 | 结算日期（付汇日期） |
| 20 | origin_order_id | 订单号 | 支付原订单号，交易类型为退款时该字段有值 |
3.32 海关/国检重推
## Request data:
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/declare_again/CUST_GA2TAOBRGYZTAMJTHE2TSMBUGQZDAMJZGA2TAOB4
CIQ_GA2TANZTGIYTSNJSGEZDAMJYGA2TANYO \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
## Response data:
'{
"declare_again": {
"declare_type": "0",
"mer_reference_id": "0115144722428302"
},
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
}
}'
请求
GET: /declare_again/{id}
如清关时出现支付单不存在，且联动侧支付人身份信息通过，并报送30分钟后，商户可调动该接口，UMF会重新上送此笔数据
请求url中的id是在上一步创建的真实(报关id)、(报检id)、(独立报关id)、(独立报检id).
响应
| Parameter | Description |
|---|---|
| meta | 对象. 响应公共部分. |
| declare_again | 对象. 重推信息. |
3.34 账户可退款余额查询
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/payments/payment/self_account_balance \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f"
//response
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"accountBalance": {
"balance": "472627.21"
}
}
GET: /payments/payment/self_account_balance
获取实时可退款余额，返回为人民币金额，单位元
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共部分. |
| account_balance | 账户余额. |
3.35 下单(协议支付)
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM=" \
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"bank_code": "BOC",
"payer_info": {
"phone": "13131313131"
},
"interface_type": "SERVER_TO_SERVER",
"external_customer_id": "UMP1499826888843602",
"business_type": "B2C"
},
"order": {
"mer_reference_id": "1219143301457101",
"mer_date": "20191219",
"amount": {
"total": "100",
"currency": "USD"
},
"order_summary": "CrossBorderOrderSummary",
"expire_time": "360",
"user_ip": "10.10.70.134",
"sub_orders": [{
"mer_sub_reference_id": "1219143301458102",
"trans_code": "03223010",
"amount": {
"total": "50.0",
"currency": "USD"
},
"is_customs": "False",
"invoice_id": "123456"
},
{
"trans_code": "01122030",
"amount": {
"total": "50.0",
"currency": "USD"
},
"is_customs": "False",
"invoice_id": "123456",
"items": [{
"mer_item_id": "1219143301458103",
"type": "FOOD",
"name": "banana",
"quantity": "2",
"description": "banana",
"amount": {
"total": "50.0",
"currency": "USD"
}
}]
}],
"sub_mer_id": "umfsubmer001",
"if_sms": "Y"
},
"notify_url": "http://10.10.38.49:2216/spay_rest/payments/test/mer",
"ret_url": "http://10.10.38.49:2213/notify0000V4.jsp",
"risk_info": {
"trans_type": "02"
}
}'
## Response data:
'{
"payment": {
"id": "PAY_GY4TCMRRHEYTIMJZG4ZTCNZUGQZDAMJZGEZDCOMI",
"order": {
"amount": {
"total": "100",
"currency": "USD"
},
"mer_date": "20191219",
"sub_mer_id": "umfsubmer001",
"sub_orders": [{
"amount": {
"total": "50.0",
"currency": "USD"
},
"trans_code": "03223010",
"invoice_id": "123456",
"is_customs": "False",
"mer_sub_reference_id": "1219143301458102"
},
{
"amount": {
"total": "50.0",
"currency": "USD"
},
"trans_code": "01122030",
"items": [{
"amount": {
"total": "50.0",
"currency": "USD"
},
"mer_item_id": "1219143301458103",
"description": "banana",
"name": "banana",
"quantity": "2",
"type": "FOOD"
}],
"invoice_id": "123456",
"is_customs": "False",
"mer_sub_reference_id": "1219143301737008"
}],
"if_sms": "Y",
"expire_time": "2019-12-20T14:19:45+0800",
"order_summary": "CrossBorderOrderSummary",
"mer_reference_id": "1219143301457101",
"user_ip": "10.10.70.134"
},
"payer": {
"payer_info": {
"bank_card": {
"phone": "",
"payer_name": "",
"citizen_id_type": "IDENTITY_CARD",
"valid_date": "",
"number": "",
"cvv2": "",
"citizen_id_number": ""
},
"payer_agreement": {
"usr_pay_agreement_id": "",
"usr_busi_agreement_id": ""
}
},
"interface_type": "SERVER_TO_SERVER",
"external_customer_id": "UMP1499826888843602",
"business_type": "B2C",
"bank_code": "BOC",
"payment_method": "DEBIT_CARD"
},
"state": "WAIT_BUYER_PAY",
"notify_url": "http://10.10.38.49:2216/spay_rest/payments/test/mer",
"risk_info": {
"trans_type": "02"
},
"is_from_US": "Y",
"ret_url": "http://10.10.38.49:2213/notify0000V4.jsp"
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMJZG4ZTCNZUGQZDAMJZGEZDCOMI"
},
{
"ref": "agreement_sms_verify",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/agreement/PAY_GY4TCMRRHEYTIMJZG4ZTCNZUGQZDAMJZGEZDCOMI/verify"
},
{
"ref": "self_payment_refund",
"method": "GET",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMJZG4ZTCNZUGQZDAMJZGEZDCOMI/self_payment_refund"
}],
"meta": {
"ret_code": "0000",
"ret_msg": "交易成功"
}
}'
请求
POST: /payments/payment
创建一个稍后或立即执行的支付单, 取决于付款类型.
下面的表格展示了UMF支持的支付类型, 所有的付款必须使用人民币支付:
接口类型为SERVER_TO_SERVER时，支付方式如下：
| 支付方式（payment_method） | 描述 |
|---|---|
| CREDIT_CARD | 信用卡支付 |
| DEBIT_CARD | 借记卡支付 |
| 接口类型(interface_type) | 描述 |
|---|---|
| SERVER_TO_SERVER | API模式 |
| 模式(business_type) | 描述 |
|---|---|
| B2C | B2C |
| 参数 | 描述 |
|---|---|
| payer | 对象. 支付信息. |
| order | 对象. 订单信息. 包含子订单. |
| notify_url | String. 商户服务器的url 接收支付结果. |
| risk_info | Object. The information of transaction. |
响应:
响应结果包含meta信息和一个支付对象. 请参见右边的示例. 已创建的支付对象包含如下信息：
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| payment | 对象. 支付对象. |
| links | 对象数组. 下一步操作的链接. 取决于支付类型的状态. 链接是HATEOAS链接. |
3.36 下发短信(协议支付首次下发短信)
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/agreement/PAY_GY4TCMRRHEYTIMJZG4ZTCNZUGQZDAMJZGEZDCOMI/verify \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"bank_code": "BOC",
"payer_info": {
"bank_card": {
"number": "DBYomKOn/H5Grpb8cFOk6Ze4tYsJm4CfpXqn41VcuMqZrjHqUQZulqcphq8eZJ3003k4Az50RnEKUn7qoCNI85jDfd/z3xeiZiTWiC/qiB6eiBN0Ju2cVawfuLUr1eYvsI2UaXmvYso349k30fA8MUO8\u003d",
"citizen_id_number": "qxq836xD7aR2wiSiccVjuU4AWpyrt1Z4LdAgDe8ftwBiaOx4llkS1xKIo2Jig2KcR2z5ApMmIye7Bp9mh8l8BMFOYQBnk+h7Igz54Y4qtdpH6bHbhmcrdqgCyITjKSCc04QF1dPa7kDovxEOx4rjhXtmJw9atIgUanA\u003d",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "jtXyFaH6dZIhVnUWhoq7Zkb7HbGgzKGIzrGGE7ieu+s4j3TCbBpYK2pe8nJ7Fv1XczMnKHWmeleyHgQyeJqUy594ugqU9Q+wfPplsqU7HZx2DUpqneffQBz7aU/im68UKYW+eEEjhJPiCCIYJigA9X4DpIA1NucY8\u003d",
"valid_date": "",
"cvv2": "",
"phone": "15754314122"
}
},
"external_customer_id": "1980655668"
}
}'
//Response:
'{
"payment": {
"id": "PAY_GY4TCMRRHEYTIMJZG4ZTCNZUGQZDAMJZGEZDCOMI",
"payer": {
"payer_info": {
"bank_card": {
"phone": "15754314122",
"payer_name": "mBakvdbsU/H3Qi9xSQNtR/Oap2YGkut3Up6/3b13alI3OUyZWDmvlgvxuorxrqIW9yd4CzsRYTrpvPtJuhCGroV5AjZpdf+5M9KdDXuVMiaxWM5G0btpLEwF1aafHOpoqR7ScstXgLhs/jCt2q5Lv3muo=",
"citizen_id_type": "IDENTITY_CARD",
"valid_date": "",
"number": "XBGF1LZiOM7kyFOO6/7tpD33DdUC7x0FYHAy6adMsbW+mH7CQFT9nGmd4yRBWJUpZpMYlM3rkjgyuTC5UviDzwpyLQYcT1FdzCTfBUKKjQTMpao7olDNXnUhdBjY3HAVZAW9ZWweISld1i7DHtuNteST8ZsUKczrsw1c=",
"cvv2": "",
"citizen_id_number": "lV1RjtaZUbFie8YICUd3juF252tr7CVkTlmUpgKX6RxgtHTt9FNY/+28XGo9F46LqNmYFY21t3vEkAwPlYg5QZkpS037FAf6vc2X4MrBSfEDDLMOVflyhUvmhU0kIFPyj8/dt44wUJVxCbIms8J+FYwrNyK4="
}
},
"external_customer_id": "1980655668",
"bank_code": "BOC",
"payment_method": "DEBIT_CARD"
}
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMJZG4ZTCNZUGQZDAMJZGEZDCOMI"
},
{
"ref": "agreement_confirm",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/agreement/PAY_GY4TCMRRHEYTIMJZG4ZTCNZUGQZDAMJZGEZDCOMI/execute"
}],
"meta": {
"ret_code": "0000",
"ret_msg": "交易成功"
}
}'
只有银行卡支付才会下发短信验证码.
在这个过程中, 商户发送银行卡信息, UMF(或者银行) 将向用户手机发送短信验证码. 短信验证码是完成支付过程参数的一部分.
请求
POST:/payments/payment/agreement/{payment_id}/verify
请求url中的payment_id是在上一步创建的真实payment_id(下单).
可用的支付对象
| 参数 | 描述 |
|---|---|
| payer | 对象. 支付信息.某些参数应该使用 UMF公钥加密. 看支付对象的描述信息. |
响应
响应结果仅仅包含下一步操作的链接. 看右边的示例. 如果请求合法, 短信将发送到用户手机.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| links | 对象数组. 下一步操作的链接. |
3.37 确认支付(协议支付首次确认支付)
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/agreement/PAY_GI3TAOBQGEYDQMRQHAYTMMJRGEZDAMJXGA3TGMKN/execute \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:a/1A+rSDh2EBPGgiqRcET1hNcUtPBjSjQOYZmkqLx1n+IPAeM2p5c29XkB64jMy0fHfzFaK/cCj3vvq/f+o2fqC+WsLWnby34ByxdH+sgTK+I+bkzEdvwD7S9NCWwdMxejwuhBu+HcUn7uLhYgeRdOXfLIH/aThssRoBMTcmeZc="
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"bank_code": "BOC",
"payer_info": {
"bank_card": {
"number": "vi2nq8Pf7b18/y40/g61PS1Ow34I126gNmjiMb61eLehGxhqWRuDbY1ENCJx1y3DpXrvS6EVpiL/bzBwrRe46KyZnD23ofPUE1er0pTrv54slsIYSz3SFhUXiYlER3IgCroa+wuuwL97gyk2CmlQ7kpltZb4\u003d",
"citizen_id_number": "CpudGFVGe8KASKsyVPJHhNaCsRZ0QGsPXHSRj68PVq8AU1y5874M9H9/IxeevTAYayPVpldiwjtrkwnU+ecqnLvDdjmcGDcrw3gx0T6PlJEUis7ttcDtxu3T1qB9hNEWuIU0CFxYjO4L22sbfiNvX7a/tDw\u003d",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "g0yHps8zOCR4TMVKG4ea91qOpJjrqiMbKNiB0mcpoRnH5TOcJYQW5qE0q9/SDPsc1dG5tyRBYLhRBOTwv1w9VoUTREl8i0yImyVbv0qeTPFZRTE1V689VmzOp0fRm6Yneuua3HojIP5tJfMCsNr3e/kY\u003d",
"valid_date": "",
"cvv2": "",
"phone": "15754314122",
"verify_code": "192804"
}
},
"external_customer_id": "1980655668"
},
"order": {
"if_sms": "Y"
}
}'
## Response data:
'{
"payment": {
"id": "PAY_GY4TCMRRHEYTIMJZG4ZTCNZUGQZDAMJZGEZDCOMI",
"execute_success_time": "2019-12-19T14:34:52+0800",
"order": {
"if_sms": "Y"
},
"payer": {
"payer_info": {
"bank_card": {
"phone": "15754314122",
"payer_name": "jUca5Ff9/Su5m26hD2lN5QdX7z2pCuJrG72kCc1wGvnve1nNLs8whUWby9mmadVU+ZsAKcTdaFWpevxV0xAyrIzjHreCCI+vGNt5uer5EkVIdVDAxOawb9fLrCjjbGwE8exXwll6xwoAu5YNXSDDgIfLdlmE=",
"citizen_id_type": "IDENTITY_CARD",
"valid_date": "",
"number": "jf07wMz/xh4GpHElz4iztQ0yJly3CHSRD/ucH+49NVVOseraiv5t6e+koEvcDmV0jDrjuvY7rcMdyXNOYd9z5Qed3I61Tt75M79Ykwkv8fRnYkKLsRpYOlelqdlvs5GbrbT4mY3mV/cSP2Oj0PjDX6xxySJI6D4=",
"cvv2": "",
"verify_code": "192804",
"citizen_id_number": "PPgMwxYpwzVV3jctTVGHQ1o3fJ8zMcJ9n9Cm9wZ1yudTTO7OGjnrmHHGplS7eBF/BPcF0Xr2F0OHCPV9uFlH+LgyBYf1ruNuJyU80Kad6L8MGl4ejJrZLCIMB3W0uTukvLlZ7EXCsfIDZYZ7pyrogMS2HSqs="
},
"payer_agreement": {
"usr_pay_agreement_id": "fsdsdfssf",
"usr_busi_agreement_id": "fsfsfsfssfs"
}
},
"external_customer_id": "1980655333",
"bank_code": "BOC",
"payment_method": "DEBIT_CARD"
},
"state": "TRADE_SUCCESS",
"settle_date": "20191219"
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMJZG4ZTCNZUGQZDAMJZGEZDCOMI"
},
{
"ref": "apply_to_customs",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMJZG4ZTCNZUGQZDAMJZGEZDCOMI/apply_to_customs"
},
{
"ref": "refund",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMJZG4ZTCNZUGQZDAMJZGEZDCOMI/refund"
},
{
"ref": "asynchronous_refund",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMJZG4ZTCNZUGQZDAMJZGEZDCOMI/asynchronous_refund"
},
{
"ref": "apply_to_ciq",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMJZG4ZTCNZUGQZDAMJZGEZDCOMI/apply_to_ciq"
}],
"meta": {
"ret_code": "0000",
"ret_msg": "交易成功"
}
}'
处理完支付单,并且交易完成后. 资金从用户账户转移到UMF商户账户.
要执行支付单, 请在请求url中添加payment ID参数, 在请求的JSON body中包含一个payer对象.
处理结果不会立即返回. 商户想要获取结果有两种方式，方式如下:
– 查询付款结果. 支付成功的状态为"TRADE_SUCCESS". – 等待UMF通知. 商户需要开发http(s)服务. 支付产生结果时,UMF请求到这个服务.
请求
POST:/payments/payment/agreement/{payment_id}/execute
请求url中的payment_id是在上一步创建的真实payment_id(下单).
参数
| 参数 | 描述 |
|---|---|
| payer | 对象. 支付信息. 一些参数应该用UMF公钥加密. 参见payer对象的描述. 若支付类型是银行卡或者信用卡, payer对象应该包含手机验证码. |
响应
响应结果包含payment对象. 银行卡信息不将返回, 例如card number, cvv2, citizen_id, 等等.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| payment | 对象. 支付对象. |
| links | 对象数组. 下一步操作的链接. 链接是HATEOAS链接. |
3.38 下发短信(协议支付二次下发短信)
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/agreement/PAY_GY4TCMRRHEYTIMJZG4ZTCNZUGQZDAMJZGEZDCOMI/verify \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"bank_code": "BOC",
"payer_info": {
"payer_agreement": {
"usr_pay_agreement_id": "dsadasdsasda",
"usr_busi_agreement_id": "dadasdasdada"
}
},
"external_customer_id": "1980655333"
}
}'
//Response:
'{
"payment": {
"id": "PAY_GY4TCMRRHEYTIMRSG4ZTENZSGQZDAMJZGEZDCOKL",
"payer": {
"payer_info": {
"bank_card": {
"phone": "15754314122",
"payer_name": "N6SoTa1ngLQM41BMaGakqBuN3dfq6+Az7Pa4ScoMaBV2SS9LbpOvJLGoV4KlhDvcihDBioyMgfcqfS9GWO+GKXtmUmH9bz8l5Uo9mekt27gQXbzl7hUei+7yZsBrW1pttnlQe7hK1PrV/AAy3SCWly58fzIA=",
"citizen_id_type": "IDENTITY_CARD",
"valid_date": "",
"number": "SBnJ/cbP3H4vz+mpVfa2Eu7Y+C6cHd3rgjwAsemNR+nMxsokdydfnCyaZLjkbkqlqya647nx1sOezGl/mMCKsX/B4rWn8ZEjBFf3HR3GyVkT0xFRCnbM9I/TuoKSqyIypcKnYktR4n+4ncvQQjsLBo83w5KA=",
"cvv2": "",
"citizen_id_number": "FyQOpgzE5bEzsMxfo7w6TXxkU3crsj92ajZBq/Rjmvk0Z0VdA0tMQLcJqGoGpukxiIpb+dBQBqksGafHOW1dS5Np/Q3QXoVK6BW6BqZcicmuegq4NAqg0hBxxbSgsn9Yzp5swAFnSd03aN5P0Kg068ATSv4Q="
},
"payer_agreement": {
"usr_pay_agreement_id": "dsdadas",
"usr_busi_agreement_id": "dasdadasdasd"
}
},
"external_customer_id": "1980655333",
"bank_code": "BOC",
"payment_method": "DEBIT_CARD"
}
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMRSG4ZTENZSGQZDAMJZGEZDCOKL"
},
{
"ref": "agreement_confirm",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/agreement/PAY_GY4TCMRRHEYTIMRSG4ZTENZSGQZDAMJZGEZDCOKL/verify"
}],
"meta": {
"ret_code": "0000",
"ret_msg": "交易成功"
}
}'
只有银行卡支付才会下发短信验证码.
在这个过程中, 商户发送银行卡信息, UMF(或者银行) 将向用户手机发送短信验证码. 短信验证码是完成支付过程参数的一部分.
请求
POST:/payments/payment/agreement/{payment_id}/verify
请求url中的payment_id是在上一步创建的真实payment_id(下单).
可用的支付对象
| 参数 | 描述 |
|---|---|
| payer | 对象. 支付信息.某些参数应该使用 UMF公钥加密. 看支付对象的描述信息. |
响应
响应结果仅仅包含下一步操作的链接. 看右边的示例. 如果请求合法, 短信将发送到用户手机.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| links | 对象数组. 下一步操作的链接. |
3.39 确认支付(协议支付二次发短信确认支付)
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/agreement/PAY_GI3TAOBQGEYDQMRQHAYTMMJRGEZDAMJXGA3TGMKN/execute \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:a/1A+rSDh2EBPGgiqRcET1hNcUtPBjSjQOYZmkqLx1n+IPAeM2p5c29XkB64jMy0fHfzFaK/cCj3vvq/f+o2fqC+WsLWnby34ByxdH+sgTK+I+bkzEdvwD7S9NCWwdMxejwuhBu+HcUn7uLhYgeRdOXfLIH/aThssRoBMTcmeZc="
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"bank_code": "BOC",
"payer_info": {
"payer_agreement": {
"usr_pay_agreement_id": "asdsadaasd",
"usr_busi_agreement_id": "dasdasdasdasd",
"verify_code": "177554"
}
},
"external_customer_id": "1980655333"
},
"order": {
"if_sms": "Y"
}
}'
## Response data:
'{
"payment": {
"id": "PAY_GY4TCMRRHEYTIMRSG4ZTENZSGQZDAMJZGEZDCOKL",
"execute_success_time": "2019-12-19T14:38:25+0800",
"order": {
"if_sms": "Y"
},
"payer": {
"payer_info": {
"bank_card": {
"phone": "15754314122",
"payer_name": "plIhAzMAGD6DODRLDzcOM6QcnEiH+7/rKBvDYYpV9bDq6us6zmSTPkLpf7iNLYSPhGEGMON0cHesN5ScFZBdq0DD2l2ICZoMnIxpXEIIUykyFvsm7SXjU54Szy4UlPXsR5xrk/ABn2TNLoJFRFwA8MOGRxM=",
"citizen_id_type": "IDENTITY_CARD",
"valid_date": "",
"number": "Tiamtr73kegodKiG/Su97FPFFQtS9k+h9MwDladdKebfKGkh3lo67zeqkeP2+8hK5oJeNCtIAPXmVa2jVkyhP44qkUG/uNQdqfT1IaI5JjmGxJbApTcXYi/vY7Va3+hYn90rr2dONWNi0FluKggDs750Edzk4=",
"cvv2": "",
"verify_code": "177554",
"citizen_id_number": "PHq6R36WRZ/by2MPPmz4pXp+cfoavCpAT7YWRvnwUgyeMuWK+bKx6pr5PrelI1Oum4JXxYKoIHVDy25iZMWUvUzrgMNTABEUTuSSXXi8krcB6PPevX5IptjvJCR6Y17mrlK46ts0abZ2UCOr9DmdkkVDsuYA4="
},
"payer_agreement": {
"usr_pay_agreement_id": "dasdsdadasadas",
"usr_busi_agreement_id": "dasdasdadad"
}
},
"external_customer_id": "1980655333",
"bank_code": "BOC",
"payment_method": "DEBIT_CARD"
},
"state": "TRADE_SUCCESS",
"settle_date": "20191219"
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMRSG4ZTENZSGQZDAMJZGEZDCOKL"
},
{
"ref": "apply_to_customs",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMRSG4ZTENZSGQZDAMJZGEZDCOKL/apply_to_customs"
},
{
"ref": "refund",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMRSG4ZTENZSGQZDAMJZGEZDCOKL/refund"
},
{
"ref": "asynchronous_refund",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMRSG4ZTENZSGQZDAMJZGEZDCOKL/asynchronous_refund"
},
{
"ref": "apply_to_ciq",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMRSG4ZTENZSGQZDAMJZGEZDCOKL/apply_to_ciq"
}],
"meta": {
"ret_code": "0000",
"ret_msg": "交易成功"
}
}'
处理完支付单,并且交易完成后. 资金从用户账户转移到UMF商户账户.
要执行支付单, 请在请求url中添加payment ID参数, 在请求的JSON body中包含一个payer对象.
处理结果不会立即返回. 商户想要获取结果有两种方式，方式如下:
– 查询付款结果. 支付成功的状态为"TRADE_SUCCESS". – 等待UMF通知. 商户需要开发http(s)服务. 支付产生结果时,UMF请求到这个服务.
请求
POST:/payments/payment/agreement/{payment_id}/execute
请求url中的payment_id是在上一步创建的真实payment_id(下单).
参数
| 参数 | 描述 |
|---|---|
| payer | 对象. 支付信息. 一些参数应该用UMF公钥加密. 参见payer对象的描述. 若支付类型是银行卡或者信用卡, payer对象应该包含手机验证码. |
响应
响应结果包含payment对象. 银行卡信息不将返回, 例如card number, cvv2, citizen_id, 等等.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| payment | 对象. 支付对象. |
| links | 对象数组. 下一步操作的链接. 链接是HATEOAS链接. |
3.40 确认支付(协议支付二次不发短信确认支付)
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/agreement/PAY_GI3TAOBQGEYDQMRQHAYTMMJRGEZDAMJXGA3TGMKN/execute \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:a/1A+rSDh2EBPGgiqRcET1hNcUtPBjSjQOYZmkqLx1n+IPAeM2p5c29XkB64jMy0fHfzFaK/cCj3vvq/f+o2fqC+WsLWnby34ByxdH+sgTK+I+bkzEdvwD7S9NCWwdMxejwuhBu+HcUn7uLhYgeRdOXfLIH/aThssRoBMTcmeZc="
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"bank_code": "BOC",
"payer_info": {
"payer_agreement": {
"usr_pay_agreement_id": "dasdsadadsad",
"usr_busi_agreement_id": "dasdadadasd"
}
},
"external_customer_id": "1980655333"
},
"order": {
"if_sms": "N"
}
}'
## Response data:
'{
"payment": {
"id": "PAY_GY4TCMRRHEYTIMRSG4ZTENZSGQZDAMJZGEZDCOKL",
"execute_success_time": "2019-12-19T14:38:25+0800",
"order": {
"if_sms": "N"
},
"payer": {
"payer_info": {
"bank_card": {
"phone": "15754314122",
"payer_name": "plIhAzMAGD6DODRLDzcOM6QcnEiH+7/rKBvDYYpV9bDq6us6zmSTPkLpf7iNLYSGMON0cHesN5ScFZBdq0DD2l2ICZoMnIxpXEIIUykyFvsm7SXjU54Szy4UlPXsR5xrk/ABn2TNLoJFRFwA8MOGRxM=",
"citizen_id_type": "IDENTITY_CARD",
"valid_date": "",
"number": "Tiamtr73kegodKiG/Su97FPFFQtSebfKGkh3lo67zeqkeP2+8hK5oJeNCtIAPXmVa2jVkyhP44qkUG/uNQdqfT1IaI5JjmGxJbApTcXYi/vY7Va3+hYn90rr2dONWNi0FluKggDs750Edzk4=",
"cvv2": "",
"verify_code": "177554",
"citizen_id_number": "PHq6R36WRZ/by2MPPmz4pXp+cfoavCpAT7YWRvnwUgyeMuWK+bKx6pr5PrelI1Oum4JXxYKoIHVDy25iZMWUvUzrgMsABEUTuSSXXi8krcB6PPevX5IptjvJCR6Y17mrlK46ts0abZ2UCOr9DmdkkVDsuYA4="
},
"payer_agreement": {
"usr_pay_agreement_id": "dsadasdadad",
"usr_busi_agreement_id": "dasdadasda"
}
},
"external_customer_id": "1980655333",
"bank_code": "BOC",
"payment_method": "DEBIT_CARD"
},
"state": "TRADE_SUCCESS",
"settle_date": "20191219"
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMRSG4ZTENZSGQZDAMJZGEZDCOKL"
},
{
"ref": "apply_to_customs",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMRSG4ZTENZSGQZDAMJZGEZDCOKL/apply_to_customs"
},
{
"ref": "refund",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMRSG4ZTENZSGQZDAMJZGEZDCOKL/refund"
},
{
"ref": "asynchronous_refund",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMRSG4ZTENZSGQZDAMJZGEZDCOKL/asynchronous_refund"
},
{
"ref": "apply_to_ciq",
"method": "POST",
"href": "http://10.10.178.36:8071/spay_rest/payments/payment/PAY_GY4TCMRRHEYTIMRSG4ZTENZSGQZDAMJZGEZDCOKL/apply_to_ciq"
}],
"meta": {
"ret_code": "0000",
"ret_msg": "交易成功"
}
}'
处理完支付单,并且交易完成后. 资金从用户账户转移到UMF商户账户.
要执行支付单, 请在请求url中添加payment ID参数, 在请求的JSON body中包含一个payer对象.
处理结果不会立即返回. 商户想要获取结果有两种方式，方式如下:
– 查询付款结果. 支付成功的状态为"TRADE_SUCCESS". – 等待UMF通知. 商户需要开发http(s)服务. 支付产生结果时,UMF请求到这个服务.
请求
POST:/payments/payment/agreement/{payment_id}/execute
请求url中的payment_id是在上一步创建的真实payment_id(下单).
参数
| 参数 | 描述 |
|---|---|
| payer | 对象. 支付信息. 一些参数应该用UMF公钥加密. 参见payer对象的描述. 若支付类型是银行卡或者信用卡, payer对象应该包含手机验证码. |
响应
响应结果包含payment对象. 银行卡信息不将返回, 例如card number, cvv2, citizen_id, 等等.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| payment | 对象. 支付对象. |
| links | 对象数组. 下一步操作的链接. 链接是HATEOAS链接. |
3.41 银行卡下单接口（无paymentId）
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/apply_sms \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:a/1A+rSDh2EBPGgiqRcET1hNcUtPBjSjQOYZmkqLx1n+IPAeM2p5c29XkB64jMy0fHfzFaK/cCj3vvq/f+o2fqC+WsLWnby34ByxdH+sgTK+I+bkzEdvwD7S9NCWwdMxejwuhBu+HcUn7uLhYgeRdOXfLIH/aThssRoBMTcmeZc="
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"bank_code": "SPDB",
"payer_info": {
"bank_card": {
"number": "RvlRh6WYjw96SHXY1/pO4TgE01lQ3OCuZR7GpYzDm3gT13vWXKtasdfEWqntOxr3yrN7MFxp+TMRTJWy3JX2EQQudfOGYNeis7YHMNhzTqRkknZd/jkP0SiiVd6OSOANeU2Nm6T3p2/Ku9BMh/sw5PGgXfBtsElzLnjepSc+NQ\u003d",
"citizen_id_number": "UZGG1w8PQZDtmg8VZDybjuUu82lu4VHmVTxw8qtlf2mEbgRcmFwfpyBEH4PNBmXtCvyLB6/tz5sgEkZ8z5TPV3Clfzx1WGHQSWjG6oIWrgli0vQFkQCsQLFf9lcNRUW0IcUbPkwZzerEcEFRqNMQJBZZsHO3I3mLuZwlM5ifpYk\u003d",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "OwvLX/0iVm4mI4ZNfOpXOGk+1YuOI3+fv8gP42DLg2PCl5Fh/PuZizwOuiCguW6x3NzflALloHOFqlId3MbR0NeehGvQsyCPq6bOpJY++foOs34ohw/bpNzyjHF7x/FP5cgUmZzcLIjfWcDC2mvzuJSoVPzNO28h1eSB2mMzeXU\u003d",
"phone": "13552100000"
}
},
"external_customer_id": "000000"
},
"order": {
"mer_reference_id": "0115172540746101",
"mer_date": "20200115",
"amount": {
"total": "0.1",
"currency": "CNY"
},
"order_summary": "CrossBorderOrderSummary",
"expire_time": "360",
"user_ip": "10.10.70.134",
"sub_orders": [{
"mer_sub_reference_id": "0115172540747102",
"trans_code": "03223010",
"amount": {
"total": "0.05",
"currency": "CNY"
},
"is_customs": "False",
"invoice_id": "123456"
},
{
"trans_code": "01122030",
"amount": {
"total": "0.05",
"currency": "CNY"
},
"is_customs": "true",
"invoice_id": "123456",
"items": [{
"mer_item_id": "0115172540748103",
"type": "FOOD",
"name": "banana",
"quantity": "2",
"description": "banana",
"amount": {
"total": "0.05",
"currency": "CNY"
}
}]
}],
"sub_mer_id": "umfsubmer001"
},
"notify_url": "http://www.baidu.com"
}'
## Response data:
'{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"payment": {
"state": "WAIT_BUYER_PAY",
"notify_url": "http://www.baidu.com",
"payer": {
"bank_code": "SPDB",
"external_customer_id": "000000",
"payment_method": "DEBIT_CARD",
"payer_info": {
"bank_card": {
"number": "lAfy3SdcVDzQxeT4hNWVmdcbkeP7eyt+Z8weIoeSMi2ASRETlnuho84qWZJ6ndeTKB/pqwa+AERPoPQ9inqp1oExWEiWDxkyulsYTb8GRc+LwKlWwdGv6EhOwDJ3+zOi3yDMnlHOZVdmURQOokNg7qXlMUDCdrLyVO0boqu9Y3Q=",
"cvv2": "",
"valid_date": "",
"citizen_id_number": "q0Cs9uvO1D3rW1u6tlqp+kFVtIKPhUa0iMHbLEP+zXUhBjcfc3v36TcwEqOPWSPabnt6Tf+MsyqWgndSl7d0mc/jXx2jVbhn6/QD9szEJCvpMiPaS9/WQ2MZ+N4Pj2hmR3bLyDsSfqyKgWwF+obP4qKgcgfcxVUOLWTrOSVhecE=",
"phone": "13552100000",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "k/f1h3Ilcxc3sF49ngJVy0pZxQHcJ8T/FGuc2UNH1PLLtDL/J97Hp9/FSGlN9Hdqq2jmLj07JGVxsRrcGJVnfpqL1F+4kPtN3MUOrGw6gWv4vHeqdS12WVmYgPvj8OxjBmfwNNf6rvjXQpNVKjp5ejgu+IdoqtAhfCp8Fk14qOI="
}
}
},
"order": {
"user_ip": "10.10.70.134",
"amount": {
"total": "0.1",
"currency": "CNY"
},
"sub_orders": [{
"mer_sub_reference_id": "0115172540747102",
"trans_code": "03223010",
"amount": {
"total": "0.05",
"currency": "CNY"
},
"invoice_id": "123456",
"is_customs": "False"
},
{
"mer_sub_reference_id": "0115172541660664",
"trans_code": "01122030",
"amount": {
"total": "0.05",
"currency": "CNY"
},
"invoice_id": "123456",
"is_customs": "true",
"items": [{
"amount": {
"total": "0.05",
"currency": "CNY"
},
"quantity": "2",
"mer_item_id": "0115172540748103",
"name": "banana",
"description": "banana",
"type": "FOOD"
}]
}],
"sub_mer_id": "umfsubmer001",
"mer_date": "20200115",
"expire_time": "2020-01-15 23:25:42.459",
"mer_reference_id": "0115172540746101",
"order_summary": "CrossBorderOrderSummary"
}
}
}'
请求
POST: /payments/payment/apply_sms
创建一个稍后或立即执行的支付单, 取决于付款类型.
此接口下单同时也会下发短信验证码.
在这个过程中, 商户发送银行卡信息, UMF(或者银行) 将向用户手机发送短信验证码. 短信验证码是完成支付过程参数的一部分.
下面的表格展示了UMF支持的支付类型, 所有的付款必须使用人民币支付，同时此接口仅支持B2CAPI人民币下单:
接口类型为SERVER_TO_SERVER时，支付方式如下：
| 支付方式（payment_method） | 描述 |
|---|---|
| CREDIT_CARD | 信用卡支付 |
| DEBIT_CARD | 借记卡支付 |
| 参数 | 描述 |
|---|---|
| payer | 对象. 支付信息. |
| order | 对象. 订单信息. 包含子订单. |
| notify_url | String. 商户服务器的url 接收支付结果. |
| risk_info | 反欺诈信息. 内容取决于商户和UMF之间的合同. |
响应:
响应结果包含meta信息和一个支付对象. 请参见右边的示例. 已创建的支付对象包含如下信息：
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| payment | 对象. 支付对象. |
3.42 银行卡确认支付(无paymentId)
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/verify_execute \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:a/1A+rSDh2EBPGgiqRcET1hNcUtPBjSjQOYZmkqLx1n+IPAeM2p5c29XkB64jMy0fHfzFaK/cCj3vvq/f+o2fqC+WsLWnby34ByxdH+sgTK+I+bkzEdvwD7S9NCWwdMxejwuhBu+HcUn7uLhYgeRdOXfLIH/aThssRoBMTcmeZc="
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"bank_code": "SPDB",
"payer_info": {
"bank_card": {
"number": "tbPIHQK0B7g+lG0IrIuafuMMasdfAfAM4OSDQ9ZtAILfVpdwEprwb20ROeYAKHy+Q/LC3ttP82HI7rpURiOjSe/aLZsNQG4HLdjS4k+vfnag+A3Xv4CJiuHo25GLr+KQmNbYZsUPUcaxSgyV4hhrF8gjq7LwMU2UoCtJsMH1jQ\u003d",
"citizen_id_number": "mHV2O8CI3kUmBOOqELVU3fsZStazH91lihKe3pA+WPC9ar1vH1slQKinOxw9MOJ/X1oVHaOCIsSg7LmZ1xrPiTVeAZrxOp1MasdasdKD0aVsifrFu31YnNUXrZLAgvsVc6U8bGqd2AthC5qt2bI1W0HYUKtYzcqKrs3YVqB0OhmE\u003d",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "NfMddH8zfsl+irz24D2JWDxM3J8bi6g1RMEZ5iwsdasKCMhshsYAUwq2j7YInbAZPLQlELd2r0hjZV3hwTddl4WA5Wq9umKkzZP8B17sosAWh09F6qDvivMh4QgGvPMFznyTgVmAVfCTgQ4scliGAtxTn33J5orirSaJkHIfa2s\u003d",
"phone": "13552100000",
"verify_code": "123456"
}
},
"external_customer_id": "000000"
},
"order": {
"mer_reference_id": "0115172540746101",
"mer_date": "20200115",
"if_sms": "Y"
}
}'
## Response data:
'{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"payment": {
"settle_date": "20200115",
"state": "TRADE_SUCCESS",
"execute_success_time": "2020-01-15T17:26:21+0800",
"payer": {
"bank_code": "SPDB",
"external_customer_id": "00000",
"payment_method": "DEBIT_CARD",
"payer_info": {
"bank_card": {
"number": "q1cmH403asdfasCFmuVoVMeCVbZ7RJrlWokNuFE7Oflgy5B+n36cLt+uBNh9F8fFZZGRsL6ArctJWwjl4T+WUOx1vcMIUEWvdzi5/cY/DIsLkvKdEb0M6GJdvnKaJGKAxNz5SFdHBbxodCfAbBu+/VX2nuF9EIaO/IsPRDw=",
"cvv2": "",
"valid_date": "",
"citizen_id_number": "ZcIAI5asdfasjYbUbIJginNYB1u9CMiWDiJalU9EY0NPEF7O9INAxEhKdRZvAFlIGbtiBxc9UQX18r57HuOeDCTV1+djvxsYUOMcOdSv/ZW5qlA4WBwPBukUtm47HEtb+1lJYcRDlT4y0jJN/6HFUuHWsu14gKfZIMxA40FI0=",
"phone": "13552105741",
"citizen_id_type": "IDENTITY_CARD",
"verify_code": "243256",
"payer_name": "bt1LLi5EO7WjCasdfaSQR7eIPqbhaavnbxFyBLJzX5sldaZqRlvuW+k0MR8gToSLOk+O7GPiiT43Fq3ibeIWPdzgspZxrs9V2PNSepURER5R2CfhPREIKG4xzqmozqEpDHq4KtgngAKhzHD4MGEVuSL/rqkPk095iRqh5fooHVQ="
},
"payer_agreement": {
"usr_busi_agreement_id": "UB201912191600500000000000000000",
"usr_pay_agreement_id": "P2020011517261900000000000000000"
}
}
},
"order": {
"if_sms": "Y",
"mer_date": "20200115",
"mer_reference_id": "0115172540746101"
}
}
}'
此接口响应成功，并同时 payer_agreement 实体中支付协议号及业务协议号成功返回，即视为签约成功，
处理完支付单,并且交易完成后. 资金从用户账户转移到UMF商户账户.
要执行支付单, 在请求的JSON body中包含一个payer对象.
处理结果不会立即返回. 商户想要获取结果有两种方式，方式如下:
– 查询付款结果. 支付成功的状态为"TRADE_SUCCESS". – 等待UMF通知. 商户需要开发http(s)服务. 支付产生结果时,UMF请求到这个服务.
请求
POST: /payments/payment/verify_execute
调用此接口需调用(下单).
参数
| 参数 | 描述 |
|---|---|
| payer | 对象. 支付信息. 一些参数应该用UMF公钥加密. 参见payer对象的描述. 若支付类型是银行卡或者信用卡, payer对象应该包含手机验证码. |
响应
响应结果包含payment对象. 银行卡信息不将返回, 例如card number, cvv2, citizen_id, 等等.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| payment | 对象. 支付对象. |
3.43 协议下单接口（无paymentId）
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/apply_sms \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:a/1A+rSDh2EBPGgiqRcET1hNcUtPBjSjQOYZmkqLx1n+IPAeM2p5c29XkB64jMy0fHfzFaK/cCj3vvq/f+o2fqC+WsLWnby34ByxdH+sgTK+I+bkzEdvwD7S9NCWwdMxejwuhBu+HcUn7uLhYgeRdOXfLIH/aThssRoBMTcmeZc="
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"bank_code": "BOC",
"payer_info": {
"payer_agreement": {
"usr_pay_agreement_id": "P2018080109324500000000000000000",
"usr_busi_agreement_id": "UB201912191600500000000000000000"
}
},
"external_customer_id": "000000"
},
"order": {
"mer_reference_id": "0109155242150101",
"mer_date": "20200109",
"amount": {
"total": "0.1",
"currency": "CNY"
},
"order_summary": "CrossBorderOrderSummary",
"expire_time": "360",
"user_ip": "10.10.70.134",
"sub_orders": [{
"mer_sub_reference_id": "0109155242151102",
"trans_code": "03223010",
"amount": {
"total": "0.05",
"currency": "CNY"
},
"is_customs": "False",
"invoice_id": "123456"
},
{
"trans_code": "01122030",
"amount": {
"total": "0.05",
"currency": "CNY"
},
"is_customs": "true",
"invoice_id": "123456",
"items": [{
"mer_item_id": "0109155242152103",
"type": "FOOD",
"name": "banana",
"quantity": "2",
"description": "banana",
"amount": {
"total": "0.05",
"currency": "CNY"
}
}]
}],
"sub_mer_id": "umfsubmer001"
},
"notify_url": "http://www.baidu.com"
}'
## Response data:
'{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"payment": {
"state": "WAIT_BUYER_PAY",
"notify_url": "http://www.baidu.com",
"payer": {
"bank_code": "BOC",
"external_customer_id": "00000000",
"payment_method": "DEBIT_CARD",
"payer_info": {
"bank_card": {
"number": "R/ba4olTSwICVOmNUnfYh9rvi3k3DJqA3I2Wli4Y/65LdzSUBjDntj5lNf2u8ySA8lFLn0jNZY4fXBosM+gRorF1/xLpnEhnY8mTemxNI/nqh4AUsshIX385qrgs1dcEP4sCFUDFDgc2c+QrhGuHLvuykfcPHYutXD3pizhG4Vs=",
"cvv2": "",
"valid_date": "",
"citizen_id_number": "TUwhYj20NvmYkkpsWPOFo/2rALutVrLGrW3Lul1qo/YNH4PpmXR7QXcFBUMwq740wKK72ZNH7wgsabI9ldpvyil/iN+FsMFnRWCb02kFrEtsz+fvUhlr8VOWKAWjPcSRNbygE4BfE53nNafs+czvI2aPa3yswnLGkTy1hDgICFs=",
"phone": "15750000000",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "hFIhbyMPFyyaqVQL3qmpp+jFYrAHbCi71CzPverbgTrCsQICBNHavskwlVXPCg0ykFDNBUzqkQwEoQbDWFhPOhzaOWNVbJngKUyIqcevlZrHcBfGk8nCuKg+AHUgOeiFyIycuxgxtkw+LfTVKnd8Ipx4KUMj/ceoSV1MYw5gN8Q="
},
"payer_agreement": {
"usr_busi_agreement_id": "UB201912191600500000000000000000",
"usr_pay_agreement_id": "P2018080109324500000000000000000"
}
}
},
"order": {
"user_ip": "10.10.70.134",
"amount": {
"total": "0.1",
"currency": "CNY"
},
"sub_orders": [{
"mer_sub_reference_id": "0109155242151102",
"trans_code": "03223010",
"amount": {
"total": "0.05",
"currency": "CNY"
},
"invoice_id": "123456",
"is_customs": "False"
},
{
"mer_sub_reference_id": "0109155242718534",
"trans_code": "01122030",
"amount": {
"total": "0.05",
"currency": "CNY"
},
"invoice_id": "123456",
"is_customs": "true",
"items": [{
"amount": {
"total": "0.05",
"currency": "CNY"
},
"quantity": "2",
"mer_item_id": "0109155242152103",
"name": "banana",
"description": "banana",
"type": "FOOD"
}]
}],
"sub_mer_id": "umfsubmer001",
"mer_date": "20200109",
"expire_time": "2020-01-09 21:52:43.442",
"mer_reference_id": "0109155242150101",
"order_summary": "CrossBorderOrderSummary"
}
}
}'
请求
POST: /payments/payment/apply_sms
创建一个稍后或立即执行的支付单, 取决于付款类型.
此接口下单同时也会下发短信验证码.
在这个过程中, 商户发送银行卡信息, UMF(或者银行) 将向用户手机发送短信验证码. 短信验证码是完成支付过程参数的一部分.
此接口对比(下单),是使用用户的协议信息下单，而无需使用真实信息。
下面的表格展示了UMF支持的支付类型, 所有的付款必须使用人民币支付，同时此接口仅支持B2CAPI人民币下单:
接口类型为SERVER_TO_SERVER时，支付方式如下：
| 支付方式（payment_method） | 描述 |
|---|---|
| CREDIT_CARD | 信用卡支付 |
| DEBIT_CARD | 借记卡支付 |
| 参数 | 描述 |
|---|---|
| payer | 对象. 支付信息. |
| order | 对象. 订单信息. 包含子订单. |
| notify_url | String. 商户服务器的url 接收支付结果. |
| risk_info | 反欺诈信息. 内容取决于商户和UMF之间的合同. |
响应:
响应结果包含meta信息和一个支付对象. 请参见右边的示例. 已创建的支付对象包含如下信息：
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| payment | 对象. 支付对象. |
3.44 协议确认支付(无paymentId)
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/verify_execute \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:a/1A+rSDh2EBPGgiqRcET1hNcUtPBjSjQOYZmkqLx1n+IPAeM2p5c29XkB64jMy0fHfzFaK/cCj3vvq/f+o2fqC+WsLWnby34ByxdH+sgTK+I+bkzEdvwD7S9NCWwdMxejwuhBu+HcUn7uLhYgeRdOXfLIH/aThssRoBMTcmeZc="
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"bank_code": "BOC",
"payer_info": {
"payer_agreement": {
"usr_pay_agreement_id": "P2018080109324500000000041329281",
"usr_busi_agreement_id": "UB201912191600500000000036393393",
"verify_code": "596253"
}
},
"external_customer_id": "1980655668"
},
"order": {
"mer_reference_id": "0109155242150101",
"mer_date": "20200109",
"if_sms": "Y"
}
}'
## Response data:
'{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"payment": {
"settle_date": "20200109",
"state": "TRADE_SUCCESS",
"execute_success_time": "2020-01-09T15:53:28+0800",
"payer": {
"bank_code": "BOC",
"external_customer_id": "000000",
"payment_method": "DEBIT_CARD",
"payer_info": {
"bank_card": {
"number": "Wf2ht55DvLQ7tZZiIyiQwG9eb8eQt7cFhZba15RB299ZGdwf/G/eYv4ND2OCmE9i9sFLPBb/IJq8cGz77lNh53PxU+ug+LWZOp5lXJgp1ZFIqI4TtoB0dm1L3CB6/+3KrGnP+mt2e5SKt9HE74AEmISVKTSQN8sdQaeIQj0nmbk=",
"cvv2": "",
"valid_date": "",
"citizen_id_number": "S9pUiFh1MNProtPQ+pQIEszrfVLxtLJPcz73uMMDP2ZhRReBqFE7QQ6oX1oQZ6qmkAeVQMInFVGklXGZvNmbzQk4GCFS2lc/IGtIRrVYn1tVgEuVRNlHyOBrB6s/7oZhB+SKeBv0bPr1jdb9wrzrTlkW0m7+7mpp5i5iMSmoYnA=",
"phone": "15754314122",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "cwNxeflbjZe4Eeoo2mVsmJwxy26dKIUnD7VfR5XHuGs+bLHCPWRBhDVejJ4dpQt2M/BUD2+2l2KwUagYXMAaTjazYF3cKphn0jtVkhJU+LaV8blegkIbOPaKZrZKS25tpXU1KSjSRgtLhcAGEPKRwl/slNPyFfKvZaxGkuZfmtY="
},
"payer_agreement": {
"usr_busi_agreement_id": "UB201912191600500000000000000000",
"usr_pay_agreement_id": "P2018080109324500000000000000000"
}
}
},
"order": {
"if_sms": "Y",
"mer_date": "20200109",
"mer_reference_id": "0109155242150101"
}
}
}'
处理完支付单,并且交易完成后. 资金从用户账户转移到UMF商户账户.
要执行支付单, 在请求的JSON body中包含一个payer对象.
处理结果不会立即返回. 商户想要获取结果有两种方式，方式如下:
– 查询付款结果. 支付成功的状态为"TRADE_SUCCESS". – 等待UMF通知. 商户需要开发http(s)服务. 支付产生结果时,UMF请求到这个服务.
请求
POST: /payments/payment/verify_execute
调用此接口需调用(下单).
参数
| 参数 | 描述 |
|---|---|
| payer | 对象. 支付信息. 一些参数应该用UMF公钥加密. 参见payer对象的描述. 若支付类型是银行卡或者信用卡, payer对象应该包含手机验证码. |
响应
响应结果包含payment对象.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| payment | 对象. 支付对象. |
3.45 下单及确认支付(无paymentId)
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/verify_execute \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:a/1A+rSDh2EBPGgiqRcET1hNcUtPBjSjQOYZmkqLx1n+IPAeM2p5c29XkB64jMy0fHfzFaK/cCj3vvq/f+o2fqC+WsLWnby34ByxdH+sgTK+I+bkzEdvwD7S9NCWwdMxejwuhBu+HcUn7uLhYgeRdOXfLIH/aThssRoBMTcmeZc="
-d '{
"payer": {
"payment_method": "DEBIT_CARD",
"bank_code": "BOC",
"payer_info": {
"payer_agreement": {
"usr_pay_agreement_id": "P2018080109324500000000000000000",
"usr_busi_agreement_id": "UB201912191600500000000000000000"
}
},
"external_customer_id": "000000"
},
"order": {
"mer_reference_id": "0109155431688101",
"mer_date": "20200109",
"amount": {
"total": "0.1",
"currency": "CNY"
},
"order_summary": "CrossBorderOrderSummary",
"expire_time": "360",
"user_ip": "10.10.70.134",
"sub_orders": [{
"mer_sub_reference_id": "0109155431689102",
"trans_code": "03223010",
"amount": {
"total": "0.05",
"currency": "CNY"
},
"is_customs": "False",
"invoice_id": "123456"
},
{
"trans_code": "01122030",
"amount": {
"total": "0.05",
"currency": "CNY"
},
"is_customs": "true",
"invoice_id": "123456",
"items": [{
"mer_item_id": "0109155431689103",
"type": "FOOD",
"name": "banana",
"quantity": "2",
"description": "banana",
"amount": {
"total": "0.05",
"currency": "CNY"
}
}]
}],
"sub_mer_id": "umfsubmer001",
"if_sms": "N"
},
"notify_url": "http://www.baidu.com"
}'
## Response data:
'{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"payment": {
"settle_date": "20200115",
"state": "TRADE_SUCCESS",
"execute_success_time": "2020-01-15T17:26:21+0800",
"payer": {
"bank_code": "SPDB",
"external_customer_id": "00000",
"payment_method": "DEBIT_CARD",
"payer_info": {
"bank_card": {
"number": "q1cmH403asdfasCFmuVoVMeCVbZ7RJrlWokNuasdfgy5B+n36cLt+uBNh9F8fFZZGRsL6ArctJWwjl4T+WUOx1vcMIUEWvdzi5/cY/DIsLkvKdEb0M6GJdvnKaJGKAxNz5SFdHBbxodCfAbBu+/VX2nuF9EIaO/IsPRDw=",
"cvv2": "",
"valid_date": "",
"citizen_id_number": "ZcIAI5asdfasjYbUbIJginNasdJalU9EY0NPEF7O9INAxEhKdRZvAFlIGbtiBxc9UQX18r57HuOeDCTV1+djvxsYUOMcOdSv/ZW5qlA4WBwPBukUtm47HEtb+1lJYcRDlT4y0jJN/6HFUuHWsu14gKfZIMxA40FI0=",
"phone": "13552000000",
"citizen_id_type": "IDENTITY_CARD",
"verify_code": "243256",
"payer_name": "bt1LLi5EO7WjCasdfaSQR7eIPqbhasdfxFyBLJzX5sldaZqRlvuW+k0MR8gToSLOk+O7GPiiT43Fq3ibeIWPdzgspZxrs9V2PNSepURER5R2CfhPREIKG4xzqmozqEpDHq4KtgngAKhzHD4MGEVuSL/rqkPk095iRqh5fooHVQ="
},
"payer_agreement": {
"usr_busi_agreement_id": "UB201912191600500000000000000000",
"usr_pay_agreement_id": "P2020011517261900000000000000000"
}
}
},
"order": {
"if_sms": "Y",
"mer_date": "20200115",
"mer_reference_id": "0115172540746101"
}
}
}'
创建一个稍后或立即执行的支付单, 取决于付款类型.
在这个过程中, 商户发送协议信息, 联动在校验协议信息后完成交易.
处理完支付单,并且交易完成后. 资金从用户账户转移到UMF商户账户.
要执行支付单, 在请求的JSON body中包含一个payer对象.
处理结果不会立即返回. 商户想要获取结果有两种方式，方式如下:
– 查询付款结果. 支付成功的状态为"TRADE_SUCCESS". – 等待UMF通知. 商户需要开发http(s)服务. 支付产生结果时,UMF请求到这个服务.
请求
POST: /payments/payment/verify_execute
下面的表格展示了UMF支持的支付类型, 所有的付款必须使用人民币支付，同时此接口仅支持B2CAPI人民币支付:
接口类型为SERVER_TO_SERVER时，支付方式如下：
| 支付方式（payment_method） | 描述 |
|---|---|
| CREDIT_CARD | 信用卡支付 |
| DEBIT_CARD | 借记卡支付 |
| 参数 | 描述 |
|---|---|
| payer | 对象. 支付信息. |
| order | 对象. 订单信息. 包含子订单. |
| notify_url | String. 商户服务器的url 接收支付结果. |
| risk_info | 反欺诈信息. 内容取决于商户和UMF之间的合同. |
响应
响应结果包含payment对象.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| payment | 对象. 支付对象. |
3.46 订单查询(无paymentId)
## 请求数据:
$ curl -s -X POST https://fxus.soopay.net/cberest/v1/payments/payment/query \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"order": {
"mer_reference_id": "0109104413476101",
"mer_date": "20200302"
}
}'
## 响应:
'{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"payment": {
"settle_date": "20200302",
"state": "TRADE_SUCCESS",
"execute_success_time": "20200302",
"payer": {
"payment_method": "DEBIT_CARD"
},
"order": {
"user_ip": "",
"amount": {
"total": "0.03",
"exchange_rate": {
"rate": "1.0000",
"currency": "CNY"
},
"currency": "CNY",
"total_cny": "0.03"
},
"mer_date": "20200302",
"verify_department": "UnionPay",
"verify_department_pay_trace": "11111110000098604439080301907",
"mer_reference_id": "0109104413476101"
}
}
}'
POST: /payments/payment/query
商户随时可以请求该url. UMF将返回订单对象. 若state是"TRADE_SUCCESS", 则支付成功.
请求
| 参数 | 描述 |
|---|---|
| order | 对象. 订单信息 |
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| payment | 对象. 支付对象. |
3.47 异步退费（无paymentId）
## request:
$ curl -s -X POST https://fxus.soopay.net/cberest/v1/payments/payment/asy_refund \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"refund_info": {
"mer_reference_id": "0113161033042101",
"mer_date": "20200113",
"amount": {
"total": "1",
"currency": "CNY"
},
"sub_orders": [{
"mer_sub_reference_id": "0113161033042102",
"trans_code": "03223010",
"amount": {
"total": "1",
"currency": "CNY"
}
}]
},
"notify_url": "http://www.baidu.com",
"mer_refund_id": "1134592475"
}'
## 响应:
'{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"asy_refund": {
"mer_refund_id": "1134592475",
"refund_info": {
"amount": {
"total": "1",
"currency": "CNY"
},
"sub_orders": [{
"mer_sub_reference_id": "0113161033042102",
"trans_code": "03223010",
"amount": {
"total": "1",
"currency": "CNY"
}
}],
"mer_date": "20200113",
"mer_reference_id": "0113161033042101"
}
}
}'
请求
POST:/payments/payment/asy_refund
该请求创建并发送一个退款对象. 响应结果是UMF创建的退款对象.
UMF支持全额或部分退款. 部分退款可以多次执行.
退款和付款的货币必须一致, 退款金额一定不能大于付款总金额.
请求
| 参数 | 描述 |
|---|---|
| asy_refund | 对象. 退款对象. 应该输入订单、金额和nofify_url. |
响应
响应结果包含支付对象. 退款对象包含state.
若state是"REFUND_SUCCESS", 表示交易完成，退款成功. 若state是"REFUND_PROCESS", 表示交易正在处理, 交易完成后, UMF 将通知商户. 商户也可以查询退款状态 查询退款
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| asy_refund | 对象. 退款对象. |
3.48 异步退费查询(无paymentId)
## 请求数据:
$ curl -s -X POST https://fxus.soopay.net/cberest/v1/payments/refund/refund_query \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"mer_refund_id": "1636237315"
}'
## 响应:
'{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"asy_refund": {
"mer_refund_id": "1636237315",
"state": "REFUND_PROCESS"
}
}'
POST: /payments/refund/refund_query
此接口仅支持(异步退款)的查询。
商户随时可以请求该url. UMF将返回退款对象. 若state是"REFUND_SUCCESS", 则退款成功.
请求
| 参数 | 描述 |
|---|---|
| asy_refund | 对象. 退款对象. 应该输入订单、金额和nofify_url. |
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| asy_refund | 对象. 退款对象. |
3.49 异步退费异步通知
## Notification request(modify the follow url address to get demo notification):
curl -s -X POST https://dev.restdemo.umftech.com/restdemo/demo/notifyResultRest \
-H "Content-Type:application/json" \
-H "Signature:U1TE7d24ZeWbzbsNl63/140jzq83BplOQ5JZxQw/elEjO/fNp7L0dpeCiHdgGsLFou/O6Eh8VtH+/fxwmpejmpQa1rpjR2XaI82SGNwEPGvATYquS5UI6rFyiG8BdiRjBxLWcH+yOa6Kw6MsCSsJKmq+kJrRf2Iiu/jYLxJAvh8=" \
-d '{"meta": {"ret_code": "0000","ret_msg": ["SUCCESS"]},"refund": {"id": "REFUND_KRCC2V2NKMZDAMJZGEZDENZUGAZDMMJQG4ZC2NJRHEYTEMBRHEYTEMRXCM","refund_info": {"mer_reference_id": "WMS2019122740261072","mer_date": "20191227","amount": {"total": "0.02","currency": "CNY","total_cny": "2"}},"state": "REFUND_SUCCESS"},"links": [{"href": "https://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4TCMRSG4YTGNBTG42DCMBSGUZDAMJZGEZDEN3Y","ref": "parent_payment","method": "GET"},{"href": "https://fx.soopay.net/cberest/v1/payments/refund/REFUND_KRCC2V2NKMZDAMJZGEZDENZUGAZDMMJQG4ZC2NJRHEYTEMBRHEYTEMRXCM","ref": "self","method": "GET"}]}'
## Notification data:
{
"meta": {
"ret_code": "0000",
"ret_msg": ["SUCCESS"]
},
"refund": {
"id": "REFUND_KRCC2V2NKMZDAMJZGEZDENZUGAZDMMJQG4ZC2NJRHEYTEMBRHEYTEMRXCM",
"refund_info": {
"mer_reference_id": "WMS2019122740261072",
"mer_date": "20191227",
"amount": {
"total": "0.02",
"currency": "CNY",
"total_cny": "2"
}
},
"state": "REFUND_SUCCESS"
},
"links": [{
"href": "https://fx.soopay.net/cberest/v1/payments/payment/PAY_GY4TCMRSG4YTGNBTG42DCMBSGUZDAMJZGEZDEN3Y",
"ref": "parent_payment",
"method": "GET"
},
{
"href": "https://fx.soopay.net/cberest/v1/payments/refund/REFUND_KRCC2V2NKMZDAMJZGEZDENZUGAZDMMJQG4ZC2NJRHEYTEMBRHEYTEMRXCM",
"ref": "self",
"method": "GET"
}]
}
处理完商户的付款请求数据后, UMF将支付结果回调商户服务.
接收回调后商户将作出响应.
请求
UMF调用商户提供的服务. 服务的url即为商户配置的服务url.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共信息. |
| refund | 对象. 付款对象. |
响应
商户发送到UMF的响应结果.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应信息. |
3.50 报关（无paymentId）
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/apply_customs \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"sub_order": {
"mer_sub_reference_id": "0115144722428302",
"items": [{
"mer_item_id": "0115144721498103"
}]
},
"customs_id": "HZHG",
"mer_customs_code": "123456",
"freight_amount": {
"total": "0.00",
"currency": "CNY",
"total_cny": "0.00"
},
"tax_amount": {
"total": "0.00",
"currency": "CNY",
"total_cny": "0.00"
},
"sub_order_amount": {
"total": "0.05",
"currency": "CNY",
"total_cny": "0.05"
},
"ec_plat_id": "123456",
"notify_url": "http://120.26.99.183:8081/api_callback/umGatewayPaymentDeclareNotify",
"mer_date": "20200115"
}'
//Response
'{
"customs_declaration": {
"tax_amount": {
"total": "0.00",
"currency": "CNY",
"total_cny": "0.00"
},
"freight_amount": {
"total": "0.00",
"currency": "CNY",
"total_cny": "0.00"
},
"mer_date": "20200115",
"customs_clearance_date": "",
"verify_department": "UnionPay",
"mer_customs_code": "123456",
"sub_order": {
"mer_sub_reference_id": "0115144722428302",
"sub_customs_trace": "0115144723404800",
"items": [{
"mer_item_id": "0115144721498103"
}]
},
"ec_plat_id": "123456",
"verify_department_pay_trace": "2020011500000097452123380300405",
"sub_order_amount": {
"total": "0.05",
"currency": "CNY",
"total_cny": "0.05"
},
"notify_url": "http://120.26.99.183:8081/api_callback/umGatewayPaymentDeclareNotify",
"customs_id": "HZHG"
},
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
}
}'
请求
POST: /payments/payment/apply_customs
该接口是可选的. 当商户需要UMF将支付信息提交到海关时, 该接口被调用. 一旦商户请求该url, 支付信息将发送给海关.
在订购后一个月内,商户向UMF提供子订单数据,在收到订单后,UMF将子订单数据更新到海关系统.
| 参数 | 描述 |
|---|---|
| customs_declarations | 对象，报关信息。 |
响应
响应结果包含一个报关对象和meta信息.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共部分. |
| customs_declarations | 对象. 海关信息. |
3.51 报关状态查询（无paymentId）
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/customs_query \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-d '{
"sub_order": {
"mer_sub_reference_id": "0521174444066101"
},
"mer_date": "20191208",
"is_customs": "TRUE"
}'
## Response data:
'{
"customs_declaration": {
"pay_trace": "6521174445724001",
"mer_date": "20191208",
"customs_clearance_date": "20190614",
"state": "SUCCESS",
"sub_order": {
"mer_sub_reference_id": "0521174444066101"
},
"is_customs": "TRUE",
"customs_id": "BJZS"
},
"meta": {
"ret_code": "0000",
"ret_msg": "交易成功"
}
}'
请求
POST: /payments/payment/customs_query
is_customs默认为非独立报关,独立报关传TRUE
| 参数 | 描述 |
|---|---|
| customs_declarations | 对象，报关信息。 |
响应
| Parameter | Description |
|---|---|
| meta | 对象. 响应公共部分. |
| customs_declarations | 对象. 海关信息. |
3.52 报国检（无paymentId）
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/payment/apply_to_ciq \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"sub_order": {
"mer_sub_reference_id": "0115144722428302"
},
"mer_date": "20200115",
"ciq_code": "GJHP",
"plat_supplier_no": "56546546"
}'
//Response
'{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"ciq_declarations": {
"mer_date": "20200115",
"sub_order": {
"mer_sub_reference_id": "0115144722428302",
"sub_ciq_trace": "0115144723404800"
},
"ciq_clearance_date": "20200115",
"ciq_code": "GJHP",
"plat_supplier_no": "56546546"
}
}'
请求
POST: /payments/payment/apply_to_ciq
该接口是可选的. 当商户需要UMF将支付信息提交到国检时, 该接口被调用. 一旦商户请求该url, 支付信息将发送给国检.
在订购后一个月内,商户向UMF提供子订单数据,在收到订单后,UMF将子订单数据更新到国检系统.
| 参数 | 描述 |
|---|---|
| national_inspection | 对象，报关信息。 |
响应
响应结果包含一个报关对象和meta信息.
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共部分. |
| national_inspection | 对象. 国检信息. |
3.53 报国检状态查询（无paymentId）
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/payments/ciq_declarations \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBXo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"sub_order": {
"mer_sub_reference_id": "0115144722428302"
},
"mer_date": "20200115"
}'
## Response data:
'{
"meta": {
"ret_msg": "该笔单未报送",
"ret_code": "00280045"
}
}'
请求
POST: /payments/ciq_declarations
此接口需要先调用(报国检).
| 参数 | 描述 |
|---|---|
| national_inspection | 对象，报关信息。 |
响应
| Parameter | Description |
|---|---|
| meta | 对象. 响应公共部分. |
| national_inspection | 对象. 海关信息. |
3.54 海关/国检重推（无paymentId）
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/declare_again \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/1V1FnalfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"mer_reference_id": "0115144722428302",
"declare_type": "0"
}'
## Response data:
'{
"declare_again": {
"declare_type": "0",
"mer_reference_id": "0115144722428302"
},
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
}
}'
请求
POST: /declare_again
如清关时出现支付单不存在，且联动侧支付人身份信息通过，商户可调动该接口，UMF会重新上送此笔数据
请求
| Parameter | Description |
|---|---|
| declare_again | 对象. 重推信息. |
响应
| Parameter | Description |
|---|---|
| meta | 对象. 响应公共部分. |
| declare_again | 对象. 海关信息. |
3.55 签约请求及获取短信验证码
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/bind/get_smscode \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"payer_info": {
"bank_card": {
"number": "eKjGbVVkltLSYcLMT2y72R4RhLCam4rw/mMp1f/S8k6v/1TpCDD1NIXC65ATegQBX1EGVyZ8prDtP4M67qp7yFUdLjgeh8NrVef/bveWe3VIx9adwBNbET1ZbJMJRbQKmKQBU9Rzl4dK33JrU9Bf8to\u003d",
"citizen_id_number": "drnnZn9Nba+d7kAhwfoNApJPSaxPgjfe+wTE0EfgfQwyk8kjIkInuEG0r+z3te9z+vb7LKQpapLI0PfrMLB0yMsF9aeUgq+BVS/n8RE0sB49sOwsT4aFlv39F8Yi7ahbmtykuexmy7r0erK4CIC4FqwgGj2ynB5tug8Spuw\u003d",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "ehXTBVxnobQtvns3Su6PRidZ3KAHeWwfqUo7W4JDReCueQC5hc7RSuelATk7Ai+RJ00mtah5BPS335WjlJZt/QNvGJCUlGNWBJDZO1tYm+u4XmRPbKzdy5/D50SsbBv2j4ZJ5n8uU1qZMPhSYZ9LNkbIO0eXivr63t8fJwrUk\u003d",
"valid_date": "",
"cvv2": "",
"phone": "15700000000"
}
},
"external_customer_id": "123456"
}'
## Response data:
'{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payer_info": {
"bank_card": {
"number": "eKjGbVVkltLSYcLMT2y72R4RhLCam4rw/mMp1f/S8k6v/1TpCDD1NIXC65ATeX1EGVyZ8prDtP4M67qp7yFUdLjgeh8NrVef/bveWe3VIx9adwBNbET1ZbJMJRbQKmKQBU9Rzl4dK33JrU9Bf8to\u003d",
"citizen_id_number": "drnnZn9Nba+d7kAhwfoNApJPSaxPgjfe+wTE0EfgfQwsvyk8kInuEG0r+z3te9z+vb7LKQpapLI0PfrMLB0yMsF9aeUgq+BVS/n8RE0sB49sOwsT4aFlv39F8Yi7ahbmtykuexmy7r0erK4CIC4FqwgGj2yn3tug8Spuw\u003d",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "ehXTBVxnobQtvns3Su6PRidZ3KAHeWwfqUo7W4JDReCueQC5hc7SuelATk7Ai+RJ00mtah5BPS335WjlJZt/QNvGJCUlGNWBJDZO1tYm+u4XmRPbKzdy5/D50SsbBv2j4ZJ5n8uU1qZMPhSYZ9LNkbIO0eXivr63t8fJwrUk\u003d",
"valid_date": "",
"cvv2": "",
"phone": "15700000000"
}
},
"external_customer_id": "123456"
}'
请求
POST: /bind/get_smscode
调用该接口，请求银行下发短信完成借记卡/信用卡绑卡
请求
| Parameter | Description |
|---|---|
| payer | 对象. 付款信息. |
响应
| Parameter | Description |
|---|---|
| meta | 对象. 响应公共部分. |
| payer | 对象. 付款信息. |
3.56 签约确认
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/bind/get_smscode \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/U82xlQUFi8ua/3kv0o7eTVbKLDr1LacEFWFWWy3RpXFFa57SA=" \
-d '{
"payer_info": {
"bank_card": {
"number": "eKjGbVVkltLSYcLMT2y72R4RhLCam4rw/mMp1f/S8k6v/1TpCDD1NIXC65ATegQBX1EGVyZ8prDtP4M67qp7yFUdLjgeh8NrVef/bveWe3VIx9adwBNbET1ZbJMJRbQKmKQBU9Rzl4dK33JrU9Bf8to\u003d",
"citizen_id_number": "drnnZn9Nba+d7kAhwfoNApJPSaxPgjfe+wTE0EfgfQwyk8kjIkInuEG0r+z3te9z+vb7LKQpapLI0PfrMLB0yMsF9aeUgq+BVS/n8RE0sB49sOwsT4aFlv39F8Yi7ahbmtykuexmy7r0erK4CIC4FqwgGj2ynB5tug8Spuw\u003d",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "ehXTBVxnobQtvns3Su6PRidZ3KAHeWwfqUo7W4JDReCueQC5hc7RSuelATk7Ai+RJ00mtah5BPS335WjlJZt/QNvGJCUlGNWBJDZO1tYm+u4XmRPbKzdy5/D50SsbBv2j4ZJ5n8uU1qZMPhSYZ9LNkbIO0eXivr63t8fJwrUk\u003d",
"valid_date": "",
"cvv2": "",
"phone": "15700000000",
"verify_code": "666666"
}
},
"external_customer_id": "123456"
}'
## Response data:
'{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payer_info": {
"bank_card": {
"number": "eKjGbVVkltLSYcLMT2y72R4RhLCam4rw/mMp1f/S8k6v/1TpCDD1NIXC65ATeX1EGVyZ8prDtP4M67qp7yFUdLjgeh8NrVef/bveWe3VIx9adwBNbET1ZbJMJRbQKmKQBU9Rzl4dK33JrU9Bf8to\u003d",
"citizen_id_number": "drnnZn9Nba+d7kAhwfoNApJPSaxPgjfe+wTE0EfgfQwsvyk8kInuEG0r+z3te9z+vb7LKQpapLI0PfrMLB0yMsF9aeUgq+BVS/n8RE0sB49sOwsT4aFlv39F8Yi7ahbmtykuexmy7r0erK4CIC4FqwgGj2yn3tug8Spuw\u003d",
"citizen_id_type": "IDENTITY_CARD",
"payer_name": "ehXTBVxnobQtvns3Su6PRidZ3KAHeWwfqUo7W4JDReCueQC5hc7SuelATk7Ai+RJ00mtah5BPS335WjlJZt/QNvGJCUlGNWBJDZO1tYm+u4XmRPbKzdy5/D50SsbBv2j4ZJ5n8uU1qZMPhSYZ9LNkbIO0eXivr63t8fJwrUk\u003d",
"valid_date": "",
"cvv2": "",
"phone": "15700000000",
"verify_code": "666666"
},
"payer_agreement": {
"usr_busi_agreement_id": "UB2018112614505ddddds00033862892",
"usr_pay_agreement_id": "P2018080109dddddsd00000041329281"
}
},
"external_customer_id": "123456"
}'
请求
POST: /bind/get_contract
调用该接口，上送银行短信验证码，完成签约绑卡
请求
| Parameter | Description |
|---|---|
| payer | 对象. 付款信息. |
响应
| Parameter | Description |
|---|---|
| meta | 对象. 响应公共部分. |
| payer | 对象. 付款信息. |
3.57 银行协议解绑
$ curl -s -X GET https://fx.soopay.net/cberest/v1/bank_agreement/unbind \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM=" \
{
"external_customer_id": "911886886911",
"payer_agreements": [{
"usr_pay_agreement_id": "P2018080109324500000000041329281",
"usr_busi_agreement_id": "UB201811261450560000000033862892"
}]
}
## Response data:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
}
}
请求
POST: /bank_agreement/unbind
此解绑接口会解除用户在联动侧和银行侧的支付协议，同时该用户在联动侧的所有商户下的支付协议，请谨慎调用此接口!并在用户调用此接口时，告知用户可能造成的影响!!!
| 参数 | 描述 |
|---|---|
| payer_agreements | 对象. 响应公共信息. |
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共信息. |
3.58 更新物流单号
$ curl -s -X GET https://fx.soopay.net/cberest/v1/payments/payment/PAY_GYYDANZQHAYTMMRYHEZDSOJXGMZDAMRQGA3TAOGC/update_express_info \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM=" \
{
"order": {
"sub_orders": [{
"mer_sub_reference_id": "0709095938921001",
"tracking_number": "顺丰 11313258946251003256"
},
{
"mer_sub_reference_id": "0709095938921002",
"tracking_number": "中通 1131325845256252623256"
}]
}
}
## Response data:
{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"payment": {
"id": "PAY_GYYDANZQHEYDSNJZHEZTSOJXGQZDAMRQGA3TAOM3",
"order": {
"sub_orders": [{
"mer_sub_reference_id": "0709095938921001",
"tracking_number": "顺丰 11313258946251003256"
},
{
"mer_sub_reference_id": "0709095938921002",
"tracking_number": "中通 1131325845256252623256"
}]
}
},
"links": [{
"ref": "parent_payment",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GYYDANZQHEYDSNJZHEZTSOJXGQZDAMRQGA3TAOM3"
}]
}
只有货物类型交易,在下单结束后会返回该link
该link用于更新该笔货物交易的物流单号
（1）物流单号怎么传？ A:tracking_number长度为64位，格式为：物流公司简称+空格+物流单号
（2）物流单号允许在什么时间范围内进行更新？ A：商户需要7天内更新，因数据库在线库会清数据~
（3）如果不同子单有不同的物流信息，很可能不是同时取得的，是否支持一个一个增量更新？还是必须一起更新？ A：支持一个一个增量更新，以子单维度增加物流单号.
（4）如果请求更新的物流信息，是之前已经更新过，那么是因不允许更新而报错？还是会覆盖之前的信息？ A:允许更新，不会报错，会覆盖之前的信息
（5）如果请求的某一子单ID有误，是否会所有子单都更新不成功？还是仅仅有误的那个子单无法更新成功？ A：先全部校验订单信息。子单都对才去更新，某一个子单的suborderid有误，所有子单都更新不成功.
(6) 商户如果传服贸的子订单号来更新物流单号？ A：如果商户传的不是01货物的业务类型，则会提示子单校验失败
请求
POST: /payments/payment/{payment_id}/update_express_info
请求url中的payment_id是在上一步创建的真实payment_id(下单).
| 参数 | 描述 |
|---|---|
| payment | 对象. 支付对象. |
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共信息. |
| payment | 对象. 支付对象. |
| links | 对象数组. 下一步操作的链接. |
3.59 上传文件
此接口是为阿根廷留学业务开发的, 商户需要通过此接口上传交易的相关的文件, 并保存接口返回的文件名. 在下单时,将文件名传入下单接口.
需上传文件: 1. student_identity_filename | 学生身份信息 2. student_id_filename | offer或学生证 3. tuition_pay_filename | 学费缴费清单
## Request data:
curl -s -X POST https://fx.soopay.net/cberest/v1/file/upload \
-H "Content-Type:multipart/form-data" \
-H "Authorization:Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
-d ''
## Response data:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"data": "202311/11101442022111742308180002.jpg"
}
请求
POST: /file/upload
阿根廷留学商户在下单之前，上送交易证明文件。
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| data | 对象. 响应的文件路径. |
4. B2B
4.1 企业资质录入
## request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/enterprise_qualification \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:p+owOiuS9eVrDQIHaP9CwwR89k996MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM=" \
-d '{
"enterprise_qualification": {
"external_enterprise_id": "10000125",
"enterprise_name": "华西电子商务有限公司",
"enterprise_phone": "13241359611",
"enterprise_email": "fengjian@umpay.com",
"enterprise_contact": "FengJian1",
"busi_type": "GFHG",
"enterprise_code": "90000331"
}
} '
## Response data:
{
"meta": {
"sign": "KkIbGZXg49qqc6hHON/+dkxzqu+DYM3BvZ2iwK45SXnGLsH3fCX0lDXb2cf56/cRkI6/oZqlP8vqzRJEeKaopr1oVZTprynSRBthtvcTVZxF+mBLE53A1V3uLPO6qE6Tcg9Ex+nlDm0/ivGGka7kt5u1xpWyfXHRGeaJ8DLbr2c=",
"ret_msg": "Success",
"ret_code": "0000"
},
"enterprise_qualification":{
"external_enterprise_id": "10000125",
"enterprise_name": "华西电子商务有限公司",
"enterprise_phone": "13241359611",
"enterprise_email": "fengjian@umpay.com",
"enterprise_contact": "FengJian1",
"busi_type": "GFHG",
"enterprise_code": "90000331"
},
"links": [
{
"ref": "self",
"method": "GET",
"href": "https://uatfx.soopay.net/cberest/v1//enterprise_qualification/EQ_GEYDAMBQGEZDK7CHIZEEOMRQGE3TANRRGNJQ"
}
]
}
请求
POST:/enterprise_qualification
商户应该在UMF登记用户,企业的状态在创建时为“禁用”,之后商户应离线向UMF提交所需文件,UMF将向企业开户的银行提交文件,如果验证成功，状态将更改为“启用”。.
参数:
| 参数 | 描述 |
|---|---|
| enterprise_qualification | 对象. 企业资质信息. |
响应
响应结果包含meta信息和enterprise_qualification对象. 请参见示例.
4.2 企业资质查询
## Request data:
curl -s -X GET \
https://uatfx.soopay.net/cberest/v1/enterprise_qualification/EQ_GEYDAMBQGEZDK7CHIZEEOMRQGE3TANRRGNJQ
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f"
## Response data:
{
"meta": {
"sign": "GEy9+f2xwLcoMy5cvEsEPUima8A74fJXG9mpyy9qC/9tbvzXvmgcl3oS03ra19PxwFubw5GjpIeYk0E8G3xm0LiJ2LHUF6zLEQH/zt/ioPxcb+s15hY92ZioV8RKNvl16W7w/nonB/tYBkMQAD+1cCDPelVrIYdH4+pwSK4SJ+s=",
"ret_msg": "Success",
"ret_code": "0000"
},
"enterprise_qualification": {
"external_enterprise_id": "10000122",
"busi_type": "GFHG",
"rank": "A",
"enterprise_name": "华西电子商务有限公司"
}
}
请求
GET:/enterprise_qualification/enterprise_id
http get请求. enterprise_id应该使用enterprise_qualification对象的id替换.
响应
参数:
| 参数 | 描述 |
|---|---|
| enterprise_qualification | 对象. 企业资质信息. |
4.3 下单
## Request
$ curl -s -X POST https://uatfx.soopay.net/cberest/payments/payment \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM=" \
-d '{
"payer": {
"payment_method": "NOT_APPLICABLE",
"bank_code": "BOC",
"payer_info": {},
"interface_type": "DIRECT_TO_BANK",
"external_customer_id": "20066666",
"business_type": "B2B"
},
"order": {
"mer_reference_id": "201707270001",
"mer_date": "20170727",
"amount": {
"total": "200.04",
"currency": "USD"
},
"order_summary": "maimaimai",
"expire_time": "360",
"sub_orders": [
{
"mer_sub_reference_id": "072700012",
"trans_code": "08227020",
"amount": {
"total": "100.02",
"currency": "USD"
},
"invoice_id": "123456"
},
{
"mer_sub_reference_id": "072700011",
"trans_code": "01122030",
"amount": {
"total": "100.02",
"currency": "USD"
},
"is_customs": "FALSE",
"invoice_id": "123456",
"items": [
{
"mer_item_id": "0727000111",
"type": "FOOD",
"name": "banana",
"quantity": "2",
"description": "banana",
"amount": {
"total": "50.02",
"currency": "USD"
}
},
{
"mer_item_id": "0727000112",
"type": "ELECTRONIC",
"name": "yifu",
"quantity": "3",
"description": "yifu",
"amount": {
"total": "50.00",
"currency": "USD"
}
}
]
}
]
},
"notify_url": "http://10.10.178.93:8081/spaytest/notify0000V4.jsp",
"ret_url": "http://10.10.178.93:8081/spaytest/notify0000V4.jsp",
"risk_info": {
"trans_type": "02"
}
}'
## Response
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"id":"PAY_GI3TANZSHAYTQMBZGAYTMNJTGUZDAMJXGA3TEOGI",
"risk_info": {
"trans_type": "02"
},
"notify_url": "http://10.10.178.93:8081/spaytest/notify0000V4.jsp",
"payer": {
"bank_code": "BOC",
"external_customer_id": "20066666",
"business_type": "B2B",
"interface_type": "DIRECT_TO_BANK",
"payment_method": "NOT_APPLICABLE",
"payer_info": {}
},
"ret_url": "http://10.10.178.93:8081/spaytest/notify0000V4.jsp",
"order": {
"amount": {
"total": "200.04",
"currency": "USD"
},
"sub_orders": [
{
"mer_sub_reference_id": "072700012",
"trans_code": "08227020",
"amount": {
"total": "100.02",
"currency": "USD"
},
"invoice_id": "123456"
},
{
"mer_sub_reference_id": "072700011",
"trans_code": "01122030",
"amount": {
"total": "100.02",
"currency": "USD"
},
"invoice_id": "123456",
"is_customs": "FALSE",
"items": [
{
"amount": {
"total": "50.02",
"currency": "USD"
},
"quantity": "2",
"mer_item_id": "0727000111",
"name": "banana",
"description": "banana",
"type": "FOOD"
},
{
"amount": {
"total": "50.00",
"currency": "USD"
},
"quantity": "3",
"mer_item_id": "0727000112",
"name": "yifu",
"description": "yifu",
"type": "ELECTRONIC"
}
]
}
],
"mer_date": "20170727",
"expire_time": "360",
"mer_reference_id": "201707270001",
"order_summary": "maimaimai"
}
},
"links": [
{
"ref": "self",
"method": "GET",
"href": "http://10.10.179.74:8070/cberest/v1/payments/payment/PAY_GI3TANZSG4YTGNBZGAYDMOBYGQZDAMJXGA3TEN6F"
},
{
"ref": "upay",
"method": "GET",
"href": "http://10.10.178.116:8081/upay/cbPluginPay.do?cbAmount=20004&retUrl=http%3A%2F%2F10.10.178.116%3A8081%2Fupay%2FcbPluginPayReturn.do&busiId=06&orderId=201707270001&isShowTransUse=N&merName=%E8%B7%A8%E5%A2%83%E6%94%B6%E9%93%B6%E5%8F%B0%E6%B5%8B%E8%AF%95%E5%95%86%E6%88%B700&isShowFrame=Y&isCollectUserInf=N&interfaceType=02&trace=2707271349719054&payType=1&exchangeRate=6.784¤cy=USD&oriAmount=135707&amount=135707&goodsInf=maimaimai&idenCheckFlag=N&rpid=PSP134922ecc19f6&instId=20000001&isShowCustomServiceInf=Y&expireTime=2017-07-27+19%3A49%3A24.38¬ifyUrl=http%3A%2F%2F10.10.179.74%3A8070%2Fcberest/v1%2Fpayments%2Fpayment%2Fnotify&merId=70510000&binBankId=B001&busiPayUrl=http%3A%2F%2F10.10.179.34%3A8087%2Fpaybusi%2FA01002&orderDate=20170727&payDate=20170727&sign=6a351a59d3749645b7612e2c815f8d2aef529717"
},
{
"ref": "apply_to_customs",
"method": "POST",
"href": "http://10.10.179.74:8070/cberest/v1/payment/PAY_GI3TANZSG4YTGNBZGAYDMOBYGQZDAMJXGA3TEN6F/apply_to_customs"
},
{
"ref": "refund",
"method": "POST",
"href": "http://10.10.179.74:8070/cberest/v1/payment/PAY_GI3TANZSG4YTGNBZGAYDMOBYGQZDAMJXGA3TEN6F/refund"
}
]
}
POST: /payments/payment
B2B交易的下单. 付款人必须使用企业到银行账户.
支付类型为"B2B_ONLINE_BANKING"
参数:
| 参数 | 描述 |
|---|---|
| payer | 对象. 付款信息. |
| order | 对象. 订单信息. 包含子订单. |
| notify_url | 字符串. 商户服务器地址. 用于接收支付结果. |
响应:
| 参数 | 描述 |
|---|---|
| payer | 对象. 支付信息. |
| order | 对象. 订单信息. 包含子订单. |
| notify_url | 字符串. 商户服务器地址. 用于接收支付结果. |
| links | 对象数组. 下一步操作的链接. 取决于状态和支付类型. 这些链接是HATEOAS 链接. |
支付结果通知
当处理完商户的支付请求数据后,UMF会将支付结果发送到商户的服务器.
接收到请求后商户需要响应.
和B2C的通知一致. 请参见 3.5 支付结果通知
4.4 上传交易明细文件
支付成功后, 商户需要通过FTP协议上传交易的所有文档. 一旦商户账号创建完成,UMF需要向商户发送地址,用户名和密码.
文件上传规则:
- 每笔付款都需要上传相关文件.
- 文件需要包括联系人和发票.
- 一笔交易的所有文件应该压缩成一个文件,格式是zip.
- 商户仅有向FTP文件夹写的权限, 商户不能删除已经上传的文件.
- 文件名应该遵循的规则：mer_reference_id + mer_date + sequence_num（4位）.zip. mer_reference_id和mer_date应该与下单是一样的. sequence_num是相同支付的序列. 如果上传的文件有错误, 商户需要上传另一个带有不同序列号的压缩文件.
- UMF的工作人员会校验上传的文件F. 校验完成后, UMF将金额由人民币兑换成对应的货币. 如果校验没在24小时内完成，付款将取消. 金额将退回到支付人.
4.5 付款查询
和B2C付款查询相同. 请参见 3.6 付款查询
4.6 退款
和B2C退款相同. 请参见 3.7 退款
4.7 退款查询
和B2C退款查询查询相同. 请参见 3.8 退款查询
4.8 结算列表下载
和B2C结算列表下载相同. 请参见 3.11 结算列表下载
4.9 对账文件下载
和B2C对账文件下载相同. 请参见 3.12 对账文件下载
4.10 汇率查询
和B2C汇率查询相同. 返回信息是人民币的对账金额.
请参见 3.13 汇率查询
5. 实体
amount
| 参数 | 描述 | 约束 |
|---|---|---|
| total | 收款或退款的总金额. | 字符串.最大长度10. 两位小数. |
| currency | ISO-4217 币种代码. | 三个大写英文字符 |
| total_cny | 人民币金额. | 可选.字符串.最大长度10. 两位小数. |
| exchange_rate | exchange_rate汇率. | 可选. 对象. |
bank
| 参数 | 描述 | 约束 |
|---|---|---|
| name | 英文的银行名称. | 字符串.最大长度256. |
| name_zh | 中文的银行名称. | 字符串.最大长度16.最小长度2 |
| code | 银行缩写. 国内银行. | 16个大写英文字母以内 |
| logo_url | 银行图标地址. | 字符串.最大长度128 |
| types | 银行支持的卡类型.枚举值: CREDIT_CARD, DEBIT_CARD | 数组 |
| is_support | 联动是否支持. 可选值: Y, N | 字符串 |
bank_card
| 参数 | 描述 | 约束 |
|---|---|---|
| number | 卡号 | 字符串. 加密. |
| valid_date | 银行卡有效期 | 字符串. 加密. 格式YYMM |
| cvv2 | 银行卡安全码 | 字符串. 加密. |
| payer_name | 持卡人姓名 | 字符串. 加密. |
| phone | 银行预留号码. | 字符串. |
| citizen_id_type | 公民当前身份类型. 枚举值为IDENTITY_CARD | 枚举. |
| citizen_id_number | 身份证号码. | 字符串. 加密. |
| verify_code | 短信验证码. | 字符串.最大长度8 |
customs_declaration
| 参数 | 描述 | 约束 |
|---|---|---|
| id | id | 字符串 |
| sub_order | sub_order | 对象 |
| customs_id | 海关申报时的海关编号(如 HZHG, NB 和 GZHG 分别代表杭州, 宁波 和广州海关). | 字符串.最大长度10 |
| mer_customs_code | 商户海关备案编号 | 字符串.最大长度60 |
| freight_amount | 支付运费amount | 对象 |
| tax_amount | 海关税amount | 对象 |
| sub_order_amount | 订单金额amount | 对象 |
| ec_plat_id | 商户海关备案编号 | 字符串.最大长度60.最小长度4 |
| notify_url | 商户接收通知地址. 从UMF接收地址. | 字符串.最大长度128 |
| state | 状态. 枚举值ACCEPTED SUBMITTED SUCCESS FAIL |
枚举 |
| customs_clearance_date | 请求海关日期 | 字符串.格式为YYYYMMDD |
| verify_department | 验核机构 验核机构包括： 银联-UnionPay 网联-NetsUnion 其他-Others（银行卡快捷，网银） |
字符串. |
| verify_department_pay_trace | 验核机构流水号 交易流水号，来自验核机构，如银联侧的交易流水号，供商户报备海关 | 字符串. |
| mer_date | 原订单时间 | 字符串 yyyyMMdd 非必传，(报关)接口必传. |
declare_again
| 参数 | 描述 | 约束 |
|---|---|---|
| declare_type | 海关或者国检 0 海关 ； 1 国检 | String 0 or 1 |
| mer_reference_id | 报关订单号 | 字符串,最大长度32.最小长度4. |
exchange_rate
| 参数 | 描述 | 约束 |
|---|---|---|
| currency | 货币代码 | 枚举 |
| rate | 汇率 | 字符串.最大长度10.8位小数 |
enterprise_qualification
企业资质. 应用于B2B业务.
| 参数 | 描述 | 约束 |
|---|---|---|
| id | 字符串 | |
| external_enterprise_id | 商户系统中的企业id | 字符串.最大长度16 |
| enterprise_name | 企业名称 | 字符串.最大长度256 |
| enterprise_phone | 手机号 | 字符串.手机号格式 |
| enterprise_email | 邮箱 | 字符串.邮箱格式 |
| enterprise_contact | 联系人姓名 | 字符串.最大长度256 |
| rank | 企业状态 枚举值 A: 表示该企业是A类企业,可做货物、服务类交易 OTHERS:表示该企业还未确认,可做服务类交易 UNKNOWN:表示该企业是非A类企业,不可做交易 |
枚举. |
| busi_type | 企业类型. 枚举值 -SJHG: 收结汇. -GFHG: 购付汇. |
枚举 |
| enterprise_code | 法人实体和其他组织统一的社会信用法典体系.请参见 (统一社会信用代码) | 字符串.最大长度18.最小长度8 |
item
子订单中相同商品的信息.
| 参数 | 描述 | 约束 |
|---|---|---|
| mer_item_id | 商户系统id. | 字符串.最大长度32 |
| type | 商品类型. 枚举值 CLOTHING FOOD ELECTRONIC COSMETIC HOUSEHOLD_ITEMS |
枚举 |
| name | 商品名称 | 字符串.最大长度256 |
| description | 商品描述 | 字符串.最大长度64 |
| amount | 金额. 商品的价格. | 必填 |
| quantity | 数量. 商品的数量. | 字符串. |
link
付款或退款对象的一部分. 这是那些对象的下一步. 链接取决于对象的状态.
| 参数 | 描述 | 约束 |
|---|---|---|
| href | 对象的url. 对象或对象的可用操作. | 字符串.最大长度128 |
| ref | 对象的关联操作地址. | 字符串.最大长度128 |
| method | http方法. 枚举值POST, GET, PUT | 枚举. |
meta
响应信息的一部分. 包含响应的公共信息.
| 参数 | 描述 |
|---|---|
| ret_code | 响应的返回码. |
| ret_msg | 响应信息. |
| CONTENT | 内容. |
| errorCode | 交易错误码. |
order
订单信息. 订单的详细信息,item必须在子订单对象中.
| 参数 | 描述 | 约束 |
|---|---|---|
| amount | 订单总金额. | 对象 |
| expire_time | 订单有效时间.UMF默认24小时，单位：分钟。 如果支付时间过时, UMF不会支付订单. | 字符串.最大长度8 |
| mer_reference_id | 表示订单号. 商户唯一订单号. | 字符串,最大长度32.最小长度4. |
| mer_date | 订单日期. 下单的日期. | 字符串.长度为8 |
| order_summary | 订单信息. | 字符串.最大长度32 |
| sub_mer_Id | 二级商户号 | 字符串.最大长度8 |
| sub_orders | 子订单 数组对象. 每个子订单只能是相同的商品类型. | 对象数组 |
| user_ip | 用户付款请求的IP地址.(微信APP与微信公众号，该字段必填) API模式时,该字段必填 |
字符串.ip地址格式 |
| if_sms | 是否检验短信 字符串. |
N 不校验 Y 校验 |
| school_locate_city | 学校所在城市 | 字符串.最大长度255 |
| school_name | 学校名称 | 字符串.最大长度127 |
| student_name | 学生姓名(每笔订单对应单个个人) | 字符串.加密.最大长度255 |
| student_id | 录取通知书编号/学生证件号 | 字符串.最大长度65 |
| enrollment_date | 入学日期 | 字符串.最大长度8 |
| student_identity_filename | 学生身份信息 | 字符串.最大长度127 |
| student_id_filename | offer或学生证 | 字符串.最大长度127 |
| tuition_pay_filename | 学费缴费清单 | 字符串.最大长度127 |
pagination
一些返回大量对象的API接口会响应分页信息; 以及对象列表中也会有响应的分页的key.
| 参数 | 描述 | 约束 |
|---|---|---|
| total_count | 交易列表总数. | 字符串 |
| page_number | 当前页的数量 (从1开始). | 字符串 |
| page_size | 每一页的记录大小. | 字符串 |
payer
付款信息.
| 参数 | 描述 | 约束 |
|---|---|---|
| payment_method | 支付方式. 枚举值: - CREDIT_CARD : 信用卡支付. 请参见银行卡支付流程. - DEBIT_CARD: 借记卡支付. 请参见银行卡支付流程. - WECHAT_SCAN: UMF返回二维码字符串. 客户可以用微信扫描二维码支付. 请参见微信主扫支付流程. - WECHAT_IN_APP: 用户可以在app应用里完成支付. 请参见微信APP支付流程. - WECHAT_WEB: 用户可以在微信浏览器内完成支付. 请参见微信公众号支付流程. - ALIPAY_SCAN: UMF返回二维码字符串. 用户使用支付宝扫描二维码完成支付. 请参见支付宝支付流程. - WECHAT_H5: UMF返回支付链接. 用户在浏览器打开支付链接完成支付. 请参见微信H5支付流程. - NOT_APPLICABLE: 接口类型是收银台或网银直连. |
枚举 |
| bank_code | 国内银行缩写. 请参见银行代码 | 16个大写英文字母或数字以内 |
| business elements object | 该字段的名称根据business_type而不同的. 可以是如下对象. B2C付款为payer_info . B2B付款为enterprise_qualification . |
对象 |
| interface_type | 付款接口类型. 枚举值: - SERVER_TO_SERVER : API请求 - SERVER_TO_WEB : 服务器到UMF收银台 - SERVER_TO_H5WEB : 服务器到UMF H5收银台 - DIRECT_TO_BANK : 网银, 如果 payment_method的值为NOT_APPLICABLE, bank_code会发送. |
枚举 |
| business_type | 枚举值: - B2B : 企业到企业. - B2C : 企业到用户. |
枚举 |
| external_customer_id | 商户用户标识 | 字符串.最大长度32 |
interface_type和business_type可用的支付方式如下
| 接口类型 | B2C | B2B |
|---|---|---|
| SERVER_TO_SERVER | CREDIT_CARD DEBIT_CARD WECHAT_SCAN WECHAT_IN_APP WECHAT_WEB ALIPAY_SCAN WECHAT_H5 |
|
| SERVER_TO_WEB | NOT_APPLICABLE | |
| DIRECT_TO_BANK | WECHAT_SCAN ALIPAY_SCAN |
NOT_APPLICABLE |
| SERVER_TO_H5WEB | NOT_APPLICABLE |
payer_agreement
支付协议代表了用户的一张卡. 验证时商户可以使用这个对象代替银行卡对象.
| 参数 | 描述 | 约束 |
|---|---|---|
| usr_busi_agreement_id | 商户系统每个用户的唯一id. | 字符串.最大长度64 |
| usr_pay_agreement_id | 每个usr_busi_agreement_id的每张卡的唯一id. | 字符串.最大长度64 |
| gate_id | 银行代码. | 字符串.最大长度16 |
| last_four_cardid | 卡号后四位. | 字符串.长度为4 |
| valid_date | 到期时间. | 字符串.格式为（YYMM） |
| cvv2 | 银行卡安全码. | 字符串 |
| verify_code | 短信验证码. | 字符串.最大长度8 |
pay_info
支付信息对象包含微信APP支付和微信公众号支付的信息.
| 参数 | 描述 | 约束 |
|---|---|---|
| app_id | UMF的合作商户的唯一标识符 | 字符串 |
| time_stamp | 从世界时间1970年1月1日星期四至今经过的秒数. | 字符串 |
| sign_type | 签名方式. 此情景下为MD5. | 字符串 |
| package | 微信支付的id. | 字符串 |
| nonce_str | 生成签名的随机字符串. | 字符串 |
| pay_sign | 请求的签名. | 字符串 |
payer_info
支付人信息.
| 参数 | 描述 | 约束 |
|---|---|---|
| phone | 支付人手机号. | 字符串.手机号格式 |
| name | 必须加密. 支付人姓名. | 字符串.最大长度128 |
| pay elements object | 这部分的名称是不同的, 取决于支付类型. 可选值如下. bank_card. 支付类型有: 信用卡支付, 借记卡支付 qr_code_scan. 支付类型有: 微信主扫支付, 支付宝主扫支付 wechat_in_app 支付类型有: 微信APP支付 wechat_in_app_web 支付类型有: 微信公众号支付 payer_agreement 支付类型有: CREDIT_CARD, DEBIT_CARD wechat_H5 支付类型有: 微信H5 |
对象 |
payment
支付对象是API接口的核心. 包含如下信息:
| 参数 | 描述 | 约束 |
|---|---|---|
| id | 支付id.(请求时无需上送) | 字符串 |
| payer | 支付信息. | 对象 |
| order | 订单信息. 包含子订单. | 对象 |
| state | 支付状态. 枚举值 -WAIT_BUYER_PAY: 付款需要支付. -TRADE_SUCCESS: 支付成功. -TRADE_CLOSED:订单过期,支付关闭. -TRADE_CANCEL:付款取消. -TRADE_FAIL: 支付失败. |
枚举 |
| ret_url | 结果前台通知. 仅存在于商户使用UMF的收银台. | 字符串.最大长度128 |
| notify_url | 结果后台通知. 仅存在于商户使用UMF的收银台. | 字符串.最大长度128 |
| execute_success_time | 金额从用户账户转移到UMF账户的时间. | 字符串 |
| mer_check_date | 交易日期. 日期来自商户系统. 不具有时区信息. 交易将在交易列表和对账列表中标记此日期. | 字符串.最大长度8 |
| settle_date | UMF的交易日期. | 字符串.最大长度8 |
| refund | 退费信息. | 对象 |
| risk_info | 反欺诈信息. 内容取决于商户和UMF之间的合同. |
payment_summary
付款详情. 包含一个对账对象或者结算对象.
| 参数 | 描述 | 约束 |
|---|---|---|
| payment_id | 支付id. | 字符串 |
| phone_number | 用户手机号. 仅存在于对账对象. | 字符串 |
| order_date | 订单日期. | 字符串 |
| mer_reference_id | 订单引用id. | 字符串 |
| amount | amount. | 对象 |
| settle_date | 交易日期. | 字符串 |
| execute_success_time | 交易完成时间. | 字符串 |
| state | 请参见payment. | 对象 |
| product_id | UMF的产品号. | 字符串 |
| service_fee | 人民币费率. 仅存在于结算对象. | 字符串 |
| exchange_amount | 兑换金额, amount. 仅存在于结算对象. | 对象 |
| exchange_date | 兑换日期. 仅存在于结算对象. | 字符串 |
qr_code_scan
商户为每个订单创建二维码. 用户使用微信或支付宝扫描二维码后, 可以在手机上看到相关的产品信息和交易指南. 这个对象可以用于微信或支付宝.
如果商户想显示一个二维码给客户进行扫描, wechat_qr_code对象需要被包含在payer_info对象中.
| 参数 | 描述 | 约束 |
|---|---|---|
| citizen_id_type | 身份证类型. 目前, 枚举值IDENTITY_CARD. | 枚举 |
| citizen_id_number | 身份证号码.加密 | 字符串 |
| qr_code_url | 微信二维码支付地址. 该信息由UMF返回 | 字符串 |
qr_code_url是二维码的内容.商户使用二维码转换工具将url字符串转换为二维码. 当用户使用微信或二维码扫描二维码时, 可以使用微信或支付宝支付.
reconciliations
结算信息.
| 参数 | 描述 | 约束 |
|---|---|---|
| payment_summaries | payment_summary. | 对象数组 |
| refund_summaries | refund_summary. | 对象数组 |
| settle_date | 结算日期. | 字符串 |
| amount | 对账的总金额.amount | 对象 |
| pagination | pagination对象返回当前页和当前页的记录数的信息.pagination | 对象 |
refund
退款对象取决于付款对象. 一次付款可以联系多个退款对象, 意味着一次付款可以被多次退款. 退款的总金额不会大于付款的总金额. 包含如下信息:
| 参数 | 描述 | 约束 |
|---|---|---|
| id | 退费id,由UMF返回 | 字符串 |
| refund_info | 包含退费的mer_reference_id和商品信息. | 对象 |
| notify_url | 商户通知地址. 用于接收退款通知. | 字符串.最大长度128 |
| state | 退款状态. 枚举值REFUND_PROCESS, REFUND_SUCCESS, REFUND_FAIL, REFUND_CLOSE, REFUND_RETRY. | 枚举 |
asy_refund
退款对象取决于付款对象. 一次付款可以联系多个退款对象, 意味着一次付款可以被多次退款. 退款的总金额不会大于付款的总金额. 包含如下信息:
| 参数 | 描述 | 约束 |
|---|---|---|
| refund_info | 包含退费的mer_reference_id和商品信息. | 对象 |
| notify_url | 商户通知地址. 用于接收退款通知. | 字符串.最大长度128 |
| state | 退款状态. 枚举值 REFUND_PROCESS REFUND_SUCCESS REFUND_FAIL REFUND_CLOSE REFUND_RETRY |
枚举 |
| mer_reference_id | 退款唯一id. | 字符串.最大长度32.最小长度4 |
refund_info
退款信息. 退费实体详细信息必须在子订单对象中.
| 参数 | 描述 | 约束 |
|---|---|---|
| mer_reference_id | 退款唯一id.在asy_refund实体中，此字段为主单订单号 | 字符串.最大长度32.最小长度4 |
| mer_date | 退款日期. This time will show as-is in the statement. | YYYYMMDD |
| amount | 退款金额. | 对象 |
| refund_summary | 退款摘要. | 字符串.最大长度64 |
| sub_orders | 1. 一次退款可能包含多个sub_order. 退款子订单的mer_sub_reference_id和付款子订单ID一致,退款金额和退款的子订单金额总和相等. 2. 交易代码为**货物交易的如01122030时需要发送trans_code参数并且发送items. |
对象数组 |
refund_summary
退款摘要. 包含在交易对象或对账对象中.
| 参数 | 描述 | 约束 |
|---|---|---|
| refund_id | 退款id. | |
| payment_id | 支付id. | |
| phone_number | 用户手机号. 仅存在于对账对象. | |
| amount | Object. | |
| settle_date | 退款请求提交日期. | |
| execute_success_time | 交易完成时间戳. | |
| state | 请参见 refund. | |
| product_id | UMF的产品号. | |
| mer_sub_reference_id | 子订单参考id. 仅存在于对账对象. |
risk_info
交易信息. UMF使用信息核准或拒绝交易. 如果欺诈的风险太高交易将被取消. 反欺诈算法将周期性地进行检查.
| 字段名 | 描述 | 字段描述 | 发送与否 | 约束 |
|---|---|---|---|---|
| goods_type | 商品分类 | 枚举值. 0 虚拟类 1 实物类 |
必填 | 枚举 |
| real_name | 商品实名制购买 | 枚举值. 0 非实名制 1 实名制 |
必填 | 枚举 |
| business_type | 业务类型 | 枚举值 2 跨境支付 |
非必填 | 枚举 |
| trans_type | 交易类型 | 枚举值. 01 充值 02 消费 |
非必填 | 枚举 |
| receiver_name | 收货人姓名 | 例如: 张三 | 必填 | 字符串.最大长度256 |
| receiver_moblie_id | 收件人的电话号码 | 例如: 13800011111 | 必填 | 字符串.手机号格式 |
| shipping_address | 送货地址 | 例如：北京市海淀区学院南路12号 | 必填 | 字符串 |
| identify_card_number | 身份证号码 | 注册人身份证号码 | 视情况而定 | 字符串 |
| registration_email | 注册人邮箱 | 用户注册时所用邮箱, 商户必须加密 | 非必填 | 字符串.邮箱格式 |
| registration_moblie_id | 手机号 | 注册人手机号 | 非必填 | 字符串.手机号格式 |
| device_type | 设备类型 | 如果是WEB终端, 用户不为空. APP为空. | 非必填 | |
| user_ip | 用户ID | 商户侧用户标识，可以是数据库主键标识，也可以是用户登陆id | 当interface_type为SERVER_TO_SERVER时该字段必填,该字段下单时在order实体上送 | 字符串.ip地址格式 |
| registration_time | 用户注册时间 | 用户注册产品的时间，在第二阶段应该准确读取. 例如:20150311120000 |
非必填 | 字符串 |
| user_agent | 产品形态 | 枚举值. 1 android app 2 IOS app 3 PC (web page) 4 Mobile phone(wap, or html5 page); |
非必填 | 枚举 |
| success_transactions_number | 用户成功交易笔数 | 商户平台的成功交易量 | 非必填 | 字符串 |
| is_receiver_bank_num | 收款人手机号与银行预留手机号一致性 | 枚举值. 0 不一致 1 一致 |
必填 | 枚举 |
| registration_days | 用户已注册天数 | 例如: 3天 | 必填 | 字符串.最大长度30 |
sub_order
相同交易id的商品在同一个子订单对象中.
| 参数 | 描述 | 约束 |
|---|---|---|
| mer_sub_reference_id | 子订单对象的id.(非必填，不传联动返回，作为报送海关的订单号) | 字符串.最大长度32.最小长度4 |
| amount | 子订单金额. | 对象 |
| trans_code | 商品的交易码. 请参见 交易代码及交易附言描述 | 字符串.固定长度8. |
| is_customs | 是否报关. | 字符串 |
| invoice_id | 子订单收据. | 字符串.最大长度20 |
| items | item. | 对象数组(业务类型为货物时必传) |
| sub_customs_trace | 报关流水.商户无需上送，请求UMF报关后返回 | 字符串.最大长度20 |
| tracking_number | 物流单号.更新物流单号时上传 | 字符串.最大长度64 |
transactions
对账信息.
| 参数 | 描述 | 约束 |
|---|---|---|
| payment_summaries | payment_summary. | 对象数组 |
| refund_summaries | refund_summary. | 对象数组 |
| pagination | pagination对象返回当前页和当前页的记录数的信息.pagination | 对象 |
wechat_in_app
返回所有微信SDK要求激活和付款的所有信息.
| 参数 | 描述 | 约束 |
|---|---|---|
| citizen_id_type | 身份证类型. 枚举值 IDENTITY_CARD. | 枚举 |
| citizen_id_number | 加密. 身份证号码. | 字符串 |
| pay_info | 调用微信本地SDK激活微信APP的信息. | 对象 |
| app_id | 微信开发识别码 | 字符串.长度为32 |
wechat_in_app_web
返回所有微信SDK要求激活和付款的所有信息. 商户不需要修改微信需要的信息.
| 参数 | 描述 | 约束 |
|---|---|---|
| open_id | OpenID是为每个合作用户的唯一微信id, 不同的用户有单独的OpenID. | 字符串 |
| citizen_id_type | 身份证类型. 枚举值 IDENTITY_CARD. | 枚举 |
| citizen_id_number | 加密. 身份证号码. | 字符串 |
| pay_info | 在微信浏览器调用微信JS-API唤醒微信支付插件的信息. | 对象 |
| app_id | 微信开发识别码 | 字符串.长度为32 |
wechat_H5
返回微信H5地址
| 参数 | 描述 | 约束 |
|---|---|---|
| citizen_id_type | 身份证类型. 枚举值 IDENTITY_CARD. | 枚举 |
| citizen_id_number | 加密. 身份证号码. | 字符串 |
| wechat_h5_url | 微信h5支付地址.urlEncode转码 | 字符串. |
settle_month_file
月对账单
| 参数 | 描述 | 约束 |
|---|---|---|
| settle_month | 对账月份 . | 字符串 |
national_inspection
国检信息
| 参数 | 描述 | 约束 |
|---|---|---|
| id | id(请求时无需上送) | 字符串 |
| sub_order | sub_order. | 字符串 |
| mer_date | 商户订单日期 | 字符串 |
| ciq_code | 报检局编码(如GJHP) | 字符串 |
| plat_supplier_no | 电商平台备案编号 | 字符串 |
| ciq_clearance_date | 报关日期，该信息由平台返回时填写，商户不用填写 | 字符串 |
customs_declaration_only
独立报关信息
| 参数 | 描述 | 约束 |
|---|---|---|
| id | id(请求报关时无需上送) | 字符串 |
| mer_reference_id | 表示订单号. 商户唯一订单号. | 字符串,最大长度30.最小长度4. |
| order_amount | 订单金额amount | 对象 |
| name | 必须加密. 支付人姓名. | 字符串.最大长度128 |
| citizen_id_type | 公民当前身份类型. 枚举值为IDENTITY_CARD | 枚举. |
| citizen_id_number | 身份证号码. | 字符串. 加密. |
| mer_pay_date | 商户订单支付日期 | 字符串.格式为YYYYMMDD |
| mer_pay_time | 商户订单支付时间. | 字符串.格式为HHmmss |
| phone | 支付人手机号. | 字符串. |
| customs_id | 海关申报时的海关编号(如 HZHG, NB 和 GZHG 分别代表杭州, 宁波 和广州海关). | 字符串.最大长度10 |
| mer_customs_code | 海关商户号 | 字符串.最大长度60 |
| ec_plat_id | 海关系统电子商务平台帐号 | 字符串.最大长度60.最小长度4 |
| freight_amount | 支付运费amount | 对象 |
| tax_amount | 海关税amount | 对象 |
| state | 状态. 枚举值ACCEPTED SUBMITTED SUCCESS FAIL 请求UMF报关后返回，无需上送 |
枚举 |
| customs_clearance_date | 请求海关日期 请求UMF报关后返回，无需上送 |
字符串.格式为YYYYMMDD |
| pay_trace | 原支付流水号.非必填.不传会返回 | 字符串.最大长度32. |
| notify_url | 异步通知报关结果地址. | 字符串. |
| paye_code | 企业检验检疫CIQ备案编号.当报送平潭海关且需同时报送国检时，该字段必填 | 字符串. |
| goods_info | 货物信息 字段传入要求：商品描述+规格+数量 如有多个货物，用 ;隔开，如：飞利浦电动牙刷HX6730*1;Estee Lauder精华眼霜 15ml*1 | 字符串. |
| tracking_number | 物流单号 物流公司名+单号，如：申通 3716523085241 | 字符串. |
bind
签约信息
| 参数 | 描述 | 约束 |
|---|---|---|
| id | id(请求签约时无需上送) | 字符串 |
| number | 卡号 | 字符串. 加密. |
| citizen_id_number | 身份证号码. | 字符串. 加密. |
| citizen_id_type | 公民当前身份类型. 枚举值为IDENTITY_CARD | 枚举. |
| name | 支付人姓名. | 字符串. 加密.最大长度128. |
| phone | 银行预留号码. | 字符串. |
| bank_code | 银行简称. | 字符串. |
| verify_code | 短信验证码. | 字符串.最大长度8 |
bind_payment
一键支付对象是API接口的核心. 包含如下信息:
| 参数 | 描述 | 约束 |
|---|---|---|
| id | 支付id.(请求时无需上送) | 字符串 |
| order | 订单信息. 包含子订单. | 对象 |
| state | 支付状态. 枚举值 -WAIT_BUYER_PAY: 付款需要支付. -TRADE_SUCCESS: 支付成功. -TRADE_CLOSED:订单过期,支付关闭. -TRADE_CANCEL:付款取消. -TRADE_FAIL: 支付失败. |
枚举 |
| ret_url | 结果前台通知. 仅存在于商户使用UMF的收银台. | 字符串.最大长度128 |
| notify_url | 结果后台通知. 仅存在于商户使用UMF的收银台. | 字符串.最大长度128 |
| execute_success_time | 金额从用户账户转移到UMF账户的时间. | 字符串 |
| mer_check_date | 交易日期. 日期来自商户系统. 不具有时区信息. 交易将在交易列表和对账列表中标记此日期. | 字符串.最大长度8 |
| settle_date | UMF的交易日期. | 字符串.最大长度8 |
| risk_info | 反欺诈信息. 内容取决于商户和UMF之间的合同. | |
| usr_pay_agreement_id | String. 用户的支付协议号. | |
| bank_code | 国内银行缩写. 请参见银行代码 | 16个大写英文字母或数字以内. |
account_balance
账户余额. 包含如下信息:
| 参数 | 描述 | 约束 |
|---|---|---|
| balance | 可退款余额 （币种：人民币；单位：元） | 字符串 |
ciq_declaration_only
独立报检信息
| 参数 | 描述 | 约束 |
|---|---|---|
| id | id(请求报检时无需上送) | 字符串 |
| ciq_id | 国检申报时的海关编号(如 GJHP 代表黄埔国检). | 字符串.最大长度10 |
| mer_ciq_code | 国检商户号 | 字符串.最大长度60 |
| ec_plat_id | 国检系统电子商务平台帐号 | 字符串.最大长度60.最小长度4 |
| state | 状态. 枚举值ACCEPTED SUBMITTED SUCCESS FAIL 请求UMF报检后返回，无需上送 |
枚举 |
| ciq_clearance_date | 请求国检日期 请求UMF报检后返回，无需上送 |
字符串.格式为YYYYMMDD |
| pay_trace | 原支付流水号.非必填 | 字符串.最大长度32. |
payee_infor
收款方信息
| 参数 | 描述 | 约束 |
|---|---|---|
| payee_account | 收款方账号 | 字符型.最大长度32(加密).必传 |
| payee_name | 收款方名称 | 字符串.加密(加密).必传 |
| payee_address | 收款方地址 | 字符串(加密).必传 |
| payee_swift | 收款行swiftcode | 字符串.固定长度8位或11位(加密).必传 |
| iban | 收款行IBAN | 字符串.最大长度32(加密).非必传 欧元区银行识别码，如果输入会取代“收款人账号”作为收款人要素 |
| payee_bank_name | 收款行名称 | 字符串.最大长度32(名称跟地址不能超过130字符).非必传 |
| payee_bank_address | 收款行名称地址 | 字符串.最大长度128(名称跟地址不能超过130字符).非必传 |
| payee_country | 收款方国家 | 字符串.最大长度32.必传 |
order_item
交易明细信息
| 参数 | 描述 | 约束 |
|---|---|---|
| mer_batchno | 商户批次号 | 字符型.最大长度16.必传 |
| business_code | 业务编码 | 字符串.最大长度8.必传 |
| currency | 币种 | 字符串.固定长度3.必传 |
| mer_orderId | 商户订单号 | 字符串.最大长度64.必传 |
| goods_type | 商品品类 | 字符串.最大长度32.必传 |
| goods_name | 商品名称 | 字符串.最大长度256.必传 |
| goods_unitPrice | 商品单价 | 字符串.最大长度20.必传.单位:元 |
| goods_sum | 商品数量 | 字符串.最大长度8.必传. |
| Damount | 交易金额 | 字符串.最大长度20.必传.单位:元 |
| payer_name | 支付人姓名 | 字符串(加密).必传. |
| payer_IDCard | 支付人身份证号 | 字符串(加密)不支持15位版本身份证号.必传. |
| payer_phone | 支付人手机号 | 字符串.最大长度16.必传. |
| order_time | 订单时间 | 字符串.固定长度20.必传.格式：yyyy-MM-dd HH:mm:ss |
| pay_time | 支付时间 | 字符串.固定长度20.必传.格式：yyyy-MM-dd HH:mm:ss |
| logistics_no | 物流单号 | 字符串.最大长度64.必传. |
| val_pattern | 计价方式 枚举值 -CNY_VALUATION: 人民币计价. -FOREIGN_VALUATION: 外币计价. |
枚举 |
confirm_payment
确认付款信息
| 参数 | 描述 | 约束 |
|---|---|---|
| mer_batchno | 商户批次号 | 字符型.最大长度16.必传 |
| payee_account | 收款方账号 | 字符串(加密).必传 |
| val_pattern | 计价方式 枚举值 -CNY_VALUATION: 人民币计价. -FOREIGN_VALUATION: 外币计价. |
枚举 |
| currency | 币种 | 字符串.最大长度3.必传 |
| Oamount | 交易金额 | 字符串.最大长度20.必传.单位:元 |
| remit_information | 汇款附言 | 字符串.最大长度64.必传 |
| cost_way | 是否全额到账 枚举值 -FULL_AMOUNT: 全额. -UN_FULL_AMOUNT: 非全额. |
枚举 |
| business_code | 业务编码 | 字符串.最大长度8.必传 |
pay_res
付汇情况反馈
| 参数 | 描述 | 约束 |
|---|---|---|
| transfer_fee | 手续费 | 字符串.最大长度20.必传.单位:元 |
| exchange_rate | 付汇手续费 | 字符串.最大长度20.必传. |
pay_order
付款对象
| 参数 | 描述 | 约束 |
|---|---|---|
| mer_order_id | 表示订单号. 商户唯一订单号. | 字符串,最大长度32.最小长度4. |
| trade_no | 附言 | 字符串.必须以USD开头,最小长度24.最大长度27. |
| currency | ISO-4217 交易币种. | 三个大写英文字符 |
| Oamount | 交易金额. | 字符串.最大长度10. 两位小数. |
| payer_name | 持卡人姓名 | 字符串. 加密. |
| payer_id_card | 身份证号码. | 字符串. 加密. |
| payer_phone | 银行预留号码. | 字符串. |
| pri_currency | ISO-4217 支付币种. | 三个大写英文字符 |
| pri_amount | 支付金额. | 字符串.最大长度10. 两位小数. |
| school_name | 学校名称. | 字符串.最大长度256 |
| school_address | 学校地址. | 字符串.最大长度256 |
| school_country | 学校所在国家. | 字符串.最大长度256 |
| oper_status | 审核状态. | 字符串.最大长度4 |
| oper_msg | 审核结果. | 字符串.最大长度256 |
| verify_status | 反洗钱状态. | 字符串.最大长度4 |
| status | U付充值状态. | 字符串.最大长度4 |
| rec_status | 用户充值状态. | 字符串.最大长度4 |
| file_path | 文件地址. | 字符串.最大长度256 |
pay_query_order
付款查询对象
| 参数 | 描述 | 约束 |
|---|---|---|
| rec_status | 用户充值状态. | 枚举值 0: 初始. 1: 充值成功. 2: 充值失败. |
| mer_orderid | 表示订单号. 商户唯一订单号. | 字符串,最大长度32.最小长度4. |
| verify_status | 反洗钱认证状态. | 枚举值 201: 提交待审核. 202: 请求反洗钱成功（文件发送银行成功）. 203: 反洗钱交易成功（文件银行处理完成）. 204: 命中反洗钱. 205: 文件处理异常. 104: 未命中反洗钱. |
| oper_status | 审核状态. | 枚举值 0: 初始，待审核. 1: 审核通过. 2: 审核不通过. |
| oper_msg | 审核结果. | 字符串.最大长度256 |
| fee | 手续费. | 字符串.最大长度10. 两位小数. |
| pay_status | 付汇状态. | 枚举值 1: 待审核（U付下账成功）. 2: 审核中. 99: U付下账失败. 90: U付处理中. 34: 付汇成功. 35: 付汇失败. 36: 付汇未明. |
send_enterprise_qualification
B2B企业资质报送信息
| 参数 | 描述 | 约束 |
|---|---|---|
| cust_code | 统一社会信用代码或组织机构代码. | 字符型.最大长度18(加密).必传 |
| cust_name | 组织机构名称. | 字符型.最大长度128(加密).必传 |
| area_code | 住所/营业场所. | 字符型.最大长度6.必传 必须是行政区划表中存在的记录，但不能选100000 |
| cust_addr | 公司注册地址. | 字符型.最大长度200(加密). |
| industry_code | 行业属性代码. | 字符型.最大长度4.必传 必须是行业属性代码表中存在的最细分类的记录 |
| attr_code | 经济类型代码. | 字符串.最大长度3.必传 必须是经济类型代码表中存在的最细分类的记录 |
| country_code | 常驻国家代码. | 字符串.最大长度3.必传 字母代码，详见字典表国家（地区）代码 |
| is_tax_free | 是否特殊经济区内企业. | 字符串.最大长度1.必传 N-非特殊经济区内企业 Y-特殊经济区内企业 |
| tax_free_code | 企业类型代码. | 字符串.最大长度2.必传 ISTAXFREE=N时只能输入00-一般贸易区，必须是特殊经济区类型代码表中存在的记录； ISTAXFREE=Y时输入除00 以外其他的。见特殊经济区内企业类型 |
| rep_nm | 企业法人名称. | 字符串.最大长度128(加密). |
| cert_type | 企业法人证件类型. | 字符串.最大长度2. 1-身份证 |
| cert_num | 企业法人证件号. | 字符串.最大长度18(加密). |
| phone | 企业法人联系电话. | 字符串.最大长度11(加密). |
| cont_aact | 单位联系人. | 字符型.18(加密).必传 |
| company_phone | 单位联系人电话. | 字符型.最大长度15(加密).必传 |
query_enterprise
企业资质报送请求信息
| 参数 | 描述 | 约束 |
|---|---|---|
| cust_code | 统一社会信用代码或组织机构代码. | 字符型.最大长度18.必传 (加密) |
| cust_name | 组织机构名称. | 字符型.最大长度128. (加密) |
query_enterprise_id
企业资质报送结果信息
| 参数 | 描述 | 约束 |
|---|---|---|
| cust_code | 统一社会信用代码或组织机构代码. | 字符型.最大长度18.必传 作参数时加密 |
| cust_name | 组织机构名称. | 字符型.最大长度128.必传 作参数时加密 |
| cust_no | 商户编号. | 字符串.最大长度8.必传 |
| trace_date | 报送日期. | 字符串.最大长度20.必传 格式yyyy-MM-dd HH:mm:ss |
| area_code | 住所/营业场所. | 字符型.最大长度6.必传 必须是行政区划表中存在的记录，但不能选100000 |
| cust_addr | 公司注册地址. | 字符型.最大长度200. |
| industry_code | 行业属性代码. | 字符型.最大长度4.必传 必须是行业属性代码表中存在的最细分类的记录 |
| attr_code | 经济类型代码. | 字符串.最大长度3.必传 必须是经济类型代码表中存在的最细分类的记录 |
| country_code | 常驻国家代码. | 字符串.最大长度3.必传 字母代码，详见字典表国家（地区）代码 |
| is_tax_free | 是否特殊经济区内企业. | 字符串.最大长度1.必传 N-非特殊经济区内企业 Y-特殊经济区内企业 |
| tax_free_code | 企业类型代码. | 字符串.最大长度2.必传 ISTAXFREE=N时只能输入00-一般贸易区，必须是特殊经济区类型代码表中存在的记录； ISTAXFREE=Y时输入除00 以外其他的。见特殊经济区内企业类型 |
| rep_nm | 企业法人名称. | 字符串.最大长度128. |
| cert_type | 企业法人证件类型. | 字符串.最大长度2. 1-身份证 |
| cert_num | 企业法人证件号. | 字符串.最大长度18. |
| phone | 企业法人联系电话. | 字符串.最大长度11. |
| status | 申报状态. | 字符串.最大长度1.必传 0-未申报 1-申报成功 9-处理中 3-申报失败 |
| desc | 申报状态描述. | 字符串.最大长度600.必传 |
b2bouter_order
交易明细信息
| 参数 | 描述 | 约束 |
|---|---|---|
| mer_batchno | 商户批次号 | 字符型.最大长度16.必传 |
| mer_orderId | 商户订单号 | 字符串.最大长度64.必传 |
| contract_no | 交易合同号或订单号 | 字符串.最大长度128.必传 |
| contract_date | 合同日期 | 字符串.最大长度8.必传 格式:YYYYMMDD |
| business_code | 业务编码 | 字符串.最大长度8.必传 |
| val_pattern | 计价方式 枚举值 | 枚举 .必传 -CNY_VALUATION: 人民币计价. -FOREIGN_VALUATION: 外币计价. -RMB_PAYMENT: 跨境人民币付款. |
| currency | 币种 | 字符串.固定长度3.必传 |
| Damount | 交易金额 | 字符串.最大长度12 .必传. 计价类型为外币计价时，该金额为外币金额。计价类型为人民币计价时，该金额为人民币金额 |
| order_sub_type | 交易标识 | 业务编码为01121990，01122030时需要填入（代号：1服装、2食品、3电子产品、4 其他 ）业务编码为服务贸易项下时需要填入（5酒店住宿、6机票、7留学、8其他）.必传 |
| logistics_no | 物流单号 | 字符串.最大长度64.必传 |
payment_sub
付款单报送信息
| 参数 | 描述 | 约束 |
|---|---|---|
| mer_batchno | 商户批次号 | 字符型.最大长度16.必传 |
| payee_account | 收款方账号 | 字符串(加密).必传 |
| business_code | 业务编码 | 字符串.最大长度8.必传 |
| currency | 币种 | 字符串.最大长度3.必传 |
| val_pattern | 计价方式 枚举值 | 枚举 .必传 -CNY_VALUATION: 人民币计价. -FOREIGN_VALUATION: 外币计价. -RMB_PAYMENT: 跨境人民币付款. |
| remit_information | 汇款附言 | 字符串.最大长度64.必传 |
| Oamount | 交易金额 | 字符串.最大长度12.必传 |
| cost_way | 是否全额到账 | 枚举.必传枚举值 -FULL_AMOUNT: 全额. -UN_FULL_AMOUNT: 非全额. |
query_order
付款单交易查询信息
| 参数 | 描述 | 约束 |
|---|---|---|
| trade_no | 第三方系统交易号. | 字符串.最大长度20.必传 |
| fee | 手续费. | 字符串.最大长度12.必传 |
| buy_rate | 购汇汇率. | 字符串.最大长度8. 只有在外币交易中才有该值 |
| pay_amt | 付款金额. | 字符串.最大长度12. 必传 |
| payee_account | 收款方账号. | 字符串.最大长度32.必传 |
| payee_name | 收款方名称. | 字符串.最大长度200.必传 |
| currency | 交易币种. | 字符串.最大长度3.必传 |
| trace_date | 交易日期. | 字符串.最大长度20.必传 格式yyyy-MM-dd HH:mm:ss |
6. 错误码
API使用如下错误码:
| 错误码 | 描述 |
|---|---|
| 400 | 请求错误 – 请求中有语法问题，或不能满足请求 |
| 401 | 未授权 – 未授权客户机访问数据 |
| 403 | 禁止访问 – 即使有授权也不需要访问 |
| 404 | 资源未找到 – 服务器找不到给定的资源 |
| 405 | 请求方法不被允许 – 您尝试使用不可用的请求方法请求服务器 |
| 406 | 不接受 – 您请求的数据格式不是json |
| 410 | 永远不可用 – 服务永远不可用 |
| 429 | 请求次数过多 – 您请求次数过多! 减少请求次数! |
| 500 | 服务器错误 – 服务器出错. 请稍后尝试. |
| 503 | 服务不存在 – 服务已经离线. 请稍后尝试. |
7. 常见问答
UMF相关
什么是联动国际?
联动国际 (美国, “仲裁”) 是移动结合金融技术公司的子公司, 在深圳上市, 中国支付和金融领域领导者. 2015年, 联动国际收到中国国家外汇管理局颁发的跨境货币转换许可证. 更多细节请参见 联动优势
UMF取得哪些证书?
UMF在中国取得了人民银行颁发的支付业务许可证（全国互联网支付、移动电话支付、银行卡受理）, 中国证监会基金支付结算业务许可证, 国家外汇管理局的跨境外汇支付试点资格和人民银行跨境人民币支付试点资格.
- 人民银行的支付业务许可证 – 跨境人民币
- 中国证监会基金销售结算许可证
- 北京安全领域跨境人民币支付先锋企业单位
- 工信部跨区增值电信业务牌照
- 工信部（工业和信息化部）短信验证码接入使用
- 北京通信管理局电信和信息服务业务许可证（北京ICP认证）
- 支付卡行业（PCI）数据（PCI DSS）
政策
为什么UMF需要每笔付款的细节?
由于中国国家外汇管理局的要求，每一笔交易都需要详细的信息来证明它是真实的交易.
文件相关内容如下:
第19条.支付机构办理跨境外汇支付业务时，应获得真实交易信息，按照完整性和可追溯性原则收集每笔交易的详细数据，并保留备查.
货物贸易的详细数据在原则上应包括商品的名称和数量, 币种, 金额以及交易的双方,来源和订单时间; 服务贸易的详细数据在原则上应包括服务的类型, 具体交易信息(如机票预定时间、机票时间、酒店名称、住宿时间、留学签证等),数量,交易货币,金额,交易各方和他们的地址以及订单日期.
原始文件的链接.
– 英文版
– 中文版
结算费用
UMF支持哪些币种?
UMF支持包括但不限于英镑、港币、美元、日元、加拿大元、澳元、欧元、纽元结算等主要货币. 微信支付将根据当地货币的价格与供应商达成协议。对于不支持的货币，可以通过结算美元来进行贸易.
汇率是如何决定的?
UMF跨境服务使用由中信银行提供的即期汇率.
有两种情况:
– 价格以当地货币为准, 如美元.
当买方在商户平台购买商品时, 买方将按照实时汇率支付人民币. 商户得到美元. UMF每天兑换两次货币. UMF会从中获得收益或损失.
– 价格是人民币.
当买方在商户平台购买商品时, 买方支付人民币. 商户得到人民币. UMF每天兑换两次货币. UMF会从中获得收益或损失.
8. 附录
交易代码及交易附言描述
| 业务编码 | 业务类型 | 交易编码 | 交易附言 |
|---|---|---|---|
| 01122030 | 货物贸易 | 122030 | 网络购物 |
| 02223022 | 留学 | 223022 | 留学及教育相关旅行（一年以上）学费 |
| 02223023 | 留学 | 223023 | 留学及教育相关旅行（一年及一年以下）学费 |
| 03222024 | 机票 | 222024 | 跨境机票款 |
| 03223010 | 机票 | 223010 | 公务及商务旅行机票 |
| 03223021 | 机票 | 223021 | 就医及健康相关旅行机票 |
| 03223022 | 机票 | 223022 | 留学及教育相关旅行（一年以上）机票 |
| 03223023 | 机票 | 223023 | 留学及教育相关旅行（一年以下）机票 |
| 03223029 | 机票 | 223029 | 其他私人旅行机票 |
| 04223010 | 酒店 | 223010 | 留学及教育相关旅行（一年以下）酒店 |
| 04223021 | 酒店 | 223021 | 其他私人旅行酒店 |
| 04223022 | 酒店 | 223022 | 公务及商务旅行酒店 |
| 04223023 | 酒店 | 223023 | 就医及健康相关旅行酒店 |
| 04223029 | 酒店 | 223029 | 留学及教育相关旅行（一年以上）酒店 |
| 05227010 | 话费充值服务 | 227010 | 移动电讯服务 |
| 06223010 | 旅游 | 223010 | 公务及商务旅行 |
| 06223021 | 旅游 | 223021 | 就医及健康相关旅行 |
| 06223022 | 旅游 | 223022 | 留学及教育相关旅行（一年以上） |
| 06223023 | 旅游 | 223023 | 留学及教育相关旅行（一年及一年以下） |
| 06223029 | 旅游 | 223029 | 其他私人旅行 |
| 07222012 | 运输 | 222012 | 涉及我国进口的海洋货运服务 |
| 07222022 | 运输 | 222022 | 涉及我国进口的空中货运服务 |
| 07222032 | 运输 | 222032 | 涉及我国进口的其他运输方式货运服务 |
| 08227020 | 软件服务 | 227020 | 软件服务 |
| 08231030 | 软件服务 | 231030 | 复制或分销计算机软件许可费 |
| 09228025 | 国际展览 | 228025 | 展会服务 |
| 00228024 | 广告服务 | 228024 | 广告服务 |
返回码描述
| 编号 | 返回码 | 描述 |
|---|---|---|
| 1 | 0000 | 成功 |
| 2 | 00060999 | 系统失败 |
错误交易码描述
| 编号 | 错误码 | 描述 |
|---|---|---|
| 1 | 0000 | 支付交易成功 |
| 2 | 00060076 | 不支持的银行卡账户 |
| 3 | 00060112 | 请重新输入用户的姓名 |
| 4 | 00060114 | 商户权限受限 |
| 5 | 00060305 | 无效卡号 |
| 6 | 00060306 | 卡被锁定，无法处理支付 |
| 7 | 00060309 | 您的订单金额超过单笔交易限额，订单支付失败。 |
| 8 | 00060310 | 用户未开通该商户协议 |
| 9 | 00060405 | 支付密码输入错误超过三次 |
| 10 | 00060490 | 用户一天的总订单金额大于一次订单的最大限额 |
| 11 | 00060544 | 支付金额超过银行允许的最大限额请与您的银行联系 |
| 12 | 00060550 | 支付被银行拒绝 |
| 13 | 00060700 | 数据校验未通过 |
| 14 | 00060702 | 超时 |
| 15 | 00060710 | 商户签名验签失败 |
| 16 | 00060711 | 商户未开通 |
| 17 | 00060720 | 用户手机号错误 |
| 18 | 00060721 | 用户未开通该银行 |
| 19 | 00060722 | 请重新选择支付银行 |
| 20 | 00060723 | 支付密码错误请重新输入 |
| 21 | 00060724 | 支付密码错误次数超过3次，支付失败。 |
| 22 | 00060740 | 生成支付订单失败 |
| 23 | 00060750 | 支付失败 |
| 24 | 00060751 | 支付超时被冲正 |
| 25 | 00060760 | 支付不存在 |
| 26 | 00060761 | 订单正在支付中请稍后 |
| 27 | 00060762 | 订单已过期请重新下单 |
| 28 | 00060763 | 订单已关闭 |
| 29 | 00060764 | 订单未支付，请继续支付 |
| 30 | 00060765 | 支付失败请重新选择支付方式 |
| 31 | 00060766 | 不允许退款 |
| 32 | 00060767 | 退款请求处理失败 |
| 33 | 00060768 | 退款金额与支付金额不一致 |
| 34 | 00060774 | 累计退款金额大于支付金额 |
| 35 | 00060778 | 退款记录不存在 |
| 36 | 00060780 | 支付成功，无需再次支付 |
| 37 | 00060861 | 财务处理中 |
| 38 | 00060874 | 该时间段不允许退费［ 23:45~00:25 ］ |
| 39 | 00060920 | 商户[]不支持T+0退款 |
| 40 | 00060931 | 退费结果不明 |
| 41 | 00060999 | 系统罢工 |
| 42 | 00071024 | 交易不能完成请与发卡银行联系 |
| 43 | 00071039 | 交易不被允许 |
| 44 | 00080530 | 亲，您的银行卡已过期或有效期错误，无法完成交易，详情请咨询发卡行 |
| 45 | 00080531 | 由于银行卡过期或到期日错误导致交易失败，请与发卡银行联系 |
| 46 | 00080534 | 错误的电话号码或CVV2 |
| 47 | 00080535 | 银行卡信息和身份证号不匹配 |
| 48 | 00080537 | 交易失败请与发卡银行联系 |
| 49 | 00080541 | 支付超时 |
| 50 | 00080542 | 交易被银行拒绝 |
| 51 | 00080545 | 输入无效卡密码超过限制 |
| 52 | 00080557 | 银行返回失败 |
| 53 | 00080559 | 交易失败请与开卡行联系 |
| 54 | 00080711 | 验证码已失效 |
| 55 | 00080722 | 验证码已过期 |
| 56 | 00080730 | 交易已被取消 |
| 57 | 00080732 | 不支持该类卡交易，请更换银行卡 |
| 58 | 00080748 | 卡类型不支持，请换另一张银行卡 |
| 59 | 00081550 | 订单数量大于允许的最大数量 |
| 60 | 00090020 | 银行卡过期或有效期错误 |
| 61 | 00090021 | 支付失败 |
| 62 | 00090230 | 交易不支持 |
| 63 | 00090239 | 银行卡有错误 |
| 64 | 00090255 | 用户的银行不支持此交易 |
| 65 | 00090361 | 超过每日交易的最大限额 |
| 66 | 00090362 | 这个交易有个错误 |
| 67 | 00090388 | 因风控导致支付失败 |
| 68 | 00090412 | 没有找到交易记录 |
| 69 | 00090470 | 超过每份订单的订单金额限制 |
| 70 | 00090504 | 银行网络错误 |
| 71 | 00090511 | 交易拒绝 |
| 72 | 00131040 | 交易失败请与开卡行联系或稍后再试 |
| 73 | 00131072 | 账户余额不足，请确认后再试！ |
| 74 | 00160079 | 电话号码和姓名不匹配 |
| 75 | 00160080 | 电话号码和银行卡号不匹配 |
| 76 | 00180008 | 支付结果不明，请稍后查询 |
| 77 | 00180018 | 订单状态异常，请重新支付 |
| 78 | 00200005 | 没有找到相关短信验证码 |
| 79 | 00200013 | 商户未开通该银行 |
| 80 | 00200014 | 错误请稍后尝试 |
| 81 | 00200025 | 验证失败 |
| 82 | 00200029 | 系统通信异常 |
| 83 | 00200073 | 卡验证失败 |
| 84 | 00200075 | 银行卡类型与支付方式不匹配 |
| 85 | 00200076 | 商户尚未开通此服务 |
| 86 | 00200077 | 无法生成订单 |
| 87 | 00200078 | 支付订单不存在 |
| 88 | 00200079 | 订单超时 |
| 89 | 00200080 | 订单关闭 |
| 90 | 00200081 | 查询交易记录不存在 |
| 91 | 00200082 | 超过验证代码请求的限制 |
| 92 | 00200083 | 验证码输入不正确 |
| 93 | 00200084 | 超过不正确验证代码的限制时间 |
| 94 | 00200085 | 验证码不正确 |
| 95 | 00200086 | 验证码一分钟内只可获取一次 |
| 96 | 00200088 | 多次验证码错误 |
| 97 | 00200089 | 不匹配的电话号码 |
| 98 | 00200090 | 无效的验证代码 |
| 99 | 00200091 | 处理中不能取消 |
| 100 | 00200092 | 取消金额和支付金额不匹配 |
| 101 | 00200093 | QR码过期了 |
| 102 | 00200094 | QR码过期了 |
| 103 | 00200096 | 退费已受理(refund_state=[REFUND_SUCCESS]),不可重复申请 |
| 104 | 00202000 | 汇率查询响应参数有误 |
| 105 | 00202001 | 订单外币金额不能为空 |
| 106 | 00202002 | 身份证号不存在，请核实后再输入 |
| 107 | 00202003 | 订单外币金额必须大于0 |
| 108 | 00202004 | 货物订单时必填数据不完整 |
| 109 | 00202005 | 银行卡号输入有误 |
| 110 | 00202006 | 姓名太长或不是中文 |
| 111 | 00202007 | 身份证号和银行卡号不匹配 |
| 112 | 00202008 | 跨境订单扩展表不存在 |
| 113 | 00202009 | 身份证号输入不正确 |
| 114 | 00202010 | 商户传入订单金额与原订单金额不一致,退费失败 |
| 115 | 00202011 | 商户传入订单币种[USD]与原订单币种[CNY]不一致,不允许退费 |
| 116 | 00202012 | 不支持的海关 |
| 117 | 00202013 | 海关信息已更新,不可再次更新 |
| 118 | 00202016 | 货物信息不存在 |
| 119 | 00202017 | 支付类型不正确 |
| 120 | 00202018 | 未传递必传支付要素 |
| 121 | 00202019 | 商户该日子订单号重复 |
| 122 | 00202020 | 商户该日同一笔子订单中的货物编号重复 |
| 123 | 00202021 | 请求国政通实名鉴权异常 |
| 124 | 00202022 | 重复下单，子订单信息与原订单子单信息不一致 |
| 125 | 00202023 | 订单金额超过外管单笔交易限额 |
| 126 | 00202024 | 组织业务编码错误 |
| 127 | 00202025 | 业务编码未配置 |
| 128 | 00202026 | 规定时间内不支持退费 |
| 129 | 00210008 | 格式不正确的 |
| 130 | 00210028 | 卡信息不匹配 |
| 131 | 00210037 | 信息不正确或没有开通网上支付 |
| 132 | 00210040 | 亲，银行系统出现故障了，银行工程师正在努力恢复…..，请您稍后再试 |
| 133 | 00210051 | 错误的用户名 |
| 134 | 00210059 | 错误的卡片信息 |
| 135 | 00210077 | 超出银行每日交易金额的限额 |
| 136 | 00230001 | 订单日期不匹配 |
| 137 | 00230005 | 字段太长 |
| 138 | 00230006 | 订单状态不匹配 |
| 139 | 00230009 | 交易状态不匹配 |
| 140 | 00230012 | 交易终止 |
| 141 | 00230017 | 错误的订单日期 |
| 142 | 00252001 | 交易失败，由于被禁止的帐户 |
| 143 | 00252002 | 交易失败，由于禁止银行卡 |
| 144 | 00252003 | 交易失败，由于禁用用户ID |
| 145 | 00252004 | 交易失败，由于被禁止的商户 |
| 146 | 00252006 | 交易失败，由于被禁止支付产品 |
| 147 | 00252007 | 交易失败，由于被禁止的电话号码 |
| 148 | 00252008 | 交易失败，由于被禁止的身份证号码 |
| 149 | 00252009 | 交易失败，由于被禁止的终端ID |
| 150 | 00252010 | 交易失败，由于被禁止的IP地址 |
| 151 | 00253001 | 在一小时内超过最大交易限额 |
| 152 | 00253002 | 超过当日最大交易限额 |
| 153 | 00253003 | 在30天内超过最大交易限额 |
| 154 | 00253010 | 用户的电话号码在1小时内超过最大交易限额 |
| 155 | 00253011 | 用户的电话号码超过一天内最大交易限额 |
| 156 | 00253012 | 用户的电话号码在30天内超过最大交易限额 |
| 157 | 00253022 | 在一小时内超过此卡的最大交易限额 |
| 158 | 00253024 | 超过该卡30天内的最大交易限额 |
| 159 | 00253034 | 这个电话号码超过了每小时最大交易限额 |
| 160 | 00253035 | 您的手机号在该商户1天内累计交易金额超限 |
| 161 | 00253036 | 这个电话号码超出了每月最大交易限额 |
| 162 | 00253044 | 您的订单金额超过该商户单笔交易限额 |
| 163 | 00253048 | 订单金额大于第一次订单的最大限额 |
| 164 | 00253049 | 新用户的电话号码超过每小时最大交易限额 |
| 165 | 00253052 | 新用户的电话号码超过了每笔交易限额 |
| 166 | 00254001 | 这个电话号码超过了每小时的最大交易频次 |
| 167 | 00254002 | 这个电话号码超过了每天最大的交易频次 |
| 168 | 00254003 | 这个电话号码超过了每月最大交易频次 |
| 169 | 00254014 | 超过一天内的最大交易频次 |
| 170 | 00254015 | 在30天内超过最大交易频次 |
| 171 | 00254022 | 此卡每小时超过最大交易频次 |
| 172 | 00254023 | 此卡超过每日最大交易频次 |
| 173 | 00254024 | 此卡每30天超过最大交易频次 |
| 174 | 00254028 | 在1小时内超过最大交易频次 |
| 175 | 00254029 | 在一天内超过最大交易频次 |
| 176 | 00254037 | 新用户超过了每小时交易频次 |
| 177 | 00254038 | 新用户超过了每天交易频次 |
| 178 | 00255003 | 多次账户余额不足因风控而拒绝支付 |
| 179 | 00280036 | 商户未开通该币种 |
| 180 | 00280037 | 请求跨境更新报关信息接口数据校验未通过 |
| 181 | 00280038 | 商户未开通报关 |
| 182 | 00280039 | 商户未开通货物业务 |
| 183 | 00280040 | mer_cust_id、usr_busi_agreement_id必传其一 |
| 184 | 00280041 | pay_type字段值不合法 |
| 185 | 00280042 | 传递用户业务协议号与商户用户标识字段对应关系不一致 |
| 186 | 00280043 | 该订单已报送海关 |
| 187 | 00280044 | 订单信息有误 |
| 188 | 00280045 | 该笔单未报送 |
| 189 | 00280046 | 该笔单已报送待处理 |
| 190 | 00280047 | 该笔订单报关失败 |
| 191 | 00280048 | 该笔子订单不为货物，不可报国检 |
| 192 | 00280049 | 该订单已报送国检,国检处理中 |
| 193 | 00280050 | 该订单已报送国检成功,无需再次报送 |
| 194 | 00280051 | 报检日期在订单日期30天外 |
| 195 | 00280052 | 国检编码不合法 |
| 196 | 00280053 | 该商户未配置 |
| 197 | 00280054 | 该商户未开通任何银行通道 |
| 198 | 00280055 | 商户配置该通道不支持该币种 |
| 199 | 00280056 | 商户未配置独立报关手续费 |
| 200 | 00280057 | 商户未开通独立报关 |
| 201 | 00280058 | 该笔订单已经存在 |
| 202 | 00280059 | 文件不存在 |
| 203 | 00280064 | 报送海关数据为空，不允许报送国检 |
| 204 | 00280065 | 订单金额大于不发短信设定金额 |
| 205 | 00280066 | 银行未签约 |
| 206 | 00281017 | 商户未开通该币种 |
| 207 | 00282014 | 是否报关为N,但却要求更新海关信息 |
| 208 | 00282015 | 无相应子订单信息 |
| 209 | 00282016 | 无相应商品信息表信息 |
| 210 | 00283087 | 【商户配置查询】商户无效 |
| 211 | 00284003 | 实名认证格式错误 |
| 212 | 00290502 | 身份信息不匹配 |
| 213 | 00290508 | 验证信息不匹配 |
| 214 | 00290511 | 银行卡和持卡人不匹配 |
| 215 | 00290512 | 电话号码不匹配 |
| 216 | 00290521 | 身份证类型不支持 |
| 217 | 00280702 | 传入数据不符合正则表达式 |
| 218 | 00284000 | 实名认证请求异常 |
| 219 | 00284001 | 实名认证失败 |
| 220 | 00284002 | 实名认证请求超时 |
| 221 | 00060406 | 根据商户用户标识未查询到对应用户 |
| 222 | 00060124 | 业务协议依赖的支付协议关系不存在 |
| 223 | 00160108 | 该卡已签约 |
| 224 | 00060072 | 协议不存在 |
| 225 | 00210011 | 手机号验证失败 |
| 226 | 00280701 | 有效期必填 |
| 227 | 00280703 | token已过期 |
| 228 | 00202012 | 该银行卡没开通在线支付 |
| 229 | 00160107 | 您输入的银行卡信息有误 |
| 230 | 00290010 | 身份证字段为空或格式不符 |
| 231 | 00281019 | 商户未开通 |
交易状态说明
| 编号 | 枚举名称 | 说明 | 备注 |
|---|---|---|---|
| 1 | WAIT_BUYER_PAY | 交易创建,等待买家付款. | |
| 2 | TRADE_SUCCESS | 交易成功,不能再次进行交易. | |
| 3 | TRADE_CLOSED | 交易关闭,在指定时间段内未支付时关闭的交易. | |
| 4 | TRADE_FAIL | 交易失败 |
退费状态说明
| 编号 | 枚举名称 | 说明 | 备注 |
|---|---|---|---|
| 1 | REFUND_SUCCESS | 退费成功 | |
| 2 | REFUND_CLOSE | 退费关闭 | |
| 3 | REFUND_PROCESS | 退费处理中 | |
| 4 | REFUND_FAIL | 退费失败 |
货币代码
| 编号 | 币种编码 | 币种描述 |
|---|---|---|
| 1 | CNY | 人民币 |
| 2 | HKD | 港币 |
| 3 | USD | 美元 |
| 4 | EUR | 欧元 |
| 5 | JPY | 日元 |
| 6 | GBP | 英镑 |
| 7 | AUD | 澳大利亚元 |
| 8 | CAD | 加拿大元 |
| 9 | NZD | 新西兰元 |
| 10 | SGD | 新加坡元 |
| 11 | MOP | 澳门元 |
| 12 | CHF | 瑞士法郎 |
| 13 | SEK | 瑞典克朗 |
| 14 | DKK | 丹麦克朗 |
| 15 | NOK | 挪威克朗 |
银行列表(支持信用卡支付)
| 编号 | 银行代码 | 银行名称 |
|---|---|---|
| 1 | ICBC | 中国工商银行 |
| 2 | CCB | 中国建设银行 |
| 3 | ABC | 中国农业银行 |
| 4 | BOC | 中国银行 |
| 5 | PSBC | 中国邮政储蓄银行 |
| 6 | CITIC | 中信银行 |
| 7 | CEB | 光大银行 |
| 8 | HXB | 华夏银行 |
| 9 | CMBC | 中国民生银行 |
| 10 | CMB | 招商银行 |
| 11 | BEA | 东亚银行 |
| 12 | CIB | 兴业银行 |
| 13 | NBB | 宁波银行 |
| 14 | SPDB | 上海浦东发展银行 |
| 15 | GDB | 广东发展银行 |
| 16 | SPAB | 平安银行 |
| 17 | BSB | 包商银行 |
| 18 | CSCB | 长沙银行 |
| 19 | CDRCB | 成都农村商业银行 |
| 20 | CRCB | 重庆农村商业银行 |
| 21 | CQB | 重庆银行 |
| 22 | DLB | 大连银行 |
| 23 | GCB | 广州银行 |
| 24 | GRCB | 广州农村商业银行 |
| 25 | HEBB | 哈尔滨银行 |
| 26 | HZCB | 杭州银行 |
| 27 | JSB | 江苏银行 |
| 28 | DAQINGB | 龙江银行 |
| 29 | SDEB | 顺德农村商业银行 |
| 30 | TZCB | 台州银行 |
| 31 | WZCB | 温州银行 |
| 32 | WRCB | 无锡农村商业银行 |
| 33 | ZJTLCB | 浙江泰隆商业银行 |
| 34 | NJCB | 南京银行 |
| 35 | NCB | 南昌银行 |
| 36 | HSB | 徽商银行 |
| 37 | GDB | 广发银行 |
| 38 | CZSB | 浙商银行 |
| 39 | SHB | 上海银行 |
银行列表(支持借记卡支付)
| 编号 | 银行代码 | 银行名称 |
|---|---|---|
| 1 | SPDB | 上海浦东发展银行 |
| 2 | CCB | 中国建设银行 |
| 3 | ABC | 中国农业银行 |
| 4 | BOC | 中国银行 |
| 5 | CITIC | 中信银行 |
| 6 | CEB | 光大银行 |
| 7 | CMB | 中国招商银行 |
| 8 | ICBC | 中国工商银行 |
| 9 | CMBC | 中国民生银行 |
| 10 | GDB | 广东发展银行 |
| 11 | COMM | 交通银行 |
| 12 | SPAB | 平安银行 |
| 13 | CIB | 兴业银行 |
| 14 | GDB | 广发银行 |
| 15 | CZSB | 浙商银行 |
| 16 | SHB | 上海银行 |
支持海关
| 编号 | 海关代码 | 海关名称 |
|---|---|---|
| 1 | CQZS | 重庆总署 |
| 2 | GZHG | 广州海关 |
| 3 | BJZS | 北京海关 |
| 4 | NB | 宁波海关 |
| 5 | ZZZS | 郑州B保 |
| 6 | QDZS | 青岛海关 |
| 7 | SZHG | 深圳海关 |
| 8 | HZHG | 杭州海关 |
| 9 | SHHG | 上海海关 |
| 10 | FZHG | 福州海关 |
| 11 | PTHG | 平潭海关 |
| 12 | FSHG | 佛山海关 |
| 13 | WHHG | 武汉海关 |
| 13 | FJHG | 福建海关 |
支持国检
| 编号 | 国检代码 | 国检名称 |
|---|---|---|
| 1 | GJHP | 广州黄埔国检 |
| 2 | GJNS | 广州南沙国检 |
9. 付款
付款时序图.
sequenceDiagram
participant 商户
participant UMF
商户-->>UMF: 1.send_payee_infor（收款方信息接口）
UMF-->>商户: 2.返回payee_infor对象
商户-->>UMF: 3.send_order_item（订单明细推送接口）
UMF-->>商户: 4.返回处理结果
商户-->>UMF: 5.confirm_payment（确认付款接口）
UMF-->>商户: 6.返回处理结果
商户-->>UMF: 7.query_payment_status（查询付款状态接口）
UMF-->>商户: 8.返回处理结果
商户-->>UMF: 9.query_rate（查询汇率接口）
UMF-->>商户: 10.返回处理结果
9.1 汇率查询
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/exchange_rate?currency=USD \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f"
//response
{
"meta":{
"sign":"Alc9iDPd4P2z3LzeaZj73aC2fmeHZmlh59d7+MvZoDRYUsOF3lLGe92VhqWhRERvXCBBOK+SarPSI72pj1rHCqTcVd6/hagHKJa/j4k0CodwsrYXhoayLhu6Y/XG7JllyY2pa84J+xLCv/D81KvwWukOpK3MRNf5yq9zrVaVD5E=",
"ret_msg":"Success",
"ret_code":"0000"
},
"exchangeRates":[
{
"rate":"6.9023",
"currency":"USD"
}
]
}
GET: /exchange_rate?currency=USD
获取实时汇率. 返回币种相应数量的人民币.
请求
参数是currency币种代码.
| 参数 | 描述 |
|---|---|
| currency | 字符串. |
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共部分. |
| exchange_rate | 对象，汇率信息. |
9.2 收款方信息
## Request data:
curl -s -X GET https://fx.soopay.net/cberest/v1/send_payee_infor \
-H "Content-Type:application/json" \
-H "Authorization:Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHy/3kv0o7FWFWWy3RpXFFa57SA="
-d '{
"payee_account": "o9pq9xBVv8kuvJD/gtXMlJr/jmIOm4mqqxw/wB8jMPkRgdG3dOZEdRuFg7AMVALAsK5DlC84La8YBDUBY\u003d",
"payee_name": "fwJLwrMZTBf0PwCA2bkXD7H6CMja8UZ/Ozimjt91psfYGrJWOHzKyKcmsh48YkuZIgZ+hXGQotTFkcMXOwOM6edLv\u003d",
"payee_address": "tA2+PM00apliBsqP5Y0b2gMQM8E/Ccfgh+W1Xq7kvJHcN6R7VHbgjwll2f/Tb7LkFFaezu7PHgVgQImcTRiPj6wScjON9DfzhSVf3+FycITU\u003d",
"payee_swift": "fm+tHGiqX80t3fWRfDmaIkgtW3Lu5kUFsPJV4S31A03U/EeImYeZGfgnUQn2ruS2YVzGjDNJIIvj6YTGKMG5Z4wfLtdsWxSNt206wHGEPwKmCbxrTqfdnw5dNI\u003d",
"iban": "ofbx2TBDti7tHp1JIUWR3HG/uFFZ6fwTn4Lh3vAT0BIP7epDDdaVfK3XPggA8qZ2yxwxEfO/HIT2M9usQwL4N7/YKnzkwB6OBt8nN44v8JdAbtek2g\u003d",
"payee_bank_name": "石景山分行",
"payee_bank_address": "中国-银行",
"payee_country": "USA"
}'
## Response data:
{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
}
}
请求
POST: /send_payee_infor
商户付汇之前，需要将付款交易对手（即收款方信息）传递给UMF。否则，付汇交易无法完成。
** 收款方名称+地址不能超过130字符 ** 名称跟地址之前用空格分开
参数
| 参数 | 描述 |
|---|---|
| payee_infor | 对象，收款方信息. |
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
9.3 交易明细推送
## Request data:
curl -s -X GET https://fx.soopay.net/cberest/v1/send_order_item \
-H "Content-Type:application/json" \
-H "Authorization:Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHy/3kv0o7FWFWWy3RpXFFa57SA="
-d '{
"mer_batchno": "1014180108224101",
"business_code": "01122030",
"currency": "USD",
"mer_orderId": "1014180108224102",
"goods_type": "FOOD ",
"goods_name": "Levi\u0027s",
"goods_unitPrice": "120",
"goods_sum": "2",
"Damount": "240",
"payer_name": "qUXPlZaEmiB9XfuS25Izf5g/v3uEIbA4a1GsRH470ogEQbwL98QHMeeT8RSAmjoGEY4m/8Gxxc7zKYU+OA43KdWgi0SJJXyVXQ\u003d",
"payer_IDCard": "pgwCm6N//YnngPcV8dV7Gfg1sk8F5zQTyK46aL8wEm2sDQT0Txa0qnUWyhBchJrYAfNBnEICy67/E9OaYvv/Wc+1ehJNnYcwHaw4c\u003d",
"payer_phone": "13131313131",
"order_time": "2020-10-14 15:06:14",
"pay_time": "2020-10-14 18:01:08",
"val_pattern": "CNY_VALUATION",
"logistics_no": "1014180108436103"
}'
## Response data:
{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
}
}
请求
POST: /send_order_item
商户付汇之前，需要将交易明细数据通过接口传递给UMF。UMF对提交数据进行风控校验。
** 校验规则：批次号不能重复、身份证号是否合法、商品单价*数量是否等于商品交易金额、 业务编码是否合法、手机号是否合法、订单时间与支付时间不能一致
参数
| 参数 | 描述 |
|---|---|
| order_item | 对象，交易明细信息. |
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
9.4 确认付款接口
## Request data:
curl -s -X GET https://fx.soopay.net/cberest/v1/send_order_item \
-H "Content-Type:application/json" \
-H "Authorization:Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHy/3kv0o7FWFWWy3RpXFFa57SA="
-d '{
"mer_batchno": "1014180108224101",
"payee_account": "K1aYGCbsCr/qAsbIwrgYpV/vnijkM7LX1mWzJ70pkK+uguwollWp+9ZALQTTazEW4N1mgZdYtJYuuM4HXYVGVBs\u003d",
"val_pattern": "CNY_VALUATION",
"currency": "USD",
"Oamount": "240",
"remit_information": "success",
"cost_way": "FULL_AMOUNT",
"business_code": "01122030"
}'
## Response data:
{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF/query_payment_status"
}]
}
请求
POST: /confirm_payment
商户发送完订单明细数据、收款方信息数后，可以调用确认付款接口进行外汇汇出。
** 校验规则： 1.商户号+批次号，是否存在对应订单明细数据； 2.商户号+收款方账号，是否存在对应收款方数据； 3.付款金额，要跟订单明细交易金额累计一致；
参数
| 参数 | 描述 |
|---|---|
| confirm_payment | 对象，确认付款信息. |
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| confirm_payment | 对象. 确认付款对象. |
| links | 对象数组. 下一步操作的链接. 取决于支付类型的状态. 链接是HATEOAS链接. |
9.5 查询付款状态接口
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/PAY_GY4DCMJSGYYTINBYHEZTSMBWGEZDAMJYGEYTENWF/query_payment_status \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-d '{
"meta":{
"error_code":"",
"ret_msg":"successful transaction",
"ret_code":"0000"
},
"pay_res":{
"transfer_fee": "150",
"exchange_rate": "7.0156"
}
}'
请求
GET: /{payment_id}/query_payment_status
请求url中的payment_id是在上一步创建的真实payment_id(确认付款).
你可以随时请求该url.
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| pay_res | 对象. 付汇情况反馈对象. |
9.6 错误交易码描述
| 编号 | 错误码 | 描述 |
|---|---|---|
| 1 | 0000 | 交易成功 |
| 2 | 00280070 | 收款方信息接收失败 |
| 3 | 00280071 | 收款方信息已存在 |
| 4 | 00280073 | 订单明细推送失败 |
| 5 | 00280074 | 订单明细已存在 |
| 6 | 00280076 | 付汇处理中，请耐心等候 |
| 7 | 00280077 | 付汇失败—-未找到该批次对应的订单明细信息，请先发送订单明细数据再付汇 |
| 8 | 00280078 | 付汇失败—-未找到该批次对应的收款方信息，请先发送收款方数据再付汇 |
| 9 | 00280079 | 付汇失败—-该批次付汇金额与对应订单明细累加金额不一致 |
| 10 | 00280080 | 付汇失败—-付汇扣款失败，余额不足，请确认U付账户金额充足 |
| 11 | 00280081 | 付汇失败—-银行校验数据失败，请联系运营人员核对付汇信息数据 |
| 12 | 00280083 | 汇率查询失败 |
| 13 | 00280084 | 收款方信息不存在 |
| 14 | 00280085 | 没有找到对应付款订单 |
| 15 | 00280086 | 订单付汇中 |
| 16 | 00280087 | 收款方信息查询结果不唯一 |
9.7 国家编码
| 编号 | 字母代码 | 简称 |
|---|---|---|
| 1 | ALB | 阿尔巴尼亚 Albania |
| 2 | DZA | 阿尔及利亚 Algeria |
| 3 | ARG | 阿根廷 Argentina |
| 4 | ARE | 阿闻酋 United Arab Emirates |
| 5 | ABW | 阿鲁巴 Aruba |
| 6 | OMN | 阿曼 Oman |
| 7 | AZE | 阿塞拜疆 Azerbaijan |
| 8 | EGY | 埃及 Egypt |
| 9 | ETH | 埃塞俄比亚 Ethiopia |
| 10 | IRL | 爱尔兰 Ireland |
| 11 | EST | 爱沙尼亚 Estonia |
| 12 | AND | 安道尔 Andorra |
| 13 | AGO | 安哥拉 Angola |
| 14 | AIA | 安圭拉 Anguilla |
| 15 | ATG | 安提瓜和巴布达 Antigua and Barbuda |
| 16 | AUT | 奥地利 Austria |
| 17 | AUS | 澳大利亚 Australia |
| 18 | MAC | 澳门 Macau |
| 19 | BRB | 巴巴多斯 Barbados |
| 20 | PNG | 巴布亚新几内亚 Papua New Guinea |
| 21 | BHS | 巴哈马 Bahamas |
| 22 | PRY | 巴拉圭 Paraguay |
| 23 | PSE | 巴勒斯坦 Palestine |
| 24 | BHR | 巴林 Bahrain |
| 25 | PAN | 巴拿马 Panama |
| 26 | BRA | 巴西 Brazil |
| 27 | BLR | 白俄罗斯 Belarus |
| 28 | BMU | 百慕大 Bermuda |
| 29 | BGR | 保加利亚 Bulgaria |
| 30 | MNP | 北马里亚纳 Northern Marianas |
| 31 | PLW | 帕劳 Palau |
| 32 | BEN | 贝宁 Benin |
| 33 | CRI | 哥斯达黎加 Costa Rica |
| 34 | GRD | 格林纳达 Grenada |
| 35 | GRL | 格陵兰 Greenland |
| 36 | GEO | 格鲁吉亚 Georgia |
| 37 | GLP | 瓜德罗普 Guadeloupe |
| 38 | GUM | 关岛 Guam |
| 39 | GUY | 圭亚那 Guyana |
| 40 | KAZ | 哈萨克斯坦 Kazakhstan |
| 41 | HTI | 海地 Haiti |
| 42 | KOR | 韩国 Korea,Republic of |
| 43 | NLD | 荷兰 Netherlands |
| 44 | ANT | 荷属安的列斯 Netherlands Antilles |
| 45 | HMD | 赫德岛和麦克唐纳岛 Heard islands and Mc Donald Islands |
| 46 | HND | 洪都拉斯 Honduras |
| 47 | KIR | 基里巴斯 Kiribati |
| 48 | DJI | 吉布提 Djibouti |
| 49 | KGZ | 吉尔吉斯斯坦 Kyrgyzstan |
| 50 | GIN | 几内亚 Guinea |
| 51 | GNB | 几内亚比绍 Guine-bissau |
| 52 | CAN | 加拿大 Canada |
| 53 | GHA | 加纳 Ghana |
| 54 | GAB | 加蓬 Gabon |
| 55 | KHM | 柬埔寨 Cambodia |
| 56 | CZE | 捷克 Czech Repoublic |
| 57 | CMR | 喀麦隆 Cameroon |
| 58 | QAT | 卡塔尔 Qatar |
| 59 | CYM | 开曼群岛 Cayman Islands |
| 60 | CCK | 科科斯(基林)群岛 Cocos(Keeling) Islands |
| 61 | COM | 科摩罗 Comoros |
| 62 | KWT | 科威特 Kuwait |
| 63 | KEN | 肯尼亚 Kenya |
| 64 | COK | 库克群岛 Cook Islands |
| 65 | LVA | 拉脱维亚 Latvia |
| 66 | LSO | 莱索托 Lesotho |
| 67 | LAO | 老挝 Lao |
| 68 | LBY | 利比亚 Libya |
| 69 | SGS | 南乔治亚岛和南桑德韦奇岛 South Georgia and South Sandwich Islands |
| 70 | NRU | 瑙鲁 Nauru |
| 71 | NPL | 尼泊尔 Nepal |
| 72 | NIC | 尼加拉瓜 Nicaragua |
| 73 | NER | 尼日尔 Niger |
| 74 | NGA | 尼日利亚 Nigeria |
| 75 | NIU | 纽埃 Niue |
| 76 | NOR | 挪威 Norway |
| 77 | NFK | 诺福克岛 Norfolk Island |
| 78 | PCN | 皮特凯恩 Pitcairn |
| 79 | PRT | 葡萄牙 Portugal |
| 80 | JPN | 日本 Japan |
| 81 | SWE | 瑞典 Sweden |
| 82 | CHE | 瑞士 Switzerland |
| 83 | SLV | 萨尔瓦多 El Salvador |
| 84 | SEN | 塞内加尔 Senegal |
| 85 | SYC | 塞舌尔 Seychells |
| 86 | SAU | 沙竺阿拉伯 Saudi Arabia |
| 87 | CXR | 圣诞岛 Christmas Island |
| 88 | SHN | 圣赫勒拿 Saint helena |
| 89 | KNA | 圣基茨和尼维斯 Saint Kitts and nevis |
| 90 | LCA | 圣卢西亚 Saint lucia |
| 91 | SMR | 圣马力诺 San Marion |
| 92 | SPM | 圣皮埃尔和密克隆 Saint Pierre and Miquelon |
| 93 | VCT | 圣文森特和格林纳丁斯 Saint Vincent and the Grenadines |
| 94 | LKA | 斯里兰卡 Sri Lanka |
| 95 | SVK | 斯洛伐克 Slovakia |
| 96 | SVN | 斯洛文尼亚 Slovenia |
| 97 | SJM | 斯瓦尔巴岛和扬马延岛 Svalbard and jan Mayen Islands |
| 98 | SWZ | 斯威士兰 Swaziland |
| 99 | SUR | 苏里南 Suriname |
| 100 | SLB | 所罗门群岛 Solomon Islands |
| 101 | TJK | 塔吉克斯坦 Tajikistan |
| 102 | THA | 泰国 Thailand |
| 103 | VGB | 英属维尔京群岛 British Virgin Islands |
| 104 | IOT | 英属印度洋领地 British indian Ocean Territory |
| 105 | JOR | 约旦 Jordan |
| 106 | VNM | 越南 Viet Nam |
| 107 | ZMB | 赞比亚 Zambia |
| 108 | TCD | 乍得 Chad |
| 109 | GIB | 直布罗陀 Gibraltar |
| 110 | CHL | 智利 Chile |
| 111 | CAF | 中非 Central Africa |
| 112 | CHN | 中国 China |
| 113 | TWN | 中国台湾 Taiwan,China |
| 114 | SRB | 塞尔维亚 SERBIA |
| 115 | MNE | 黑山 MONTENEGRO |
| 116 | BEL | 比利时 Belgium |
| 117 | ISL | 冰岛 Iceland |
| 118 | PRI | 波多黎各 Puerto Rico |
| 119 | POL | 波兰 Poland |
| 120 | BOL | 玻利维亚 Bolivia |
| 121 | BWA | 博茨瓦纳 Botswana |
| 122 | BLZ | 伯利兹 Belize |
| 123 | BTN | 不丹 Bhutan |
| 124 | BDI | 布隆迪 Burundi |
| 125 | BVT | 布维岛 Bouvet Island |
| 126 | GNQ | 赤道几内亚 Equatorial Guinea |
| 127 | DNK | 丹麦 Denmark |
| 128 | DEU | 德国 Germany |
| 129 | TMP | 东帝汶 East Timor |
| 130 | TGO | 多哥 Togo |
| 131 | DOM | 多米尼加共和国 Dominican Republic |
| 132 | DMA | 多米尼克 Dominica |
| 133 | RUS | 俄罗斯联邦 Russia Federation |
| 134 | ECU | 厄瓜多尔 Ecuador |
| 135 | ERI | 厄立特里亚 Eritrea |
| 136 | FRA | 法国 France |
| 137 | FRO | 法罗群岛 Faroe Islands |
| 138 | PYF | 法属波利尼西亚 French Polynesia |
| 139 | GUF | 法属圭亚那 French Guiana |
| 140 | ATF | 法属南部领土 French Southern Territo-ries |
| 141 | VAT | 梵蒂冈 Vatican |
| 142 | PHL | 菲律宾 Philippines |
| 143 | FJI | 斐济 Fiji |
| 144 | FIN | 芬兰 Finland |
| 145 | CPV | 佛得角 Cape Verde |
| 146 | GMB | 冈比亚Gambia |
| 147 | COG | 刚果（布） Congo |
| 148 | COL | 哥伦比亚 Colombia |
| 149 | LTU | 立陶宛 Lithuania |
| 150 | LIE | 列支敦士登 Liechtenstein |
| 151 | REU | 留尼汪 Reunion |
| 152 | LUX | 卢森堡 Luxembourg |
| 153 | ROM | 罗马尼亚 Romania |
| 154 | MDG | 马达加斯加 Madagascar |
| 155 | MLT | 马耳他 Malta |
| 156 | MDV | 马尔代夫 Maldives |
| 157 | FLK | 福克兰群岛（马尔维纳斯群岛）Falkland Islands( Malvinas) |
| 158 | MWI | 马拉维 Malawi |
| 159 | MYS | 马来西亚 Malaysia |
| 160 | MLI | 马里 Mali |
| 161 | MHL | 马绍尔群岛 Marshall Islands |
| 162 | MTQ | 马提尼克 Martinique |
| 163 | MYT | 马约特 Mayotte |
| 164 | MUS | 毛里求斯 Mauritius |
| 165 | MRT | 毛里塔尼亚 Mauritania |
| 166 | USA | 美国 United States |
| 167 | ASM | 美属萨摩亚 American Samoa |
| 168 | UMI | 美国本土外小岛屿United States Minor Outlying Islands |
| 169 | VIR | 美属维尔京群岛 United States Virgin Is-lands |
| 170 | MNG | 蒙古 Mongolia |
| 171 | MSR | 蒙特塞拉特 Montserrat |
| 172 | BGD | 孟加拉国 Bangladesh |
| 173 | PER | 秘鲁 Peru |
| 174 | FSM | 密克罗尼西亚联邦 Micronesia，Federated states of |
| 175 | MMR | 缅甸 Myanmar |
| 176 | MDA | 摩尔多瓦 Moldova |
| 177 | MAR | 摩洛哥 Morocco |
| 178 | MCO | 摩纳哥 Monaco |
| 179 | MOZ | 莫桑比克 Mozambique |
| 180 | MEX | 墨西哥 Mexico |
| 181 | NAM | 纳米比亚 Namibia |
| 182 | ZAF | 南非 South Africa |
| 183 | ATA | 南极洲 Antarctica |
| 184 | TZA | 坦桑尼亚 Tanzania |
| 185 | TON | 汤加 Tonga |
| 186 | TCA | 特克斯科斯群岛 Turks and Caicos Islands |
| 187 | TTO | 特立尼达和多巴哥 Trinidad and Tobago |
| 188 | TUN | 突尼斯 Tunisia |
| 189 | TUV | 图瓦卢 Tuvalu |
| 190 | TUR | 土耳其 Turkey |
| 191 | TKM | 土库曼斯坦 Turkmenistan |
| 192 | TKL | 托克劳 Tokelau |
| 193 | WLF | 瓦利斯和富图纳 Wallis and Futuna |
| 194 | VUT | 瓦努阿图 Vanuatu |
| 195 | GTM | 危地马拉 Guatemala |
| 196 | VEN | 委内瑞拉 Venezuela |
| 197 | BRN | 文莱 Brunei Darussalam |
| 198 | UGA | 乌干达 Uganda |
| 199 | UKR | 乌克兰 Ukraine |
| 200 | URY | 乌拉圭 Uruguay |
| 201 | UZB | 乌兹别克斯坦 Uzbekistan |
| 202 | ESP | 西班牙 Spain |
| 203 | ESH | 西撒哈拉 Western Sahara |
| 204 | WSM | 萨摩亚 Samoa |
| 205 | GRC | 希腊 Greece |
| 206 | HKG | 香港 Hong Kong |
| 207 | SGP | 新加坡 Singapore |
| 208 | NCL | 新喀里多尼亚 New Caledonia |
| 209 | NZL | 新西兰 New Zealand |
| 210 | HUN | 匈牙利 Hungary |
| 211 | SYR | 叙利亚 Syria |
| 212 | JAM | 牙买加 Jamaica |
| 213 | ARM | 亚美尼亚 Armenia |
| 214 | YEM | 也门 Yemen |
| 215 | ISR | 以色列 Israel |
| 216 | ITA | 意大利 Italy |
| 217 | IND | 印度 India |
| 218 | IDN | 印度尼西亚 Indonesia |
| 219 | GBR | 英国 United Kingdom |
10. 转账缴费
付款时序图.
sequenceDiagram
participant 商户
participant UMF
商户-->>UMF: 1.upload_files（文件上传接口）
UMF-->>商户: 2.返回文件路径
商户-->>UMF: 3.send_order_item_by_file（下单接口）
UMF-->>商户: 4.返回处理结果
10.1 上传文件
## Request data:
curl -s -X POST https://fx.soopay.net/cberest/v1/upload_files \
-H "Content-Type:application/json" \
-H "Authorization:Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
-d ''
## Response data:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payOrder": {
"file_path": "FILE_PATH_IU5FY43BOZSVYMRQGIYTAOJSHBODSOJZGROHURLENUYEISDSGE4TGNRSFZVHAZZSGAZDCMBZGI4F4"
}
}
请求
POST: /upload_files
商户下单之前，上送交易证明文件
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| pay_order | 对象. 响应的文件路径. |
10.2 下单
## Request data:
curl -s -X GET https://fx.soopay.net/cberest/v1/send_order_item_by_file \
-H "Content-Type:application/json" \
-H "Authorization:Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHy/3kv0o7FWFWWy3RpXFFa57SA="
-d '{
"mer_order_id": "1231231",
"trade_no": "USD210917031802000000009",
"currency": "CNY",
"Oamount": "1000",
"payer_name": "FkRatmzRciUL1OFmx+UYK594V21GPlwJcVRJkNK/P6XlvIUVNkXJJhPRTc19G/Zm/fbmYNqdz3wca/+11XUlnHiIwIckWhedYl+fCGGZYMdRY2kHMGTVrY01uBvLlr3t6VwVUmz4jLqY+dRTE4KSOkYwvQxD/clt92Dl9zrl6zc\u003d",
"payer_id_card": "B4BJboGLpeN/G5WpECL8zjnw1kK9ck9AMCY/uAmm6+jNck6DiySppdcSFqzCWDTZGMp0BSiJU8qQQJ2iTg7Ei+zMvkgMIG4qyXi5eyW7/cAS7aJe4pXFi/UEx2QIBb6x1KF7jSqZZblGpqrQ2gyp/5OawYhOCi5TYM1NjN83r8Y\u003d",
"payer_phone": "15081972822",
"pri_currency": "CNY",
"pri_amount": "15081",
"school_name": "北大",
"school_address": "五道口",
"school_country": "中国",
"file_path": "FILE_PATH_F52XG4RPNVYGC4BPMRQXIYJPHE4TSNBPGIYDEMJQHEYTGL3BFZYG4ZZSGAZDCMBZGEZ2W"
}'
## Response data:
{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"links": [{
"ref": "self",
"method": "GET",
"href": "http://10.10.178.36:8071/spay_rest/PAY_KVJUIMRRGA4TENZQGMYTOMZZGAYDAMBQGAYDAMBQGAZTEMBSGEYDSMRX64/query_payment_order"
}]
}
请求
POST: /send_order_item_by_file
商户下单接口。
参数
| 参数 | 描述 |
|---|---|
| pay_order | 对象，付款对象. |
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
10.3 查询付款状态接口
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/PAY_KVJUIMRRGA4TENZQGMYTOMZZGAYDAMBQGAYDAMBQGAZTEMBSGEYDSMRX64/query_payment_order \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-d '{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"pay_query_order": {
"pay_status": "",
"rec_status": "0",
"fee": "10.35",
"oper_msg": "0923运营审核通过",
"verify_status": "201",
"mer_orderid": "2021091702",
"oper_status": "1"
}
}'
请求
GET: /{payment_id}/query_payment_order
请求url中的payment_id是在上一步创建的真实payment_id(下单).
你可以随时请求该url.
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应的公共信息. |
| pay_query_order | 对象. 付汇情况反馈对象. |
10.4 错误交易码描述
| 编号 | 错误码 | 描述 |
|---|---|---|
| 1 | 0000 | 交易成功 |
| 2 | 00020000 | 数据库错误 |
| 3 | 00060999 | 系统异常 |
| 4 | 00131074 | 订单重复 |
| 5 | 00280077 | 订单信息不存在 |
11. B2B付款
付款时序图.
sequenceDiagram
participant 商户
participant UMF
商户-->>UMF: 1.send_enterprise_qualification（企业资质报送接口）
UMF-->>商户: 2.返回处理结果
商户-->>UMF: 3.query_enterprise_id（企业资质查询接口）
UMF-->>商户: 4.返回query_enterprise_id对象
商户-->>UMF: 5.send_payee_infor（收款方信息报送接口）
UMF-->>商户: 6.返回处理结果
商户-->>UMF: 7.send_b2bouter_order_detail（B2B跨境外币明细上送接口）
UMF-->>商户: 8.返回处理结果
商户-->>UMF: 9.send_b2b_order（确认付款单报送信息接口）
UMF-->>商户: 10.返回处理结果
商户-->>UMF: 11.query_order（付款单交易查询接口）
UMF-->>商户: 12.返回query_order对象
11.1 企业资质报送
## Request data:
curl -s -X POST https://fx.soopay.net/cberest/v1/send_enterprise_qualification \
-H "Content-Type:application/json" \
-H "Authorization:Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHy/3kv0o7FWFWWy3RpXFFa57SA="
-d '{
"cust_code": "FWsnm60dBg6Yc72oBFmG6gsU7OoXV3Tpxs4LIinOruY9v3LgrjoX10wsGllIrGL8vJXJGEZrnEdI8aqqHel/COMLpQB6Sgd4Od6LFpJ63SsrZ+wlALq4Q4BzTs6EoDMit61eZ7Alg7qnoSkF25WRnNz7/4j3ZWt/Jqwgo51Gz+M=",
"cust_name": "k3E0CSruklC/DB6DhapM9ui8fX1Bu2dHyaKCGug70fj2RB5SpJXQ2t5yu/T9riNhfL0xWAQwwJzjYewvq/OZs6vkyf2/QnpLT7Pv0X6TkljqAMtuRYNWOfIJz/Bx8O3eTaCEAZmPUvsmv6IRVZpqcbCgukGpUhPoPWjf0+WCgNI=",
"area_code": "110000",
"country_code": "HKG",
"cust_addr": "hAeB0A/VBzwNlAib+/3j9zNCtd8fOozCl5yht3CKSau3WEgoGwXPYvq6iwBsG6NbBVuVAlhyc/a6Xt0YrncWOoYls/FfT02CXzLHLvjcvUKsjZZawXckSTekhFTameweLUWyPG/qFOJTvFUlbC0alAW/LxodMHYPCH+cCYXYEJI=",
"industry_code": "0105",
"attr_code": "120",
"is_tax_free": "N",
"tax_free_code": "00",
"rep_nm": "YkUjSwcthVMacjQ5B4PgTBzvKYm3lKHeMs8V9WQMzEMRhuuHHUX9pokhrl7QtzN5SEcMxOypxwX3Oid/Ytb7vXIhaNRGv437TKdJl9ifSZo9gOcttyIqNYSlgz0sxvsp/942eFvpnwHeON75uXbtMVv94ljAzwH5KKi47Vq1a2A=",
"cert_type": "1",
"cert_num": "VVeQl4nmm9SpHrKW2REFRU1Dqo0ipxsyjnfDCcxRWXDc7o83WrF6t9ZsMN9NGrH5PeTj8RlLoWrCA7mNoPrR8DIK5Grb+D2sZnuRDahfLduiUmXNJPChqDMt6iPFIAp85iAgn6iCMN1v+y85rI/VpSnt/iuN0DabhU+7jX5pDV0=",
"phone": "ImnZd4cJ+0BzYMHwigkYjq7IwOr0PNbXU2ShGRi3KWbZHPOE6qeRhfcNuPjVlyWhTthtrWUl+N1+tc6lk1r2G8KEMpjqrjZ37jlJQTWg4uaaReoiHSOP5C2AmjoHaP3snt32x8j5ksSrAQRqMKiEdxogYMa4l2oMoGQOCiJMyIA=",
"cont_aact": "ImnZd4cJ+0BzYMHwigkYjq7IwOr0PNbXU2ShGRi3KWbZHPOE6qeRhfcNuPjVlyWhTthtrWUl+N1+tc6lk1r2G8KEMpjqrjZ37jlJQTWg4uaaReoiHSOP5C2AmjoHaP3snt32x8j5ksSrAQRqMKiEdxogYMa4l2oMoGQOCiJMyIA=",
"company_phone": "ImnZd4cJ+0BzYMHwigkYjq7IwOr0PNbXU2ShGRi3KWbZHPOE6qeRhfcNuPjVlyWhTthtrWUl+N1+tc6lk1r2G8KEMpjqrjZ37jlJQTWg4uaaReoiHSOP5C2AmjoHaP3snt32x8j5ksSrAQRqMKiEdxogYMa4l2oMoGQOCiJMyIA="
}'
## Response data:
{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
}
}
请求
POST: /send_enterprise_qualification
商户应该在UMF登记用户,企业的报送状态在创建时为“0”,之后商户应离线向UMF提交所需文件,UMF将向企业开户的银行提交文件,如果验证成功，状态将更改为“1”。
参数
| 参数 | 描述 |
|---|---|
| send_enterprise_qualification | 对象，企业资质报送信息. |
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共部分. |
11.2 企业资质查询
## Request data:
curl -s -X POST https://fx.soopay.net/cberest/v1/query_enterprise_id \
-H "Content-Type:application/json" \
-H "Authorization:Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHy/3kv0o7FWFWWy3RpXFFa57SA="
-d '{
"cust_code": "FWsnm60dBg6Yc73oBFmGDgsU7OoXV3Tpxs4LIinOruY9v3LgrjoX10wsGllIrGL8vJXJGEZrnEdI8aqqHel/COMLpQB6Sgd4Od6LFpJ63SsrZ+wlALq4Q4BzTs6EoDMit61eZ7Alg7qnoSkF25WRnNz7/4j3ZWt/Jqwgo51Gz+M=",
"cust_name": "k5E0CSruklC/DBxDhapM9ui8fX1Bu2dHyaKCGug70fj2RB5SpJXQ2t5yu/T9riNhfL0xWAQwwJzjYewvq/OZs6vkyf2/QnpLT7Pv0X6TkljqAMtuRYNWOfIJz/Bx8O3eTaCEAZmPUvsmv6IRVZpqcbCgukGpUhPoPWjf0+WCgNI="
}'
## Response data:
{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"query_enterprise_id": {
"cust_code": "889956966",
"cust_name": "Hong Kong Kowloon",
"cust_no": "9999",
"trace_date": "2000-01-01 00:00:00",
"area_code": "110000",
"cust_addr": "Kowloon Village, Hong Kong",
"industry_code": "0105",
"attr_code": "120",
"country_code": "HKG",
"is_tax_free": "N",
"tax_free_code": "00",
"rep_nm": "企联动",
"cert_type": "1",
"cert_num": "300000197104106866",
"phone": "18435859788",
"desc": "企业资质信息报送成功！",
"status": "1"
}
}
请求
POST: /query_enterprise_id
查询企业资质报送结果，必须先执行(企业资质报送)
参数
| 参数 | 描述 |
|---|---|
| query_enterprise | 对象，企业资质报送结果信息. |
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共部分. |
| query_enterprise_id | 对象，响应的文件路径. |
11.3 收款方信息报送
## Request data:
curl -s -X POST https://fx.soopay.net/cberest/v1/send_payee_infor \
-H "Content-Type:application/json" \
-H "Authorization:Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHy/3kv0o7FWFWWy3RpXFFa57SA="
-d '{
"payee_account": "o9pq9xBVv8kuvJD/gtXMlJr/jmIOm4mqqxw/wB8jMPkRgdG3dOZEdRuFg7AMVALAsK5DlC84La8YBDUBY\u003d",
"payee_name": "fwJLwrMZTBf0PwCA2bkXD7H6CMja8UZ/Ozimjt91psfYGrJWOHzKyKcmsh48YkuZIgZ+hXGQotTFkcMXOwOM6edLv\u003d",
"payee_address": "tA2+PM00apliBsqP5Y0b2gMQM8E/Ccfgh+W1Xq7kvJHcN6R7VHbgjwll2f/Tb7LkFFaezu7PHgVgQImcTRiPj6wScjON9DfzhSVf3+FycITU\u003d",
"payee_swift": "fm+tHGiqX80t3fWRfDmaIkgtW3Lu5kUFsPJV4S31A03U/EeImYeZGfgnUQn2ruS2YVzGjDNJIIvj6YTGKMG5Z4wfLtdsWxSNt206wHGEPwKmCbxrTqfdnw5dNI\u003d",
"iban": "ofbx2TBDti7tHp1JIUWR3HG/uFFZ6fwTn4Lh3vAT0BIP7epDDdaVfK3XPggA8qZ2yxwxEfO/HIT2M9usQwL4N7/YKnzkwB6OBt8nN44v8JdAbtek2g\u003d",
"payee_bank_name": "石景山分行",
"payee_bank_address": "中国-银行",
"payee_country": "USA"
}'
## Response data:
{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
}
}
请求
POST: /send_payee_infor
报送收款方信息
参数
| 参数 | 描述 |
|---|---|
| payee_infor | 对象，交易明细信息. |
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共部分. |
11.4 B2B跨境外币明细上送
## Request data:
curl -s -X POST https://fx.soopay.net/cberest/v1/send_b2bouter_order_detail \
-H "Content-Type:application/json" \
-H "Authorization:Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHy/3kv0o7FWFWWy3RpXFFa57SA="
-d '{
"mer_batchno": "0824175129019101",
"mer_orderId": "0824175129",
"contract_no": "08241751",
"contract_date": "20201020",
"business_code": "01122030",
"val_pattern": "FOREIGN_VALUATION",
"currency": "USD",
"Damount": "100.25",
"order_sub_type": "4",
"logistics_no": "0824175129019104"
}'
## Response data:
{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
}
}
请求
POST: /send_b2bouter_order_detail
B2B跨境外币明细上送
参数
| 参数 | 描述 |
|---|---|
| b2bouter_order | 对象，交易明细信息. |
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共部分. |
11.5 确认付款单报送信息
## Request data:
curl -s -X POST https://fx.soopay.net/cberest/v1/send_b2b_order \
-H "Content-Type:application/json" \
-H "Authorization:Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHy/3kv0o7FWFWWy3RpXFFa57SA="
-d '{
"mer_batchno": "0817184125159101",
"payee_account": "FWsnm60dBg6Yc73oBFmGDgsU7OoXV3Tpxs4LIinOruY9v3LgrjoX10wsGllIrGL8vJXJGEZrnEdI8aqqHel/COMLpQB6Sgd4Od6LFpJ63SsrZ+wlALq4Q4BzTs6EoDMit61eZ7Alg7qnoSkF25WRnNz7/4j3ZWt/Jqwgo51Gz+M=",
"business_code": "01122030",
"currency": "USD",
"val_pattern": "FOREIGN_VALUATION",
"remit_information": "success",
"Oamount": "100.25",
"cost_way": "UN_FULL_AMOUNT"
}'
## Response data:
{
"meta":{
"ret_msg":"交易成功",
"ret_code":"0000"
},
"links":[
{
"ref":"self",
"method":"GET",
"href":"https://uatfx.soopay.net/cberest/v1/PAY_GA4DCNZRHA2DCMRVGE2TSMJQGEZDEMRSGA4DEOKS/query_order"
}
]
}
请求
POST: /send_b2b_order
确认付款单报送信息
参数
| 参数 | 描述 |
|---|---|
| payment_sub | 对象，交易明细信息. |
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共部分. |
| link | 付汇情况反馈对象. |
11.6 付款单交易查询
## Request data:
curl -s -X GET https://uatfx.soopay.net/cberest/v1/PAY_GA4DCNZRHA2DCMRVGE2TSMJQGEZDEMRSGA4DEOKS/query_order \
-H "Content-Type:application/json" \
-H "Authorization:Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHy/3kv0o7FWFWWy3RpXFFa57SA="
## Response data:
{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"query_order": {
"trade_no": "KJWB202201010001",
"fee": "10",
"buy_rate": "0.8161",
"pay_amt": "77930.71",
"payee_account": "030104060",
"payee_name": "Bank Corporation",
"currency": "HKD",
"trace_date": "2000-01-01 00:00:00"
}
}
请求
GET: /{payment_id}/query_order
查询付款单交易信息
响应
| 参数 | 描述 |
|---|---|
| meta | 对象. 响应公共部分. |
| query_order | 对象，响应的文件路径. |