1. Overview
The UMF REST API uses HTTP methods and a RESTful endpoint structure. The API authorization framework is OAuth 2.0. Merchant format requests in JSON and the APIs return JSON-formatted responses.
1.1 API operations
Use the UMF REST APIs in these environments:
| Environment | Description | Endpoint |
|---|---|---|
| Sandbox - China | Test. For servers in China. Use your test client_id and client_secret to generate an access token to make calls to the Sandbox URIs. | https://uatfx.soopay.net/cberest/v1/ |
| Live - China | Production. For servers in China. Use your live client_id and client_secret to generate an access token to make calls to the Sandbox URIs. | https://fx.soopay.net/cberest/v1 |
To construct a REST call, combine:
- The HTTP method
- The full URI of the resource
- HTTP headers
- The JSON-formatted payload, if required
The Example is listed on the right.
Merchant will get the following information after becaming the partner of UMF.
| Type | Description |
|---|---|
| Merchant rsa private key | For signing the request to UMFinTech |
| UMFinTech public key | For encrypting the sensitive information |
| Merchant client id | For OAuth2 authentication |
| Merchant client secret | For OAuth2 authentication |
1.2 Authentication
The UMFinTech system supports OAuth2. It uses Client Credentials Grant to generate access token. Each merchant has a client_id and a client_secret. Merchant use client_id and client_secret to get the access Token. Each request must be made over HTTPS with access token in the http header.
If you believe either your merchant ID, secret key, or bearer token have been compromised, please regenerate your secret key in the TMS. Once you have a new secret key, a bearer token will be automatically regenerated. Please allow 15 minutes for the new bearer token to propagate through the system.
1.3 HTTP Request
UMF system supports GET and POST requests.
- GET: Inquiry an object or a list of objects.
- POST：Create or update an object.
HTTP head
To make a REST API call, you must include request headers including the Authorization header with an OAuth 2.0 access token.
http get header example:
Content-Type:application/json
Accept-Language:en
Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f
If the request is a POST request, the request headers must include the following information:
- Signature:SignatureOfPostBody
http post header example:
Content-Type:application/json
Accept-Language:zh
Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f
Signature:p+owOiuS9eVrDQIHaP9CwwR89k99+6MdALuetVW9SKpBJvbvQdO8Sx8P1wlgIN9naa9YQeha/oiVhTFh57dtEpE92HU4jsYXZ2aj8puIP6IXbyDG18vr7Qs1sCfdtT7ziXrv31BIIahn6HKZLtVf/fus2NIyO7f2zl+b34In4dM=
1.4 HTTP response
All http responses always are json format string with two parts.
meta：The common information of each response. Includes response message, error code, etc.
result: The entity object(s). The name of “result” is not always “result”, it changes by the entity type and the quantity of objects. For example: If the returned object is a payment object, then the name of result definitely is a “payment” object, and the content is a json object of payment. If the returned objects may be multiple payment objects, then the name of result is “payments”, and the content is a json array of payment.
HTTP status code summary
| Status code | Description |
|---|---|
| 200 - OK | Everything worked as expected. |
| 400 - Bad Request | The request was unacceptable, often due to missing a required parameter. |
| 401 - Unauthorized | No valid API key provided. |
| 402 - Request Failed | The parameters were valid but the request failed. |
| 404 - Not Found | The requested resource doesn’t exist. |
| 409 - Conflict | The request conflicts with another request (perhaps due to using the same idempotent key). |
| 429 - Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |
| 500, 502, 503, 504 - Server Errors | Something went wrong on UMF’s end. (These are rare.) |
1.5 Get an access token
Make an oauth authorize call with your app’s OAuth client_id and client_secret keys for an access token. Set content-type in the request to application/json. In the request body, set grant_type to client_credentials.
Request
POST: /oauth/authorize
Every request must have access_token in the http request header. This interface returns a access_token of current_user. Each token has an expires_in parameter which means this token only available during this period. But if user applies a new access_token, the old one will be disabled immediately.
Parameters:
| Parameter | Description |
|---|---|
| client_id | The client identifier issued to the merchant. |
| client_secret | The secret of client issued to the merchant. |
| grant_type | The type of OAuth authentication request. For this scenario, it must be “client_credentials” . |
Response
The response is a json format string. It include the access_token and expires_in.
Response:
| Parameter | Description |
|---|---|
| expires_in | The remaining lifetime of the access token in seconds. |
| access_token | The access_token. |
1.6 Signature and Verify Signature
Both private key and public key are necessary for DSA or RSA signature.
Both private key and public key are generated with OPENSSL by UMF.
UMF will send the SSL key pair to merchant.
Therefore, merchant uses UMF public key and merchant private key.
Sign for request
All POST requests should have a http head of ‘Signature’. The content of POST should be a JSON string. The merchant private key and the JSON string are used in the RSA signature algorithm by the RSA signature function to get the result string. (the value is given to http header “Signature”).
For Example:
Signature:AWD234SDKEBuYviyhggoopDOUEFLKDSJFI7655DFDFOIUOIulkjj
Sign algorighm:
*Translate JSON String to bytes using UTF8 encoding. *Using SHA256 algorithm to get the hashed bytes of UTF8 encoded bytes. *Using merchant RSA private key to encryte the hash bytes. *Translate hashed bytes to String by base64 encoding.
The last step is the signature of request.
Signature Verification for response
The response of request was signed for security by UMF. The merchant should check the signature after receiving the response.
The response is a JSON string, it has two parts. The first one is “meta”. Signature are included in the “meta” object. The another is a result object(s). The signature is signed based on those objects.
Checking steps:
*Translate result JSON String to bytes using UTF8 encoding.
*Using SHA256 algorithm to get the bytes array of UTF8 encoded bytes.
*Using base64 decoding the signature String to bytes array.
*Use RSA Verification.
1.7 Encrypt all sensitive information
All sensitive information should be encrypted in the http request. The sensitive information includes:
- card number
- card holder’s name
- cvv2
- expiration date (only available for credit card)
- citizen ID number (For Chinese users only)
Encryption algorithm
String -> Bytes(UTF-8 decode) -> Bytes(RSA encrypt by UMFinTech public key) -> String(Base64 encode)
1.8 Date and time format
All Date and DateTime in UMF system are formatted by ISO8601.
DateTime format
YYYY-MM-DDThh:mm:ssTZD
For example:
2016-07-16T19:20:30+01:00
Date format
YYYYMMDD
For example: 20160716
2. Tutorials
2.1 First Call
To make a REST api call：
- Apply a merchant account.
- Get an access token.
- Make an API call.
The following is the flow char of all the steps.
sequenceDiagram
participant Merchant
participant UMF
Merchant-->>UMF: Apply a merchant account
UMF-->>Merchant: Account info
Merchant-->>UMF: Require an access token
UMF-->>Merchant: Return an access token
Note right of Merchant: Using access token to call REST API.
Merchant-->>UMF: Make an API call
UMF-->>Merchant: Return the result
Apply a merchant account
Merchant need to sign a contract with UMF for the rate of service fee and other details.
When the merchant account was approved, UMF will send a email to the merchant. The email will includes the following information:
- UMF RSA public key
- Merchant RSA key pair
- client_id and client_secret of OAuth2
Get an access token
Make a /oauth/authorize call with your app’s OAuth client_id and secret key for the basic authentication values. In the request body, set grant_type to “client_credentials”. When you call Get an access token , UMF generates and returns an access token.
For information about the request headers, see REST API authentication and headers. See the API Get an access token.
Make an API call
With a valid access token in hand, you’re ready to make a request to a REST interface.
The access token is an OAuth bearer token and is included in the header of your requests with the following syntax:
Authorization:Bearer Access-Token
For details on authentication, see Authentication.
2.2 Pay by credit card or debit card
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": "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"
}
}'
## 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"
}]
}
SMS verification
## Request data:
$ 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"
}
}'
## Response data:
{
"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"
}]
}
Execute a payment
## 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"
}]
}
## Non-contractual payment SMS verification
{
"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"
}
}
}
}
## Response data:
{
"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"
}]
}
## Non-contractual payment Execute a payment
{
"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"
}
}
}
}
## Response data:
{
"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"
}]
}
Merchant can request payment in 16 type of currency. The consumer can use chinese credit card and debit card to make payment in RMB. The normally interaction process between merchant and UMF is as follows :
sequenceDiagram
participant Customer
participant Merchant
participant UMF
participant Bank
Customer-->>Merchant: 1. Order goods
Merchant-->>Customer: 2. Generate order
Customer-->>Merchant: 3. Confirm order
Note right of Merchant: If the merchant have an unexpired access token. It can be used to make an API call.
Merchant-->>UMF: 4. Optional. Acquire an access token
UMF-->>Merchant: 5. Return access_token
Note right of Merchant: Using access token to make API call
Merchant-->>UMF: 6. Create a payment
UMF-->>Merchant: 7. Return a payment object
Merchant-->>UMF: 8. Optional. Get available banks
UMF-->>Merchant: 9. Return banks
Merchant-->>Customer: 10. Show the banks to customer.
Customer-->>Merchant: 11. Fill the payment info, acquire verification SMS.
Merchant-->>UMF: 12. Call verification API
UMF-->>Merchant: 13. UMF return a response.
UMF-->>Customer: 14. Send SMS to customer
Customer-->>Merchant:15. Fill the SMS on the checkout page and submit
Merchant-->>UMF: 16. Call payment execution API
UMF-->>Bank: 17. Request deductions
Bank-->>UMF: 18. Deduction result
Note right of Merchant: If the merchant submit the ret_url and notify_url when call Create a payment. UMF will notify the payment result after payment succeed.
UMF-->>Merchant: 19. Payment result notification.
Merchant-->>Customer: 20. Payment result
Explanation of the sequence chart：
- Customer orders goods at merchant platform.
- Merchant generate an order.
- Customer confirm the order.
- Optional. Merchant acquire an access token. This step is optional. If the merchant have an unexpired access_token already, This token can be used to make a API call. Please ignore step 4 and setp 5.
- UMF returns an access token.
- Merchant submit order data to UMF. Call Create a payment.
- UMF return a payment object.
- Optional. Merchant query the availabled banks. The bank list is barely changed. Merchant may cache the result and use the cache to speed up the loading.
- UMF returns the available banks.
- Merchant show the payment page to customer
- Customer select the bank, filling the card info and phone number, acquire a SMS for verification. The phone number must be the same with user regirested in the bank user selected. UMF will check it.
- Merchant call the UMF to send a SMS to customer’s phone number. Call SMS verification.
- UMF returns a response to UMF to confirm that the SMS was sent.
- UMF(or Bank) will send a SMS to customer’s phone.
- Customer fill the received SMS and submit.
- Merchant issues a payment request to the UMF. Call Execute a payment.
- UMF initiates deduction request to the bank.
- UMF receives the result of deduction.
- UMF sends the payment result notification to merchant.
- Merchant shows the result to customer.
And an another interaction process between merchant and UMF is as follows :
sequenceDiagram
participant Customer
participant Merchant
participant UMF
participant Bank
Customer-->>Merchant: 1. Order goods
Merchant-->>Customer: 2. Generate an order
Customer-->>Merchant: 3. Confirm an order
Customer-->>Merchant: 4. Input a bank card number
Note right of Merchant: If the merchant have an unexpired access token. It can be used to make an API call.
Merchant-->>UMF: 5. Optional. Acquire an access token
UMF-->>Merchant: 6. Return access_token
Note right of Merchant: Using access token to make API call
Merchant-->>UMF: 7. Query the bank card information about this card
UMF-->>Merchant: 8. Return a bank object
Merchant-->>UMF: 9. Create a payment with bank_code
UMF-->>Merchant: 10. Return a payment object
Customer-->>Merchant: 11. Fill the payment info, acquire verification SMS.
Merchant-->>UMF: 12. Call verification API
UMF-->>Merchant: 13. UMF return a response.
UMF-->>Customer: 14. Send SMS to customer
Customer-->>Merchant:15. Fill the SMS on the checkout page and submit
Merchant-->>UMF: 16. Call payment execution API
UMF-->>Bank: 17. Request deductions
Bank-->>UMF: 18. Deduction result
Note right of Merchant: If the merchant submit the ret_url and notify_url when call Create a payment. UMF will notify the payment result after payment succeed.
UMF-->>Merchant: 19. Payment result notification.
Merchant-->>Customer: 20. Payment result
Explanation of the sequence chart：
- Customer orders goods at merchant platform.
- Merchant generate an order.
- Customer confirm the order.
- Customer input a bank card number.
- Optional. Merchant acquire an access token. This step is optional. If the merchant have an unexpired access_token already, This token can be used to make a API call. Please ignore step 4 and setp 5.
- UMF returns an access token.
- Merchant query the bank card information about this card.
- UMF return a bank object.
- Merchant submit order data to UMF. Call Create a payment with bank code.
- UMF return a payment object.
- Optional. Merchant query the availabled banks. The bank list is barely changed. Merchant may cache the result and use the cache to speed up the loading.
- UMF returns the available banks.
- Merchant show the payment page to customer
- Customer select the bank, filling the card info and phone number, acquire a SMS for verification. The phone number must be the same with user regirested in the bank user selected. UMF will check it.
- Merchant call the UMF to send a SMS to customer’s phone number. Call SMS verification.
- UMF returns a response to UMF to confirm that the SMS was sent.
- UMF(or Bank) will send a SMS to customer’s phone.
- Customer fill the received SMS and submit.
- Merchant issues a payment request to the UMF. Call Execute a payment .
- UMF initiates deduction request to the bank.
- UMF receives the result of deduction.
- UMF sends the payment result notification to merchant.
- Merchant shows the result to customer.
2.3 Pay by WeChat/Alipay QR Code Payment
## Request data of WeChat QR Code Payment:
$ curl -s -X POST https://fxus.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",
"payer_info":{
"qr_code_scan":{
"citizen_id_type":"1",
"citizen_id_number":"si7BpzrZnesc5rDxdW9PKqfBjB16QcmtYe0PrrwpouT3t7+slULGedgNmChj8sWIkPo=/573zk+jPX6/ojJF8fSBtYMyL/xEjcbzJdkwsKwtla66yjFT9RFE13OJvBVMsDtqQAY0k35KOA+WY4gGJLyCw="
},
"phone":"13581874641",
"name":"s1uD4B5p87OM38yseJyM6C/XoE9iTIsGH+ni7qpzucnePc5rDhQw9PKqfBjs12QcmtYe0P3r3vouT3t7/iIE29FLr2LNkNWBTKjoGfpDuPkw8JMKcQMqTF+4NZla6FwOpe4z0AY="
},
"interface_type":"SERVER_TO_SERVER",
"business_type":"B2C"
},
"order":{
"mer_reference_id":"z201710041119O001",
"mer_date":"20171004",
"amount":{
"total":"0.04",
"currency":"CNY"
},
"order_summary":"test for scan qrcode",
"expire_time":"360",
"sub_orders":[
{
"mer_sub_reference_id":"z201710041119O001S01",
"trans_code":"01122030",
"sub_trans_type":"1",
"amount":{
"total":"0.03",
"currency":"CNY"
},
"is_customs":"TRUE",
"items":[
{
"mer_item_id":"z201710041119O001S01I1",
"type":"FOOD",
"name":"Beef",
"quantity":"2",
"description":"beef",
"amount":{
"total":"0.02",
"currency":"CNY"
}
},
{
"mer_item_id":"z201710041119O001S01I2",
"type":"ELECTRONIC",
"name":"Mac Book Pro",
"quantity":"3",
"description":"Apple Mac Book",
"amount":{
"total":"0.01",
"currency":"CNY"
}
}
]
},
{
"mer_sub_reference_id":"z201710041119O001S02",
"trans_code":"03223010",
"sub_trans_type":"3",
"amount":{
"total":"0.01",
"currency":"CNY"
}
}
]
},
"notify_url":"https://dev.restdemo.umftech.com/restdemo/demo/notifyResultRest",
"risk_info":{
"trans_type":"02",
"goods_type":"1",
"real_name":"0",
"business_type":"Y"
}
}'
## Response data of WeChat QR Code Payment:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"id": "PAY_GM3TCMBQGUYDEMZTGA3DINRWGMZDAMJXGEYDANAB",
"state": "WAIT_BUYER_PAY",
"notify_url": "",
"execute_success_time": "2017-10-05T02:33:52+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=8m5G6Ww"
},
"phone": ""
}
},
"is_from_US": "Y",
"order": {
"amount": {
"total": "0.04",
"currency": "CNY"
},
"sub_orders": [
{
"mer_sub_reference_id": "z201710041119O001S01",
"trans_code": "01122030",
"amount": {
"total": "0.03",
"currency": "CNY"
},
"is_customs": "TRUE",
"items": [
{
"amount": {
"total": "0.02",
"currency": "CNY"
},
"quantity": "2",
"mer_item_id": "z201710041119O001S01I1",
"name": "Beef",
"description": "beef",
"type": "FOOD"
},
{
"amount": {
"total": "0.01",
"currency": "CNY"
},
"quantity": "3",
"mer_item_id": "z201710041119O001S01I2",
"name": "Mac Book Pro",
"description": "Apple Mac Book",
"type": "ELECTRONIC"
}
]
},
{
"mer_sub_reference_id": "z201710041119O001S02",
"trans_code": "03223010",
"amount": {
"total": "0.01",
"currency": "CNY"
}
}
],
"mer_date": "20171004",
"expire_time": "360",
"mer_reference_id": "z201710041119O001",
"order_summary": "test for scan qrcode"
}
},
"links": [
{
"ref": "parent_payment",
"method": "GET",
"href": "https://fxus.soopay.net/cberest/v1/payments/payment/PAY_GM3TCMBQGUYDEMZTGA3DINRWGMZDAMJXGEYDANAB"
},
{
"ref": "apply_to_customs",
"method": "POST",
"href": "https://fxus.soopay.net/cberest/v1/payments/payment/PAY_GM3TCMBQGUYDEMZTGA3DINRWGMZDAMJXGEYDANAB/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": "https://fxus.soopay.net/cberest/v1/payments/payment/PAY_GM3TCMBQGUYDEMZTGA3DINRWGMZDAMJXGEYDANAB/refund"
}
]
}
## Request data of Alipay QR Code Payment:
$ 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/SQQ 1FKVyMBH3vIqWhDRkhoJ43vV3SbVjaLf5Up0+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"
}
}'
## Response data of Alipay QR Code Payment:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"id": "PAY_GM3TAOBRGYYDGMZVHAZTMNZSGIZDAMJXGA4DCNLF",
"state": "WAIT_BUYER_PAY",
"notify_url": "",
"execute_success_time": "2017-08-16T03:35:38+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=34ogWTF"
},
"phone": ""
}
},
"order": {
"amount": {
"total": "0.03",
"currency": "CNY"
},
"sub_orders": [
{
"mer_sub_reference_id": "n98v5p6ra",
"trans_code": "01122030",
"amount": {
"total": "0.02",
"currency": "CNY"
},
"is_customs": "TRUE",
"items": [
{
"amount": {
"total": "0.01",
"currency": "CNY"
},
"quantity": "2",
"mer_item_id": "071815243911",
"name": "Beef",
"description": "beef",
"type": "FOOD"
},
{
"amount": {
"total": "0.01",
"currency": "CNY"
},
"quantity": "3",
"mer_item_id": "071815243912",
"name": "Mac Book Pro",
"description": "Apple Mac Book",
"type": "ELECTRONIC"
}
]
},
{
"mer_sub_reference_id": "4244gwhbp",
"trans_code": "03223010",
"amount": {
"total": "0.01",
"currency": "CNY"
}
}
],
"mer_date": "20170815",
"expire_time": "360",
"mer_reference_id": "o6kaqqg9px",
"order_summary": "test for scan qrcode"
}
},
"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"
}
]
}
Merchant can request payment in 16 type of currency. The consumer can scan the QR-Code by WeChat or Alipay to make payment in RMB. The interaction process between merchant and UMF is as follows :
sequenceDiagram
participant Customer
participant Merchant
participant UMF
participant WeChat/Alipay
Customer-->>Merchant: 1. Order goods
Merchant-->>Customer: 2. Generate order
Customer-->>Merchant: 3. Confirm order
Note right of Merchant: If the merchant have an unexpired access token. It can be used to make an API call
Merchant-->>UMF: 4. Optional. Acquire an access token
UMF-->>Merchant: 5. Return access_token
Note right of Merchant: Using access token to make API call
Merchant-->>UMF: 6. Create a payment
UMF-->>WeChat/Alipay: 7. Payment request
WeChat/Alipay-->>UMF: 8. Return an URL of QR code
UMF-->>Merchant: 9. Return an ali_qr_scan object
Merchant-->>Customer: 10. Show the page of QR code which generated by the URL
Customer-->>WeChat/Alipay: 11. Finish the payment by scanning QR code
WeChat/Alipay-->>UMF: 12. Deduction result
UMF-->>Merchant: 13. Payment result notification
Merchant-->>Customer: 14. Payment result
Explanation of the sequence chart：
- Customer orders goods at merchant platform.
- Merchant generate an order.
- Customer confirm the order.
- Optional. Merchant acquire an access token. This step is optional. If the merchant have an unexpired access_token already, This token can be used to make a API call. Please ignore step 4 and setp 5.
- UMF returns an access token.
- Merchant submit order data to UMF. Call Create a payment.
- UMF sends a payment request to WeChat/Alipay.
- WeChat/Alipay returns an URL of QR code to UMF.
- UMF returns an ali_qr_scan object.
- Merchant show the page of QR code to customer.
- Customer finish the payment by scaning QR code.
- UMF receives the result of deduction.
- UMF sends the payment result notification to merchant.
- Merchant shows the result to customer.
2.4 Pay by Wechat In-App Web-based Payment(link merchant’s public webchat account)
Create a payment
## 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": "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"
}
}'
## Response data:
{
"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"
}
]
}
Merchants push product messages to their followers via Official Account. With WeChat Pay enabled, their followers can purchase products on the shopping page.
sequenceDiagram
participant Consumer
participant WeChat Browser
participant Merchant
participant UMF
participant WeChat
Consumer-->>WeChat Browser: 1.Confirm order
WeChat Browser-->>Merchant: 2. Get open_id
Merchant-->>UMF: 3. Request get open_id url with notify_url
UMF-->>Merchant: 4. Return to notify_url address with getting open_id WeChat url.
Merchant-->>WeChat Browser: 5. Return this url.
WeChat Browser-->>WeChat: 6. Request open_id with return info with merchant’s app_id.
WeChat-->>UMF: 7. Redirect url to UMF
UMF-->>Merchant: 8. Call notify_url which send by Merchant with open_id
Merchant-->>UMF: 9. Create a payment request with open_id
UMF-->>WeChat: 12. Payment request
WeChat-->>UMF: 13. Return payment info
UMF-->>Merchant: 14. Return a WeChat_in_app_web object
Merchant-->>WeChat Browser: 15. Activate payment widget
WeChat Browser-->>WeChat Browser: 16. Call WeChat JS-API
Consumer-->>WeChat: 17. Enter password, finish payment
WeChat-->>WeChat Browser: 18. Return pending info.
WeChat Browser-->>WeChat Browser: 19. Redirect to ret_url.
WeChat-->>UMF: 20. Deduction result.
UMF-->>Merchant: 21. Payment result.
Explanation of the sequence chart：
- Consumer confirms the order.
- WeChat Browser request Merchant systems.
- Consumer authorize merchant to have open_id by request UMF authorization url
- UMF returns the authorization url.
- Merchant redirect to this url.
- The authorization page requests WeChat open_id with merchant’s app_id.
- The WeChat returns the open_id of current WeChat user.
- The authorization page redirect to notify_url(step 3).
- Optional. The Merchat returns a pending page to wait.
- Optional. The pending page request a payment.
- Merchant send payment request to UMF.Call Create a payment.
- UMF sends payment request to WeChat.
- WeChat returns payment info to UMF.
- UMF returns a WeChat_in_app_web object.
- Merchant returns info with WeChat_in_app_web object to browser.
- The return page activates Wechat payment widget(WeChat JS-API).
- Consumer enter password and finish the payment in WeChat explore.
- WeChat return ap pending page.
- The pending page redirect to ret_url(step 11).
- WeChat send the payment result to UMF.
- UMF send the payment result to notify_url by Merchant (step 11).
2.5 Pay by Wechat In-App Web-based Payment(link UMF’s public webchat account)
Create a payment
## 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": "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"
}
}'
## Response data:
{
"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"
}
]
}
Merchants push product messages to their followers via Official Account. With WeChat Pay enabled, their followers can purchase products on the shopping page.
sequenceDiagram
participant Consumer
participant WeChat Browser
participant Merchant
participant UMF
participant WeChat
Consumer-->>WeChat Browser: 1.Confirm order
WeChat Browser-->>Merchant: 2. Get open_id
Merchant-->>UMF: 3. Request get open_id url with notify_url
UMF-->>Merchant: 4. Return to notify_url address with getting open_id WeChat url.
Merchant-->>WeChat Browser: 5. Return this url.
WeChat Browser-->>UMF: 6. Request open_id with return info.
UMF-->>WeChat: 7. Request open_id with return info.
WeChat-->>UMF: 8. return open_id
UMF-->>WeChat Browser: 9. return open_id
WeChat Browser-->>Merchant: 10. Call notify_url which send by Merchant with open_id
Merchant-->>UMF: 11. Create a payment request with open_id
UMF-->>WeChat: 12. Payment request
WeChat-->>UMF: 13. Return payment info
UMF-->>Merchant: 14. Return a WeChat_in_app_web object
Merchant-->>WeChat Browser: 15. Activate payment widget
WeChat Browser-->>WeChat Browser: 16. Call WeChat JS-API
Consumer-->>WeChat: 17. Enter password, finish payment
WeChat-->>WeChat Browser: 18. Return pending info.
WeChat Browser-->>WeChat Browser: 19. Redirect to ret_url.
WeChat-->>UMF: 20. Deduction result.
UMF-->>Merchant: 21. Payment result.
Explanation of the sequence chart：
- Consumer confirms the order.
- WeChat Browser request Merchant systems.
- Consumer authorize merchant to have open_id by request UMF authorization url
- UMF returns the authorization url.
- Merchant redirect to this url.
- The authorization page requests UMF open_id.
- The authorization page requests WeChat open_id.
- The WeChat returns the open_id of UMF.
- The UMF returns the open_id of UMF.
- The authorization page redirect to notify_url(step 3).
- Optional. The Merchat returns a pending page to wait.
- Optional. The pending page request a payment.
- Merchant send payment request to UMF.Call Create a payment.
- UMF sends payment request to WeChat.
- WeChat returns payment info to UMF.
- UMF returns a WeChat_in_app_web object.
- Merchant returns info with WeChat_in_app_web object to browser.
- The return page activates Wechat payment widget(WeChat JS-API).
- Consumer enter password and finish the payment in WeChat explore.
- WeChat return ap pending page.
- The pending page redirect to ret_url(step 11).
- WeChat send the payment result to UMF.
- UMF send the payment result to notify_url by Merchant (step 11).
2.6 Pay by Wechat In-App Payment
Merchants can integrate WeChat Pay SDK into their apps. When users make payment in other apps, WeChat will be authorized to process the payment. Once the transaction is done, the page will redirect to the merchant’s app.
The interface_type of supported have : SERVER_TO_WEB, SERVER_TO_H5WEB
## Request data of WeChat App Code Payment:
$ 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 of WeChat App Code Payment:
{
"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"
}
}
}
sequenceDiagram
participant Customer
participant Merchant App Client
participant Merchant App Server
participant UMF
participant WeChat
Customer-->>Merchant App Client: 1. Order goods
Merchant App Client-->>Customer: 2. Generate order
Customer-->>Merchant App Client: 3. Confirm order
Merchant App Client-->>Merchant App Server: 4. Request for initial a payment
Note right of Merchant App Server: If the merchant have an unexpired access token. It can be used to make an API call
Merchant App Server-->>UMF: 5. Optional. Acquire an access token
UMF-->>Merchant App Server: 6. Return access_token
Note right of Merchant App Server: Using access token to make API call
Merchant App Server-->>UMF: 7. Create a payment with app_id
UMF-->>WeChat: 8. Request WeChat App payment
WeChat-->>UMF: 9. Return JSON string, pay_info
UMF-->>Merchant App Server: 10. Return a WeChat_in_app object
Merchant App Server-->>WeChat: 11. Activate payment widget
WeChat-->>Customer: 12. Payment widget Activated
Customer-->>WeChat: 13. Enter password, finish payment
WeChat-->>UMF: 14. Deduction result
UMF-->>Merchant App Server: 15. Payment result
Merchant App Server-->>Merchant App Client: 16. Payment result
Merchant App Client-->>Customer: 17. Payment result
Explanation of the sequence chart：
- Customer orders goods at merchant platform.
- Merchant App Client generate an order.
- Customer App Client confirm the order.
- Request for initial a payment.
- Optional. Merchant acquire an access token. This step is optional. If the merchant have an unexpired access_token already, This token can be used to make a API call. Please ignore step 4 and setp 5.
- UMF returns an access token.
- Merchant app server submit order data to UMF with app_id. Call Create a payment.
- UMF sends payment request to WeChat.
- WeChat returns payment info to UMF.
- UMF returns a WeChat_in_app object to merchant app server.
- Merchant app server activate Wechat payment widget.
- WeChat payment widget activated.
- Customer enter password and finish the payment in WeChat explore.
- UMF receives the result of deduction.
- UMF sends the result to merchant app server.
- Merchant app server sends the result to merchant app client.
- Merchant app client shows the result to customer.
2.7 Pay by AliPay H5 Payment
H5 payment is to integrate WeChat payment in the third party browser outside of AliPay client. It will call the AliPay client to complete payment once the vendor requests the H5 payment service.
sequenceDiagram
participant Customer
participant Merchant
participant UMF
Customer-->>Merchant: 1. Order goods
Merchant-->>Customer: 2. Generate order
Customer-->>Merchant: 3. Confirm order
Note right of Merchant: If the merchant have an unexpired access token. It can be used to make an API call
Merchant-->>UMF: 4. Optional. Acquire an access token
UMF-->>Merchant: 5. Return access_token
Note right of Merchant: Using access token to make API call
Merchant-->>UMF: 6. Create a payment
UMF-->>Alipay: 7. Payment request
Alipay-->>UMF: 8. Return a payment jump url of AliPay H5
UMF-->>Merchant: 9. Return a AliPay H5 object
Merchant-->>Customer: 10. Show the page of H5 which generated by the URL and the URL will call AliPay Payment()
Customer-->>Alipay: 11. Finish the payment
Alipay-->>UMF: 12. Deduction result
UMF-->>Merchant: 13. Payment result notification
Merchant-->>Customer: 14. Payment result
Explanation of the sequence chart：
- Customer orders goods at merchant platform.
- Merchant App Client generate an order.
- Customer App Client confirm the order.
- Request for initial a payment.
- Optional. Merchant acquire an access token. This step is optional. If the merchant have an unexpired access_token already, This token can be used to make a API call. Please ignore step 4 and setp 5.
- UMF returns an access token.
- Merchant app server submit order data to UMF. Call Create a payment.
- UMF sends payment request to Alipay.
- Alipay returns payment info to UMF.
- UMF returns a Alipay_H5 object to merchant app server.
- Merchant redirecte the page by a Alipay_H5_url link from Alipay_H5
- Alipay payment widget activated.
- Customer enter password and finish the payment in Alipay explore.
- UMF receives the result of deduction.
- UMF sends the result to merchant app server.
- Merchant app server sends the result to merchant app client.
- Merchant app client shows the result to customer.
2.8 Pay by Wechat H5 Payment
H5 payment is to integrate WeChat payment in the third party browser outside of WeChat client. It will call the WeChat client to complete payment once the vendor requests the H5 payment service.
## Request data of WeChat H5 Payment:
$ 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",
"payer_info":{
"phone":"13581874641",
"name":"vOFkjpIvPwrROXTwR/XoE9iTIsGH+EIscUkl6mcAhqiF2gnG1b02wcVk2BC7P8ys1eFfFhBGequLaF1lRaCIUVqMbUGDIzzsbJ9WlYXHARqzlxX/iIE29FLr2LNkNWBTKjoGfpDuPkw8JMKcQMqTF+4NZla6FwOpe4z0AY=",
"wechat_H5":{
"citizen_id_number":"2qRGlObHlp4kcMBJXbSGs67MkoR6CZXgUyLBjIsYskLyXvqLADNZ2/573zk+jPX6/ojJF8fSBtYMyL/xEjcbzJDkwsKwtla66yjFT9RFE13OJvBVM1DtqQAY0k35KOA+WY4gGJLyCw=",
"citizen_id_type":"IDENTITY_CARD"
}
},
"interface_type":"SERVER_TO_SERVER",
"business_type":"B2C"
},
"order":{
"mer_reference_id":"Z2017112613560001",
"mer_date":"20171126",
"amount":{
"total":"0.01",
"currency":"CNY"
},
"order_summary":"欧莱雅",
"expire_time":"1800",
"user_ip":"106.38.123.141",
"sub_orders":[
{
"mer_sub_reference_id":"Z2017112613560001S1",
"trans_code":"02223022",
"amount":{
"total":"0.01",
"currency":"CNY"
}
}
]
},
"notify_url":"https://dev.restdemo.umftech.com/restdemo/demo/notifyResultRest",
"risk_info":{
"trans_type":"02",
"goods_type":"1",
"real_name":"0",
"business_type":"Y"
}
}'
## Response data of WeChat App Code Payment:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"id": "PAY_GM3TCMJSG4YDMMJXGE2TINRVGAZDAMJXGEYTENSC",
"state": "WAIT_BUYER_PAY",
"notify_url": "",
"execute_success_time": "2017-11-27T06:17:31+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%3Dwx201711270617318f29d10dda0145259373%26package%3D1940641578"
},
"phone": "13581874641"
}
},
"is_from_US": "Y",
"order": {
"user_ip": "106.38.123.141",
"amount": {
"total": "0.01",
"currency": "CNY"
},
"sub_orders": [
{
"mer_sub_reference_id": "Z2017112613560001S1",
"trans_code": "02223022",
"amount": {
"total": "0.01",
"currency": "CNY"
}
}
],
"mer_date": "20171126",
"expire_time": "1800",
"mer_reference_id": "Z2017112613560001",
"order_summary": "欧莱雅"
}
},
"links": [
{
"ref": "parent_payment",
"method": "GET",
"href": "https://fxus.soopay.net/cberest/v1/payments/payment/PAY_GM3TCMJSG4YDMMJXGE2TINRVGAZDAMJXGEYTENSC"
},
{
"ref": "apply_to_customs",
"method": "POST",
"href": "https://fxus.soopay.net/cberest/v1/payments/payment/PAY_GM3TCMJSG4YDMMJXGE2TINRVGAZDAMJXGEYTENSC/apply_to_customs"
},
{
"ref": "self_payment_refund",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GM3TCMJSG4YDMMJXGE2TINRVGAZDAMJXGEYTENSC/self_payment_refund"
},
{
"ref": "refund",
"method": "POST",
"href": "https://fxus.soopay.net/cberest/v1/payments/payment/PAY_GM3TCMJSG4YDMMJXGE2TINRVGAZDAMJXGEYTENSC/refund"
}
]
}
sequenceDiagram
participant Customer
participant Merchant
participant UMF
participant WeChat
Customer-->>Merchant: 1. Order goods
Merchant-->>Customer: 2. Generate order
Customer-->>Merchant: 3. Confirm order
Note right of Merchant: If the merchant have an unexpired access token. It can be used to make an API call
Merchant-->>UMF: 4. Optional. Acquire an access token
UMF-->>Merchant: 5. Return access_token
Note right of Merchant: Using access token to make API call
Merchant-->>UMF: 6. Create a payment
UMF-->>WeChat/Alipay: 7. Payment request
WeChat/Alipay-->>UMF: 8. Return a payment jump url of wechat H5
UMF-->>Merchant: 9. Return a wechat H5 object
Merchant-->>Customer: 10. Show the page of H5 which generated by the URL and the URL will call WeChat Payment()
Customer-->>WeChat/Alipay: 11. Finish the payment
WeChat/Alipay-->>UMF: 12. Deduction result
UMF-->>Merchant: 13. Payment result notification
Merchant-->>Customer: 14. Payment result
Explanation of the sequence chart：
- Customer orders goods at merchant platform.
- Merchant App Client generate an order.
- Customer App Client confirm the order.
- Request for initial a payment.
- Optional. Merchant acquire an access token. This step is optional. If the merchant have an unexpired access_token already, This token can be used to make a API call. Please ignore step 4 and setp 5.
- UMF returns an access token.
- Merchant app server submit order data to UMF. Call Create a payment.
- UMF sends payment request to WeChat.
- WeChat returns payment info to UMF.
- UMF returns a wechat_H5 object to merchant app server.
- Merchant redirecte the page by a wechat_H5_url link from wechat_H5
- WeChat payment widget activated.
- Customer enter password and finish the payment in WeChat explore.
- UMF receives the result of deduction.
- UMF sends the result to merchant app server.
- Merchant app server sends the result to merchant app client.
- Merchant app client shows the result to customer.
2.9 Pay by Wechat Mini Programs Payment
Merchants push product messages to their followers via Official Mini Programs. With WeChat Pay enabled, their followers can purchase products on the shopping page.
sequenceDiagram
participant Consumer
participant WeChat Browser
participant Merchant
participant UMF
participant WeChat
Consumer-->>WeChat Browser: 1.Confirm order
WeChat Browser-->>Merchant: 2. Get open_id
Merchant-->>UMF: 3. Request get open_id url with notify_url
UMF-->>Merchant: 4. Return to notify_url address with getting open_id WeChat url.
Merchant-->>WeChat Browser: 5. Return this url.
WeChat Browser-->>WeChat: 6. Request open_id with return info with Mini Programs app_id.
WeChat-->>UMF: 7. Redirect url to UMF
UMF-->>Merchant: 8. Call notify_url which send by Merchant with open_id
Merchant-->>UMF: 9. Create a payment request with open_id
UMF-->>WeChat: 12. Payment request
WeChat-->>UMF: 13. Return payment info
UMF-->>Merchant: 14. Return a wechat_mp object
Merchant-->>WeChat Browser: 15. Activate payment widget
WeChat Browser-->>WeChat Browser: 16. Call WeChat JS-API
Consumer-->>WeChat: 17. Enter password, finish payment
WeChat-->>WeChat Browser: 18. Return pending info.
WeChat Browser-->>WeChat Browser: 19. Redirect to ret_url.
WeChat-->>UMF: 20. Deduction result.
UMF-->>Merchant: 21. Payment result.
Explanation of the sequence chart：
- Consumer confirms the order.
- WeChat Browser request Merchant systems.
- Consumer authorize merchant to have open_id by request UMF authorization url
- UMF returns the authorization url.
- Merchant redirect to this url.
- The authorization page requests WeChat open_id with merchant app_id.
- The WeChat returns the open_id of current WeChat user.
- The authorization page redirect to notify_url(step 3).
- Optional. The Merchat returns a pending page to wait.
- Optional. The pending page request a payment.
- Merchant send payment request to UMF.Call Create a payment.
- UMF sends payment request to WeChat.
- WeChat returns payment info to UMF.
- UMF returns a wechat_mp object.
- Merchant returns info with wechat_mp object to browser.
- The return page activates Wechat payment widget(WeChat JS-API).
- Consumer enter password and finish the payment in WeChat explore.
- WeChat return ap pending page.
- The pending page redirect to ret_url(step 11).
- WeChat send the payment result to UMF.
- UMF send the payment result to notify_url by Merchant (step 11).
2.10 B2C Direct To Bank Pay
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 Customer
participant Merchant
participant UMF
participant Bank
Customer-->>Merchant: 1. Create a payment.
Merchant-->>UMF: 2.Create a payment.
UMF-->>Merchant: 3. Return the payment object with URL of bank online payment website.
Merchant-->>Bank: 4. Open bank online payment website by the return URL.
Bank-->>Customer: 5. Show bank payment website.
Customer-->>Bank: 6. Pay it online.
Bank-->>UMF: 7. Payment result notification.
UMF-->>Merchant: 8. Payment result notification.
Explanation of the sequence chart：
- The Customer selects goods and services and Create a payment.
- Merchant submits order data to UMF.
- UMF returns the created payment object. The payment object includes the URL to Bank online payment website.
- The merchant open Bank online payment website.
- The Bank shows online payment website.
- The Customer fills all the information and commit.
- Bank sends notification of the payment result to UMF.
- UMF sends notification of the payment result to Merchant.
2.11 Refund
## Request data:
$ 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":"59cdb63e38ee5d75ca7b34af",
"mer_date":"20171003",
"amount":{
"total":"0.01",
"currency":"USD"
},
"sub_orders":[
{
"trans_code":"08227020",
"amount":{
"currency":"USD",
"total":0.01
},
"mer_sub_reference_id":"59cdb63e38ee5d75ca7b34af"
}
]
},
"notify_url":"https://merchant.wish.com/umpay/webhook/charge-confirmation"
}'
## Response data:
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"refund":{
"id":"REFUND_AAAAAAQZBJGT2AJTY24KS",
"refund_info":{
"mer_reference_id":"1753176072",
"mer_date":"20170824",
"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"
}
]
}
UMF supports full refund or partial refund of a payment.
sequenceDiagram
participant Customer
participant Merchant
participant UMF
participant Bank
Customer-->>Merchant: 1. select the goods to be returned and refunded
Merchant-->>Customer: 2. Generate a refund order
Customer-->>Merchant: 3. Confirm the refund order
Note right of Merchant: If the merchant have an unexpired access token. It can be used to make an API call
Merchant-->>UMF: 4. Optional. Acquire an access token
UMF-->>Merchant: 5. Return access_token
Note right of Merchant: Using access token to make API call
Merchant-->>UMF: 6. Request a refund
UMF-->>Bank: 7. Refund request
Bank-->>UMF: 8. Return refund result
UMF-->>Merchant: 9. Return a refund object
Merchant-->>Customer: 10. Refund result
Explanation of the sequence chart：
- Customer select the goods to be returned and refunded at merchant platform.
- Merchant platform generates a refund order.
- Customer confirm the refund order.
- Optional. Merchant acquire an access token. This step is optional. If the merchant have an unexpired access_token already, This token can be used to make a API call. Please ignore step 4 and setp 5.
- UMF returns an access token.
- Merchant request a refund with all order data to UMF. Call Create a refund.
- UMF sends a refund request to Bank.
- Bank returns refund result to UMF.
- UMF returns a refund object to merchant.
- Merchant shows the result to customer.
2.12 Direct To Bank Pay
sequenceDiagram
participant Customer
participant Merchant
participant UMF
participant Bank
Customer-->>Merchant: 1. Create a payment.
Merchant-->>UMF: 2.Create a payment.
UMF-->>Merchant: 3. Return the payment object with URL of bank online payment website.
Merchant-->>Bank: 4. Open bank online payment website by the return URL.
Bank-->>Customer: 5. Show bank payment website.
Customer-->>Bank: 6. Pay it online.
Bank-->>UMF: 7. Payment result notification.
UMF-->>Merchant: 8. Payment result notification.
Explanation of the sequence chart：
- The Customer selects goods and services and Create a payment.
- Merchant submits order data to UMF.
- UMF returns the created payment object. The payment object includes the URL to Bank online payment website.
- The merchant open Bank online payment website.
- The Bank shows online payment website.
- The Customer fills all the information and commit.
- Bank sends notification of the payment result to UMF.
- UMF sends notification of the payment result to Merchant.
2.13 UMF Web Pay
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": [{
"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 Customer
participant Merchant
participant UMF
participant Bank
Customer-->>Merchant: 1. Create a payment.
Merchant-->>UMF: 2.Create a payment.
UMF-->>Merchant: 3. Return the payment object.
Merchant-->>UMF: 4. Open UMF payment website by the return URL.
UMF-->>Customer: 5. Show payment website.
Customer-->>UMF: 6. Pay it online.
UMF-->>Bank: 7. Request deduct money.
Bank-->>UMF: 7. result notification.
UMF-->>Merchant: 8. Payment result notification.
Explanation of the sequence chart：
- The Customer selects goods and services and Create a payment.
- Merchant submits order data to UMF.
- UMF returns the created payment object. The payment object includes the URL to UMF online payment website.
- The merchant open UMF online payment website.
- The Bank shows online payment website.
- The Customer fills all the information and commit.
- Bank sends notification of result to UMF.
- UMF sends notification of the payment result to Merchant.
2.14 Entry Enterprise Qualification
- Enter the enterprise for the current merchant’s Customer.
- Use online banking to pay.
sequenceDiagram
participant Customer
participant Merchant
participant UMF
participant Bank
Customer-->>Merchant: 1. submit documents.
Merchant-->>UMF: 2.submit documents.
UMF-->>Bank: 3. submit documents.
Bank-->>UMF: 4. return check result.
UMF-->>UMF: 5. update enterprise status.
Merchant-->>UMF: 6. query enterprise status.
UMF-->>Merchant: 7. return enterprise status.
时序图描述 (offline)：
- the customer submit the required documents to the merchant.
- the merchant submit the required documents to the UMF.
- UMF check the documents and sends it to the bank.
- The Bank verify the enterprise qualification and send the result to UMF.
- UMF returns the result to the merchant.
- online. The merchant query the enterprise qualification status from UMF.
- online. UMF returns to the enterprise qualification status.
2.15 B2B payment
sequenceDiagram
participant Merchant
participant UMF
Merchant-->>UMF: Entry Enterprise Qualification
Merchant-->>UMF: Direct To Bank Pay
UMF-->>Merchant: return payment result
Merchant-->>UMF: Upload details file
时序图描述：
- The merchant enter the enterprise qualification into UMF,The merchant can request to obtain the enterprise qualification statusQuery register status.
- The merchants use online direct banking to pay.
- UMF return payment result.
- The merchant upload transaction details files to UMF.
3. B2C Reference
3.1 Query available banks
## 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"
}
}
Request
GET: /bank?type=CREDIT_CARD
Each merchant can only accept bank cards that was included in the contract.
This API will return the list of banks that are available for current merchant of the indicated type.
| Parameter | Description |
|---|---|
| type | ENUM. The type of bank cards. Allowed values: CREDIT_CARD,DEBIT_CARD |
Response
| Parameter | Description |
|---|---|
| banks | Object Array. A list of bank objects. See the example on the right. |
3.2 Query a bank card information
## 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:
{
"banks": {
"name_zh": "招商银行",
"types": [
"DEBIT_CARD"
],
"code": "CMB",
"logo_url": "",
"is_support": "Y",
"name": "China Merchants Bank"
},
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
}
}
Request
GET: bank/cardbin?card={an encrypted bank account number}
This API will return a bank information about this card.
The request is a http get request. The card must be in the URL.
| Parameter | Description |
|---|---|
| card | String. an encrypted bank account number.see how to encrypt. |
Response
| Parameter | Description |
|---|---|
| meta | Object. The common information of response. |
| bank | Object. The information of bank. |
3.3 Get WeChat open_id
# Request
$ curl -X GET \
https://fxus.soopay.net/cberest/v1/payments/wechat_openid?notify_url=https%3A%2F%2Fdev.restdemo.umftech.com%2Frestdemo%2Fdemo%2FnotifyResultRest \
-H 'authorization: Bearer f763606227230639688267c5c27079baada00ba01fd86749fd4cba4655e5084a' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
# Response
{
"meta": {
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"links": [
{
"ref": "weChat",
"method": "GET",
"href": "https://open.weixin.qq.com/connect/oauth2/authorize?appid=wx740a066b0a94fa6d&redirect_uri=http%3A%2F%2Fpay.soopay.net%2Febankpay%2FrecvweixinGZHCodeNew.htm%3Freturn_url%3Dhttps%253A%252F%252Ffx.soopay.net%252Ffx_upay%252FcbNotifyMerOpenId.do%253FnotifyUrl%253Dhttps%253A%252F%252Fdev.restdemo.umftech.com%252Frestdemo%252Fdemo%252FnotifyResultRest&response_type=code&scope=snsapi_base&state=a6493814b6caa960c1094ac68278fdaa53b3149524a1084b#wechat_redirect"
}
]
}
Request
GET: /payments/wechat_openid?notify_url=<utf8_urlEncode_notify_url>
Get Wechat open_id before call Create a payment if the payment type is WECHAT_WEB.
| Parameter | Description |
|---|---|
| notify_url | Asynchronous notification url,After the completion of the transaction,UMPay payment platform will send the transaction results to the notify_url via http(s). |
Response
| Parameter | Description |
|---|---|
| meta | Object. The common information of response. |
| links | Object Array. The next step links. See the example on the right. |
3.4 Query exchange rate
## Request data:
curl -s -X GET https://uatfx.soopay.net/cberest/v1/exchange_rate?currency=USD \
-H "Content-Type:application/json" \
-H "Authorization: Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
## Response data:
{
"meta":{
"sign":"Alc9iDPd4P2z3LzeaZj73aC2fmeHZmlh59d7+MvZoDRYUsOF3lLGe92VhqWhRERvXCBBOK+SarPSI72pj1rHCqTcVd6/hagHKJa/j4k0CodwsrYXhoayLhu6Y/XG7JllyY2pa84J+xLCv/D81KvwWukOpK3MRNf5yq9zrVaVD5E=",
"ret_msg":"Success",
"ret_code":"0000"
},
"exchange_rate":[
{
"rate":"6.5023",
"currency":"USD"
}
]
}
Request
GET: /exchange_rate?currency=USD
Get the real-time exchange rate. The returned information is the corresponding amount of CNY.
| Parameter | Description |
|---|---|
| currency | String. |
Response
The response will include an exchange_rate object and meta object.
| Parameter | Description |
|---|---|
| meta | Object. The common information of response. |
| exchange_rate | Object. The rate information. |
3.5 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 e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f" \
-H "Signature: R4gha4Kgg5NDGXV4+Tpw0PTRldATI/ECwCIYgWmLLMBYnF8oVLU2wfBM/hG4Nw+E77qSTquMShiICVS7qcHMVwHZTbFIAP2ZarkJ21EMGFEKdC5hgdDgNO89xXu0OoAfrJ8fDclfdKgpfd9RIpGH7CzKM3JoO0+RD3zCnhnbGBo=" \
-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"
}]
}
Request
POST: /payments/payment
Creates a payment to execute later or execute right now,it depends on the payment type,all payments must be paid in CNY(Chinese Yuan).
If the interface type is SERVER_TO_SERVER, the payment methods are as follows
| payment_method | Description |
|---|---|
| CREDIT_CARD | Credit card quick payment |
| DEBIT_CARD | Debit card quick payment |
| WECHAT_SCAN | Wechat scan payment.Return a url of QR code by UMF, The user completes the payment by scanning the qr code through WeChat . |
| WECHAT_WEB | Wechat Official Account payment. The user completes the payment in wechat. |
| WECHAT_IN_APP | Wechat app payment. The user completes the payment in wechat APP. |
| ALIPAY_SCAN | Alipay scan payment. Return a url of QR code by UMF. The user completes the payment by scanning the qr code through Aipay. |
| WECHAT_H5 | Wechat H5.Return a url of QR code by UMF.The user completes the payment by clicking the link in Wechat. |
| WECHAT_MP | Wechat mini program.Return a url of QR code by UMF, The user completes the payment by clicking the link in Wechat. |
| B2C_BANK | Pay by personal e-bank. |
| B2B_BANK | Pay by business e-bank. |
| interface_type | Description |
|---|---|
| SERVER_TO_SERVER | API mode |
| SERVER_TO_WEB | Cashier mode， if the interface mode is SERVER_TO_WEB，payment method：NOT_APPLICABLE |
| SERVER_TO_H5WEB | Swift H5 Cashier mode,if the interface mode is SERVER_TO_H5WEB，payment method：NOT_APPLICABLE. |
| DIRECT_TO_BANK | Bank direct connnection |
| business_type | Description |
|---|---|
| B2B | B2B |
| B2C | B2C |
| Parameters | Description |
|---|---|
| payer | Object. The payment information. |
| order | Object. The order information. Includes sub orders. |
| notify_url | String. Url of the merchant server. To receive the payment result. |
| risk_info | Object. The information of transaction. |
| subMchId_flag | String. Whether to acquire a sub-merchant. Not required. effective value: Y,N |
Response
The Response includes meta information and a payment object. See the example. The created payment object includes the following objects:
| Parameters | Description |
|---|---|
| meta | Object. The common information of response. |
| payment | Object. The payment object. |
| links | Object Array. The next step links. Depends on the status and payment type. Those links are HATEOAS links. |
3.6 SMS verification
## Request data:
$ 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"
}
}'
## Response data:
{
"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"
}]
}
This step is only available for card payment.
In this step,Merchant sends the card information,and UMF(or the bank) will send SMS to customer’s phone. This SMS is part of the parameters of executing the payment.
Request
POST:/payments/payment/{payment_id}/verify
The payment_id in the url is the real payment id that was created in the previous step(Create a payment).
The payer object can be used
| Parameter | Description |
|---|---|
| payer | Object. The payer information. Some parameters should be encrypted by UMF public key. See the description of payer object. |
Response
The response just includes the links of next steps. See the example. If the request is vaild,the sms will be sent to customer’s phone.
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
| payment | Object. The payment object. |
| links | object array. The links of next steps. |
Error Codes:
| Return code | Description of return code |
|---|---|
| 00060700 | Failed to verify parameter |
| 00200025 | Information of the card is incorrect. |
| 00200026 | The card has expired. |
| 00060999 | The system is busy. |
| 00080706 | Acquire verification codes too many times within one minute. |
| 00060875 | Failed to validate the card bin (validation failure due to incorrect card number) |
| 00080707 | The number of verification code requests for the order exceeds the maximum. |
| 00200027 | The bank is not linked with the merchant on UMF’s platform. |
| 00060869 | Merchant goods are not registered on UMF’s platform. |
3.7 Execute a payment
## 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"
}]
}
When executing a payment,the transaction completes and transfers money from the customer’s account into merchant account with UMF.
To execute a payment,include the payment ID in the URI and include a payer object in the JSON body.
The result of executing will not returned immediately. The merchant has two ways to get the result.
– Make a query of payment. If the payment state is “TRADE_SUCCESS”,then the payment was successful. – Wait for the notification from UMF. Merchant needs to write a http(s) service. UMF will call this service when the payment has a result.
Request
POST:/payments/payment/{payment_id}/execute
The payment_id in the url is the real payment ID that was created in the previous step(Create a payment).
| Parameter | Description |
|---|---|
| payer | Object. The payer information. Some parameters should be encrypted by UMF public key. See the description of payer object. If the pay_type is credit card or debit card,the verification code should be included in the payer object. |
Response
The response includes the payment object. But the bank card info will not be returned,such as card number,cvv2,citizen_id,etc.
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
| payment | object. The payment object. |
| links | Object Array. The next step links. Depends on the status and payment type. Those links are HATEOAS links. |
3.8 Payment result notification
## 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:KkNs3zgYY+sQSXPIGgAG+APHi4AG9WcM3Jy8mQOPhLyn+eNTOOpdZrW3HJDeok1VRbYadRgiCj1mJphGK/VRG0y4mcmHkJr10jhXpbBrW/l9sHdP7nvEqbqG8kdd9lhK2McPP4f3eMi1MdfrxusTzbQyEXzIAmSxQZSvbbQdmNE=" \
-d '{"meta":{"ret_code":"0000","ret_msg":["SUCCESS"]},"payment":{"id":"PAY_GM3TAOJRGYYDONJVGY3TGMRUGUZDAMJXGA4TCNOZ","payer":{"bank_code":"","payer_info":{"payer_agreement":{"gate_id":"","last_four_cardid":"","usr_pay_agreement_id":"","usr_busi_agreement_id":""}}},"order":{"mer_reference_id":"54bec7906fa88c72ba3597a7","mer_date":"20170915","amount":{"total":"0.01","currency":"CNY","total_cny":"0.01"},"mer_priv":""},"state":"TRADE_SUCCESS","settle_date":"20170916","execute_success_time":"20170916"},"links":[{"href":"https://fx.soopay.net/cberest/v1/payments/payment/PAY_GM3TAOJRGYYDONJVGY3TGMRUGUZDAMJXGA4TCNOZ","ref":"self","method":"GET"},{"href":"https://fx.soopay.net/cberest/v1/payments/payment/PAY_GM3TAOJRGYYDONJVGY3TGMRUGUZDAMJXGA4TCNOZ/refund","ref":"refund","method":"POST"},{"href":"https://fx.soopay.net/cberest/v1/payments/PAY_GM3TAOJRGYYDONJVGY3TGMRUGUZDAMJXGA4TCNOZ/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"
}]
}
}
After processing the payment request data of the merchant,UMF will call merchant’s service with the payment result.
Merchant should give a response after receiving the call.
Request
UMF calls this service which is provided by merchant. The url of service is a merchant service url.
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
| payment | object. The payment object. |
Response
The response is sent from merchant to UMF.
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
3.9 Query a payment
## Request data:
$ curl -s -X GET https://fx.soopay.net/cberest/v1/payments/payment/PAY_GM3TAOBRHEYTCMJVHAYTKMBRGUZDAMJXGA4DCOFQ \
-H "Content-Type:application/json" \
-H "Authorization:Bearer 6eb7208fa9c1b8b1afef57f159c8b5ef8804666f314c02c565727d6d19c8bb70"
## response data:
{
"meta": {
"error_code": "",
"ret_msg": "successful transaction",
"ret_code": "0000"
},
"payment": {
"settle_date": "",
"state": "WAIT_BUYER_PAY",
"execute_success_time": "",
"payer": {
"payment_method": "WECHAT_WEB"
},
"order": {
"user_ip": "",
"amount": {
"total": "0.03",
"exchange_rate": {
"rate": "1.0000",
"currency": "CNY"
},
"currency": "CNY",
"total_cny": "0.03"
},
"mer_date": "20170818",
"expire_time": "",
"mer_reference_id": "4b37lysdimy"
}
}
}
Reuest
GET: payments/payment/{payment_id}
The payment_id in the url is the real payment id that was created in the previous step(Create a payment).
You may call this url anytime. UMF will return the payment object.
Response
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
| payment | object. The payment object. |
3.10 Create a refund
## Refund/Asynchronous Refund request data:
$ 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",
"mer_date":"20170824",
"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"
}'
## Response data:
{
"meta":{
"ret_msg":"successful transaction",
"ret_code":"0000"
},
"refund":{
"id":"REFUND_AAAAAAQZBJGT2AJTY24KS",
"refund_info":{
"mer_reference_id":"1753176072",
"mer_date":"20170824",
"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"
}
]
}
Distinction
The difference between Asynchronous Refund and Refund is that when the user’s account is insufficient, the asynchronous refund will be successful, and when the account balance of the merchant is sufficient, the refund will be refunded.
Request
Refund:POST:/payments/payment/{payment_id}/refund
The payment_id in the url is the real payment ID that was created in the previous step(Create a payment).
This request creates a refund object. The request sends a refund object,and the response is the refund object that UMF created.
UMF supports full or partial refund. Partial refund can be made multiple times.
The refund must be the same currency as the payment and the refund amount must be no more than the total payment amount.
| Parameter | Description |
|---|---|
| refund | Object. The refund object. The order,amount and nofify_url should be entered. |
Response
The response includes the refund object. The returned refund object has refund_id and state.
If the state is “REFUND_SUCCESS”,that means the transcation was done and the refund was successufl. If the state is “REFUND_PROCESS”,that means the transaction is pending,when it is done,UMF will send a notification to the merchant. Or the merchant may query refund state by Query refund
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
| refund | object. The refund object. |
| links | Object Array. The next step links. Depends on the status and payment type. Those links are HATEOAS links. |
3.11 Create a Asynchronous Refund
## 异步退费请求数据:
$ 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"
}'
## Response data:
{
"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"
}
}
请求
Asynchronous Refund:POST:/payments/payment/{payment_id}/asynchronous_refund
The payment_id in the url is the real payment ID that was created in the previous step(Create a payment).
This request creates a refund object. The request sends a refund object,and the response is the refund object that UMF created.
UMF supports full or partial refund. Partial refund can be made multiple times.
The refund must be the same currency as the payment and the refund amount must be no more than the total payment amount.
Once the asynchronous refund is initiated, UMF will check the balance of the merchant’s account at every hour and refund will be made when the balance is sufficient. Bur if the balance is insufficient, UMF will query it at the next hour (in which the state is REFUND_RETRY), and UMF will execute it for 10 times. In addition, the refund will not be executed between 23:00 and 10:00.
| 参数 | 描述 |
|---|---|
| refund | Object. The refund object. The order,amount and nofify_url should be entered. |
响应
响应结果包含支付对象. 退款对象包含refund_id和state.
若ret_code是"0000", 表示退款受理成功. 退款交易完成后, UMF 将通知商户. 商户也可以查询退款状态 查询退款
| 参数 | 描述 |
|---|---|
| meta | object. The common information of response. |
| refund | object. The refund object. |
| links | Object Array. The next step links. Depends on the status and payment type. Those links are HATEOAS links. |
3.12 Query a refund
## 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"
}
}
Request
GET: /payments/refund/refund_id
The refund_id in the url is the real payment ID that was created in the previous step(create a refund).
Merchant may call this url anytime. UMF will return the refund object. If the state is “REFUND_SUCCESS”,the refund is successful.
Response
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
| refund | object. The refund object. |
3.13 Query a payment and refunds
## 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
The payment_id in the url is the real payment id that was created in the previous step(Create a payment).
You may call this url anytime. UMF will return the payment object and the refund object.
Response
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
| payment | object. |
3.14 Agreement query
$ 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"
}
}
Request
get: /agreement?external_customer_id=911886886911
or /agreement?usr_busi_agreement_id=UB201811261450560000000033862892
or /agreement?usr_busi_agreement_id=UB201708311351430000000000144944&external_customer_id=911886886911
or /agreement?usr_busi_agreement_id=UB201811261450560000000033862892&bank_type=DEBIT_CARD
or /agreement?external_customer_id=911886886911&bank_type=DEBIT_CARD
or /agreement?usr_busi_agreement_id=UB201811261450560000000033862892&external_customer_id=911886886911&bank_type=DEBIT_CARD
Response
| Parameter | Description |
|---|---|
| payer_agreements | object. |
| meta | object. The common information of response. |
3.15 Agreement unbundling
$ 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"
}
}
Request
POST: /agreement/unbundling
| Parameter | Description |
|---|---|
| payer_agreements | object. |
Response
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
3.16 Create customs clearance
## Request data:
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/payments/payment/PAY_AAEZW4UOJZ6GKAJTY2Z2I/apply_to_customs \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f"
-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 data:
{
"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/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"
}]
}
Request
POST: /payments/payment/{payment_id}/apply_to_customs
This interface is optional. When merchant needs UMF to commit the payment information to customs,this interface will be called. As soon as the merchant calls this url,the payment information will be sent to the customs system.
The merchant provides the sub-order declaration data to UMF within one month after placing an order,and UMF updates the sub-order declaration data to customs system after receiving it.
| Parameter | Description |
|---|---|
| customs_declarations | Object. The customs information. |
Response
The response will include a customs_declaration object and meta information.
| Parameter | Description |
|---|---|
| meta | Object. The common information of response. |
| customs_declarations | Object. The customs information. |
| links | Object Array. The next step links. Depends on the status and payment type. Those links are HATEOAS links. |
3.17 Query customs clearance status
## 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"
}]
}
Request
GET: payments/customs_declarations/{customs_declaration_id}
The customs_ declaration_id in the url is the ID of customs_declaration object which was created in the previous step(Create customs clearance).
Response
| Parameter | Description |
|---|---|
| meta | Object. The common information of response. |
| customs_declarations | Object. The customs information. |
Customs status description
| No. | Enumeration name | Description |
|---|---|---|
| 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 Create ciq clearance
## Request data:
$ curl -s -X GET https://uatfx.soopay.net/cberest/v1/payments/payment/PAY_AAEZW4UOJZ6GKAJTY2Z2I/apply_to_ciq \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f"
-d '{
"sub_order": {
"mer_sub_reference_id": "05073219521"
},
"ciq_code": "GJHP",
"plat_supplier_no": "56546546"
}'
## Response data:
{
"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/CUST_AAAAAAHZPC5YYAJTY2ZXC"
}
],
"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"
},
}
Request
POST: /payments/payment/{payment_id}/apply_to_ciq
This interface is optional. When merchant needs UMF to commit the payment information to ciq,this interface will be called. As soon as the merchant calls this url,the payment information will be sent to the ciq system.
The merchant provides the sub-order declaration data to UMF within one month after placing an order,and UMF updates the sub-order declaration data to ciq system after receiving it.
| Parameter | Description |
|---|---|
| national_inspection | Object. The customs information. |
Response
The response will include a national_inspection object and meta information.
| Parameter | Description |
|---|---|
| meta | Object. The common information of response. |
| national_inspection | Object. The ciq information. |
| links | Object Array. The next step links. Depends on the status and payment type. Those links are HATEOAS links. |
3.19 Query ciq clearance status
Request
## 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/{national_inspection_id}
The declarations declaration_id in the url is the ID of national_inspection object which was created in the previous step(Create ciq clearance).
Response
| Parameter | Description |
|---|---|
| meta | Object. The common information of response. |
| national_inspection | Object. The ciq information. |
3.20 Download settlement file（JSON）
## Request data:
curl -s -X GET https://uatfx.soopay.net/cberest/v1/payments/reconciliation_statement?settle_date=20180103 \
-H "Content-Type:application/json" \
-H "Authorization: Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
## Response data:
[
{
"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"
}
}
]
Request
GET: /payments/reconciliation_statement?settle_date=20180103
GET: /payments/reconciliation_statement?settle_date=20180103&page_number=2
A reconciliation statement is generated when UMF transfer money to merchant’s bank account. It includes every transactions,severice fee and exchange actions. It shows what parts of the transferd money is made of.
The date of reconciliation statement is based on the settle_date. Only when UMF transfer money to merchant’s account,the reconciliation statment is generated.
The request is a http get request. The settle_date must be in the URL.
| Parameter | Description |
|---|---|
| settle_date | String. The date when UMF transfer money to merchant’s bank account. |
| page_number | Number. Optional. The requested page number (starts at 1). Default value: 1 |
| page_size | Number. Optional. The maximum number of returned objects. Default value: 500 |
Response
The response includes a reconciliations object. See the example on the right.
| Parameter | Description |
|---|---|
| meta | Object. The common information of response. |
| reconciliations | Object. The information of reconciliations. |
3.21 Download settlement file（File stream）
$ 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,5698798
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,5984526
SETTLEDETAIL-END,70510000,20180130,6,602.79,602.79,USD
]
GET: /payments/statement_download?settle_date=20180130
UMF will make a transaction list daily for each merchant. The list includes all the successful transaction within one day(mer_date). The merchant may download the list anytime.
This date of transaction list is merchant’s order date(mer_date).
Request
The request is a http get request. The settle_date must be in the URL.
Response
This interface is an Http download interface and the transaction list is downloaded as a file.
Each line represents a transaction expect the first and last line.If the transaction data is null in A field, N/A is used. If the tranType value is payment, the row’s oriOrderId and refundNo fields are empty.
Transaction information are separated by comma and follow the order list below:
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
Field instruction of transaction lists.
| NO. | Field | Name | Description |
|---|---|---|---|
| 1 | tradeNo | tradeNo | created by UMF |
| 2 | tranType | Transaction type | payment or refund |
| 3 | tranState | Transaction State | |
| 4 | productName | Product Name | |
| 5 | mainOrderId | OrderId | |
| 6 | platDateTime | Transaction Time | |
| 7 | currency | Currency | |
| 8 | cbAmount | Foreign Amount | Format: two decimal places. |
| 9 | rate | Transaction Exchange Rate | |
| 10 | amount | Rmb Amount | Format: two decimal places. |
| 11 | comAmt | Service Charge | |
| 12 | sendTime | Buy Foreign Exchange Date | |
| 13 | buyForexNo | Buy Foreign Exchange BatchNo | |
| 14 | buyForexRate | Buy Foreign Exchange Rate | |
| 15 | buyCurrencyId | Buy Foreign Exchange Currency | |
| 16 | foreignAmount | Buy Foreign Amount | |
| 17 | oriOrderId | Original Order Id | This field has a value only when the tranType is a refund. |
| 18 | refundNo | Refund No | This field has a value only when the tranType is a refund. |
| 19 | refundAmountRequested | Refund Amount Requested | Refund amount the merchant requested. |
3.22 Download transactions（JSON）
## Request data:
curl -s -X GET https://uatfx.soopay.net/cberest/v1/payments/transactions?mer_date=20170213 \
-H "Content-Type:application/json" \
-H "Authorization: Bearer e3918a3594e20cf8aebf925579fbdf0d99c017451c78b865343808abc84af97f"
## Response data:
{
"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
}
}
}
Request
GET: /payments/transactions?mer_date=20170213
GET: /payments/transactions?mer_date=20170213&page_number=2
The request is a http get request. The mer_date must be in the URL.The page_number should be filled when there are too many transactions to return in one response.
| Parameter | Description |
|---|---|
| mer_date | String. The merchant date of payment. |
| page_number | Number. Optional. The requested page number (starts at 1). Default value: 1 |
| page_size | Number. Optional. The maximum number of returned objects. Default value: 500 |
Response
| Parameter | Description |
|---|---|
| meta | Object. The common information of response. |
| transactions | Object Array. The information of transactions. See the example on the right. |
3.23 Download reconciliation statement（File stream）
GET: /payments/transactions_download?settle_date=20170213
A reconciliation statement is generated when UMF transfer money to merchant’s bank account. It includes every transactions, severice fee and exchange actions. It shows what parts of the transferd money is made of.
It has the same logic with transaction list download. The date of reconciliation statement is based on the mer_date.
Request
The request is a http get request. The settle_date must be in the URL.
Response
This interface is an Http download interface and the transaction list is downloaded as a file.
The contents of the file are separated by commas and in the following order:
TRANSDETAIL-START,MerId,settledate
tradeno,mobileid,orderid,orderdate,platdate,plattime,currency,cbamount,amount,exchangerate,settledate, transtate,transtype,productid,merdate,refundno,prefundtradeno,cardholder,identifycode,comamt
TRANSDETAIL-END,MerId,settledate,number
| No | field | name | description |
|---|---|---|---|
| 1 | tradeno | tradeno | String. |
| 2 | mobileid | mobileid | String. |
| 3 | orderid | orderid | String. |
| 4 | orderdate | orderdate | YYYYMMDD. |
| 5 | platdate | platdate | YYYYMMDD. |
| 6 | plattime | plattime | HHmmss. |
| 7 | currency | currency | |
| 8 | cbamount | cbamount | Units: yuan |
| 9 | amount | amount | Units: yuan |
| 10 | exchangerate | exchangerate | |
| 11 | settledate | settledate | YYYYMMDD. |
| 12 | transtate | transtate | |
| 13 | transtype | transtype | |
| 14 | productid | productid | |
| 15 | merdate | merdate | YYYYMMDD. |
| 16 | refundno | refundno | String. |
| 17 | prefundtradeno | prefundtradeno | |
| 18 | cardholder | cardholder | String. |
| 19 | identifycode | identifycode | String. |
| 20 | comamt | comamt | Units: yuan |
3.24 Create Settle Month Statement
## 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"
}
}
Request
POST: /payments/settle_month_create
Create Settle Month Statements.
This interface is an Http download interface and return downloaded link. It is allowed to download Settle Month Statements after 24 hours.
| Parameter | Description |
|---|---|
| settle_month | settle month. |
Response
| Parameter | Description |
|---|---|
| links | object array. The links of next steps. |
| meta | object. The common information of response. |
| settle_month_file | object. |
3.25 Download Settle Month Statement
GET: /payments/{file_id}/settle_month_file_download
The file_id in the url is the real file_id that was created in the previous step(Create Settle Month Statements).
请求
The request is a http get request.
响应
This interface is an Http download interface and the settle month statements is downloaded as a file.
The contents of the file are separated by commas and in the following order:
MONTHLYBILL_START,merId,settleMonth
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,merId,payBill cycle,Total number of transactions,settleCurrency,total amount of foreign exchange purchase of this month,total amount of payment of this month
MONTHLYBILL_END,merId,billing cycle,the sum of transactions,Settlement currency,the total amount of foreign exchange purchase of this month， the total amount of foreign exchange payment of this month
The content of paybill is as follows.
| No | field | name | description |
|---|---|---|---|
| 1 | order_id/refund_no | orderId/refundNo | if trasaction type is payment,it is orderId,Otherwise refundNo |
| 2 | trade_no | UMF-orderId | if trasaction type is refund,it’s refund_UMF_orderId |
| 3 | order_form_time | order create time | order create time |
| 4 | order_finish_time | order payment time | order payment time |
| 5 | product_name | product name | product name |
| 6 | merchant_amount | order amount | order amount |
| 7 | merchant_currency | pricing currency | pricing currency |
| 8 | transaction_rate | trasaction rate | trasaction rate |
| 9 | transaction_amount | RMB amount | RMB amount |
| 10 | fee | fee | fee |
| 11 | net_amount | net payment | net payment |
| 12 | transaction_type | trasaction type | trasaction type,payment/refund |
| 13 | transaction_state | trasaction state | trasaction state |
| 14 | purchase_date | foreign exchange date | foreign exchange date |
| 15 | purchase_rate | foreign exchange rate | foreign exchange rate |
| 16 | reference_foreign_amount | Reference foreign currency amount | Reference foreign currency amount |
| 17 | settle_currency | settle Currency | settle Currency |
| 18 | settle_state | settle state | settle state Y：settled N：unsettlement |
| 19 | settle_date | settle date | settle date |
| 20 | origin_order_id | orderId | the field only exists when refund is needed |
3.32 海关/国检重推
## Request data:
$ curl -s -X POST 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"
}
}'
请求
POST: /declare_again
如清关时出现支付单不存在，且联动侧支付人身份信息通过，商户可调动该接口，UMF会重新上送此笔数据
响应
| Parameter | Description |
|---|---|
| meta | 对象. 响应公共部分. |
| declare_again | 对象. 重推信息. |
3.34 Account refundable balance inquiry
$ 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"
},
"account_balance": {
"balance": "472627.21"
}
}
GET: /payments/payment/self_account_balance
Get refundable balance (Currency:CNY, Units: Yuan)
Response
| name | description |
|---|---|
| meta | object. |
| account_balance | Account balance. |
3.35 Place an order (payment by agreement)
This interface is not open to overseas merchants
3.36 Sending SMS (payment by agreement first sending SMS)
This interface is not open to overseas merchants
3.37 Confirmation of payment (first confirmation of payment by agreement)
This interface is not open to overseas merchants
3.38 Send SMS (send SMS twice for payment by agreement)
This interface is not open to overseas merchants
3.39 Confirm the payment (send text message to confirm the payment twice after the agreement payment)
This interface is not open to overseas merchants
3.40 Confirm the payment (no text message will be sent to confirm the payment after the agreed payment)
This interface is not open to overseas merchants
3.41 Order interface (cancel paymentId)
This interface is not open to overseas merchants
3.42 Payment confirmation (no paymentId)
This interface is not open to overseas merchants
3.43 Order interface (no paymentId)
This interface is not open to overseas merchants
3.44 Payment confirmation (no paymentId)
This interface is not open to overseas merchants
3.45 Order confirmation and payment confirmation (no paymentId)
This interface is not open to overseas merchants
3.46 Order query (no paymentId)
This interface is not open to overseas merchants
3.47 Asynchronous refund (no 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"
}'
## response:
'{
"meta": {
"ret_msg": "success",
"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"
}
}
}'
request
asy_refund：POST:/payments/payment/asy_refund
The payment_id in the url is the real payment ID that was created in the previous step(Create a payment).
This request creates a refund object. The request sends a refund object,and the response is the refund object that UMF created.
UMF supports full or partial refund. Partial refund can be made multiple times.
The refund must be the same currency as the payment and the refund amount must be no more than the total payment amount.
| Parameter | Description |
|---|---|
| asy_refund | Object. The refund object. The order,amount and nofify_url should be entered. |
response
The response includes the refund object. The returned refund object has refund_id and state.
If the state is “REFUND_SUCCESS”,that means the transcation was done and the refund was successufl. If the state is “REFUND_PROCESS”,that means the transaction is pending,when it is done,UMF will send a notification to the merchant. Or the merchant may query refund state by Query refund
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
| asy_refund | object. The refund object. |
3.48 Asynchronous refund query (without paymentId)
## request:
$ 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"
}'
## response:
'{
"meta": {
"ret_msg": "success",
"ret_code": "0000"
},
"asy_refund": {
"mer_refund_id": "1636237315",
"state": "REFUND_PROCESS"
}
}'
POST: /payments/refund/refund_query
Merchant may call this url anytime. UMF will return the refund object. If the state is “REFUND_SUCCESS”,the refund is successful.
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
| asy_refund | object. The refund object. |
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 报国检状态查询
## 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" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/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
此接口需要先调用(报国检).
响应
| Parameter | Description |
|---|---|
| meta | 对象. 响应公共部分. |
| national_inspection | 对象. 海关信息. |
3.54 海关/国检重推（无paymentId）
## Request data:
$ curl -s -X POST https://uatfx.soopay.net/cberest/v1/declare_again
CIQ_GA2TANZTGIYTSNJSGEZDAMJYGA2TANYO \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ea3b83b316d97bd78166475fe36a3f7219d79e8d04bfc784dec424fba0e9462f" \
-H "Signature:qJIC9lz/1TIjEe5rw2Wj8YfvBX3RHyICWNCRmusOu4EeCBcDYNJlWgZCo2/1V1FnZg2alfwSlIAzHetqsEIdDfqy2tlxJriBr7VIIjM3/e9n7TOKGoiHDPuC2/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 Bank Agreement unbundling
$ curl -s -X GET https://uatfx.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"
}
}
Request
POST: /bank_agreement/unbind
This ‘unbinding’ interface will terminate the user’s payment agreement (on the all merchants in UMF) on UMF side and the bank side. So please be careful to call this interface! And when the user calls this interface, please remind the user of this impact!!
| Parameter | Description |
|---|---|
| payer_agreements | object. |
Response
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
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": "0708162829733001",
"tracking_number": "11313258946251003256"
}]
}
}
## Response data:
{
"meta": {
"ret_msg": "交易成功",
"ret_code": "0000"
},
"payment": {
"id": "PAY_GYYDANZQHAYTMMRYHEZDSOJXGMZDAMRQGA3TAOGC",
"order": {
"sub_orders": [{
"mer_sub_reference_id": "0708162829733001",
"tracking_number": "11313258946251003256"
}]
}
},
"links": [{
"ref": "parent_payment",
"method": "GET",
"href": "http://fx.soopay.net/cberest/v1/payments/payment/PAY_GYYDANZQHAYTMMRYHEZDSOJXGMZDAMRQGA3TAOGC"
}]
}
只有货物类型交易,在下单结束后会返回该link
该link用于更新该笔货物交易的物流单号
(1) What is tracking_number format? A:Tracking_number : 64 bits, express company + ‘ ’ + tracking number, like STO 3716523085241 (2)Does Tracking_number update have time limit?
A: Yes. Tracking_number need to updated within 7 days(after order time).
(3) Does this interface support tracking_number(in different sub_order in one order) update in different time?
A: Yes, it supports this function.
(4) Can the tracking_number be updated many times?
A: Yes, and the last information updated will be stored. (5) If one sub_mer_reference_id updated in this interface is wrong, will the other suborder information in the same order be updated unsuccessfully?
A:Yes, all the suborder information will be updated unsuccessfully if one of them updated is wrong
(6) Which type of trade need the merchant to input tracking_number?
A:Goods trade. If the merchant inputs tracking_number in one order not of the type of goods, there is an error return.
request
POST: /payments/payment/{payment_id}/update_express_info
The payment_id in the url is the real payment id that was created in the previous step(Create a payment).
| Parameter | Description |
|---|---|
| payment | Object. The payment object. |
response
| Parameter | Description |
|---|---|
| meta | Object. The common information of response. |
| payment | Object. The payment object. |
| links | Object Array. The next step links. Depends on the status and payment type. Those links are HATEOAS links. |
3.59 upload file
This interface is developed for the study abroad business in Argentina. Merchants need to upload transaction related files through this interface and save the file name returned by the interface. When placing an order, pass the file name into the ordering interface.
File needs to be uploaded: 1. student_identity_filename | Student identity information 2. student_id_filename | Offer or student ID 3. tuition_pay_filename | Tuition Payment List
## 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"
}
request
POST: /file/upload
Argentine study abroad merchants must submit transaction proof documents before placing an order.
response
| param | describe |
|---|---|
| meta | Object. Responding public information. |
| data | Object. The file name for the response. |
4. B2B Reference
4.1 Register a company
## 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"
}
]
}
Request
POST:/enterprise_qualification
The merchant should register their customers in UMF. The status of company is “DISABLE” when it is created. Then the merchant should commit required documents to UMF offline. UMF will commit those documents to the bank where company open their business bank account. If the verication is success, the status will be changed to “ENABLE”.
Parameters:
| Parameters | Description |
|---|---|
| enterprise_qualification | Object. The enterprise qualification information. |
Response
The Response includes meta information and a enterprise_qualification object. See the example.
4.2 Query register status
## Request data:
curl -s -X GET \
https://uatfx.soopay.net/cberest/v1/enterprise_qualification/EQ_GEYDAMBQGEZDK7CHIZEEOMRQGE3TANRRGNJQ
## 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",
"enterprise_status": "ENABLE",
"rank": "A",
"enterprise_name": "华西电子商务有限公司"
}
}
Request
GET:/enterprise_qualification/enterprise_id
This is a http get request. The parameter should be replaced by the real id of enterprise_qualification object.
Response
Parameters:
| Parameters | Description |
|---|---|
| enterprise_qualification | Object. The enterprise qualification information. |
4.3 Create a payment
## 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": {
"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"
}
]
}
POST: /payments/payment
Creates a payment for B2B business. The payer must use a business bank account.
| Parameters | Description |
|---|---|
| payer | Object. The payment information. |
| order | Object. The order information. Includes sub orders. |
| notify_url | String. Url of the merchant server. To receive the payment result. |
Response:
| Parameters | Description |
|---|---|
| payer | Object. The payment information. |
| order | Object. The order information. Includes sub orders. |
| notify_url | String. Url of the merchant server. To receive the payment result. |
| links | Object Array. The next step links. Depends on the status and payment type. Those links are HATEOAS links. |
Payment result notification
After processing the payment request data of the merchant, UMF will call merchant’s service with the payment result.
Merchant should give a response after receiving the call.
It is the same with B2C notification. See 3.5 Payment result notification
4.4 Upload transaction files
After the success of payment, The merchant should upload all the document of the transaction via FTP protocol. The address, username, password should be given by UMF once the merchant account was created.
The rules of file upload:
- Every payment need to upload related files.
- The files should include the contact and the invoice.
- All the files of one transaction should be compressed into one file. The format is ZIP.
- Merchant only have the write privillage of FTP folder, The uploaded file can not be deleted by merchant.
- The file name should follow the rule: mer_reference_id + mer_date + sequence_num(4 digitals).zip. The mer_reference_id and mer_date should be the same with the created payment. The sequence_num is the sequence of the same payment. If the uploaded file have some error, the merchant needs to upload another zipped file with different sequence number.
- The uploaded files will be verified by the staffs of UMF. Once the verification is done, UMF exchange the money from CNY to other currency. If the verification does not pass within 24 hours, the payment will be canceled. The money will be returned to payer.
4.5 Query a payment
It is the same with B2C query a payment. See 3.6 Query a payment
4.6 Create a refund
It is the same with B2C create a refund. See 3.7 Create a refund
4.7 Query a refund
It is the same with B2C query a refund. See 3.8 Query a refund
4.8 Query transactions
It is the same with B2C Query transactions. See 3.14 Query transactions
4.9 Query reconciliation statement
It is the same with B2C download reconciliation list. See 3.15 Query reconciliation statement
4.10 Query exchange rate
Get the real-time exchange rate. The returned information is the corresponding amount of CNY.
5. Object Definitions
amount
| Parameter | Description | constraints |
|---|---|---|
| total | The total amount charged or refunded. | Maximum length is 12 digits including 2 decimal places. |
| currency | The three-character currency code ISO-4217. | |
| total_cny | The amount in CNY(Chinese Yuan). | Optional. Maximum length is 12 digits including 2 decimal places. |
| exchange_rate | The exchange_rate. | Optional. Object |
bank
| Parameter | Description | constraints |
|---|---|---|
| name | The full name of bank.English. | Lengths from 1 to 256 characters. |
| name_zh | The full name of bank. | Lengths from 2 to 16 characters. |
| code | The abbreviation of bank. Available in China. See banks supported by credit card payment and debit card payment. | ENUM |
| logo_url | The url of the logo of bank. | |
| types | The bank types are supported by the bank. Allowed values: CREDIT_CARD, DEBIT_CARD | Array. |
| is_support | UMF support it or not , values: Y: support this bank N: not support this bank |
ENUM |
bank_card
One of the payment object, some parametrs must be encrypted, see how to encrypt.
| Parameter | Description | constraints |
|---|---|---|
| number | The card number. | Must be encrypted |
| valid_date | The valid date of bank card. | Must be encrypted The format is YYMM |
| cvv2 | CVV2 of bank card. | Must be encrypted |
| payer_name | The name of card holder. | Must be encrypted |
| phone | The phone number registered in the bank card issuer. | |
| citizen_id_type | The type of citizen id. Currently, it must be IDENTITY_CARD. | ENUM |
| citizen_id_number | Citizen id number. | Must be encrypted |
| verify_code | String. Only available in bank_card payment. The bank should send a verification code to customer. This verification code will be submitted to bank to prevent fraud. | Lengths from 4 to 8 digital. |
customs_declaration
| Parameter | Description | constraints |
|---|---|---|
| id | ID of this object. | |
| sub_order | The sub_order object. | Object. |
| customs_id | The customs channel number during customs declaration. NB for NingBo Customs GZHG for GuangZhou Customs HZHG for HangZhou Customs |
ENUM |
| mer_customs_code | The merchant ID in customs. | Lengths from 1 to 15 characters. |
| freight_amount | Amount object. Freight payment. | Object |
| tax_amount | Amount object. Customs tax. | Object |
| ec_plat_id | Account number of E-commerce platform in Customs’s system. | Lengths from 4 to 60 characters. |
| notify_url | The url of merchant service. To receive the notification from UMF. | Lengths from 1 to 256 characters. |
| state | ACCEPTED SUBMITTED SUCCESS FAIL. |
ENUM |
| customs_clearance_date | request customs date. | format is yyyymmdd |
| verify_department | verified Department verified Department： UnionPay NetsUnion Others（Express,E-Bank） |
String. |
| verify_department_pay_trace | verified Department Pay Trace Pay Trace from verified Department | String. |
| mer_date | The order date. | String yyyyMMdd. |
declare_again
| Parameter | Description | constraints |
|---|---|---|
| declare_type | Customs or state inspection 0 customs; 1 the inspection | String 0 |
| mer_reference_id | Customs order no. | Lengths from 4 to 32 characters. |
exchange_rate
| Parameter | Description | constraints |
|---|---|---|
| currency | The three-character currency code ISO-4217.The code of currency. | ENUM |
| rate | The exchange rate. | Maximum length is 18 digits including 8 decimal places. |
enterprise_qualification
The qualification of enterprise. It is used in B2B business.
| Parameter | Description | constraints |
|---|---|---|
| id | ID of this object. | |
| external_enterprise_id | The id of enterprise in Merchant’s system. | Lengths from 1 to 16 characters. |
| enterprise_name | The name of enterprise. | Lengths from 1 to 256 characters. |
| enterprise_phone | the phone number of contact. | the phone number base on China |
| enterprise_email | The email of contact. | |
| enterprise_contact | The name of contact . | |
| rank | 企业状态 枚举值 A: 表示该企业是A类企业,可做货物、服务类交易 OTHERS:表示该企业还未确认,可做服务类交易 UNKNOWN:表示该企业是非A类企业,不可做交易 |
ENUM. |
| busi_type | The business type of the company. -SJHG: For the company which exchange money to CNY. -GFHG: For the company which exchange money from CNY. |
ENUM |
| enterprise_code | The unified social credit code system for legal entities and other organizations. See Uniform Social Credit Code (中文版: 统一社会信用代码) | Lengths from 8 to 18 characters. |
item
Item is the information of same goods in a sub_order object.
| Parameter | Description | constraints |
|---|---|---|
| mer_item_id | The ID in merchant system. | Lengths from 1 to 32 characters. |
| type | The type of goods. CLOTHING FOOD ELECTRONIC COSMETIC HOUSEHOLD_ITEMS |
ENUM |
| name | The goods name. | Lengths from 1 to 256 characters. |
| description | The description of goods. | Lengths from 1 to 64 characters. |
| amount | The amount object. The price of goods. | it is required |
| quantity | Number. The quantity of goods. | Maximum length is 2 |
link
The link object is a part of payment object, refund object. It is the next available step of those objects. The link depends on the state of object.
| Parameter | Description | constraints |
|---|---|---|
| href | It may be the object or the available actions of the object. | URL |
| ref | The relation of url and the object. | Lengths from 1 to 16 characters. |
| method | The http method. POST, GET | ENUM |
meta
The meta object is one part of each response. It includes the common information of response.
| Parameter | Description |
|---|---|
| ret_code | The return code of current response. |
| ret_msg | The message of current response. |
order
The order information. The detail information of order items must be in the sub_order object.
| Parameter | Description | constraints |
|---|---|---|
| amount | The total amount of an order. | |
| expire_time | Order Valid Time: 24 hours(default) unit: minute . If the time expires, UMF will not execute the payment. | unit in minute |
| mer_reference_id | The ID of order. The same order ID of a merchant will pay only once. | Lengths from 4 to 32 characters. |
| mer_date | The order date. This time will show as-is in the statement. | format is yyyymmdd |
| order_summary | The summary of an order. | Lengths from 1 to 32 characters. |
| sub_mer_id | Sub merchant Id. | Lengths from 1 to 8 characters. |
| sub_orders | Object Array. The array of sub_order objects. Each sub_order can only have same type goods. | |
| user_ip | This is the IP address when a customer makes a payment request.(WeChat APP and WeChat public number, this field is required) when interface_type=SERVER_TO_SERVER,this field is required |
|
| if_sms | Do you want to verify the SMS string |
N not verified Y verified |
| school_locate_city | School City | String. Max length 255 |
| school_name | School name | String. Max length 127 |
| student_name | Student name (each order corresponds to a single individual) | String. Encrypted. Maximum length 255 |
| student_id | Admission letter number/student ID number | String. Maximum length 65 |
| enrollment_date | Enrollment date | String. Max length 8 |
| student_identity_filename | Student identity information | String. Max length 127 |
| student_id_filename | Offer or Student ID | String. Max length 127 |
| tuition_pay_filename | Tuition payment list | String. Max length 127 |
pagination
Some API endpoints which return large amount of objects will return paginated responses; as well as the list of objects there will also be a pagination key in the response:
| Parameter | Description | constraints |
|---|---|---|
| total_count | Number. The total number of transaction list. | |
| page_number | Number. The current page number (starts at 1). | Lengths from 1 to 7 characters. |
| page_size | Number. The number of objects on each page. | Lengths from 1 to 3 characters. |
payer
The payer information.
| Parameter | Description | constraints |
|---|---|---|
| payment_method | The payment method. The value should be one of the following: - CREDIT_CARD : Pay by credit card. See the workflow chart of bank card payment. - DEBIT_CARD: Pay by debit card. See the workflow chart of bank card payment. - WECHAT_SCAN: UMF return a QR-Code String. The customer may use their WeChat scan the QR-Code to pay. See the workflow chart of QR Code scan payment. - WECHAT_IN_APP: The customer may pay for the order inside a native app. See the workflow chart of Wechat In-App payment. - WECHAT_WEB: The customer may pay for the order inside the WeChat browser. See the workflow chart of In-App Web-based payment. - WECHAT_H5: The customer may pay for the order outside the WeChat browser. See the workflow chart of Web-based H5 payment. - ALIPAY_SCAN: UMF returns a QR-Code String. The customer may use their Alipay to scan the QR-Code to pay. See the workflow chart of QR Code scan payment. - NOT_APPLICABLE: When interface_type is either SERVER_TO_WEB or DIRECT_TO_BANK. |
ENUM |
| bank_code | String. The abbreviation of bank. Available in China. See Banks | |
| business elements object | Object. The name of this parts is different, depends on the business_type. It can be the following objects. payer_info for B2C. enterprise_qualification for B2B. |
|
| interface_type | The type of payment interface. The value should be one of the following: - SERVER_TO_SERVER : API call - SERVER_TO_WEB : Server to UMF website - SERVER_TO_H5WEB : Server to UMF H5 website - DIRECT_TO_BANK : Online bank, if payment_method is NOT_APPLICABLE then bank_code must be send. |
ENUM |
| business_type | The value should be one of the following: - B2B : Business to business. - B2C : Business to consumer. |
ENUM. |
| external_customer_id | The customer id in merchant system. | Lengths from 1 to 32 characters. |
Available payment_method for each interface_type and business_type.
| interface_type | B2C | B2B |
|---|---|---|
| SERVER_TO_SERVER | CREDIT_CARD DEBIT_CARD WECHAT_SCAN WECHAT_IN_APP WECHAT_WEB WECHAT_H5 ALIPAY_SCAN |
|
| SERVER_TO_WEB | NOT_APPLICABLE | |
| DIRECT_TO_BANK | WECHAT_SCAN ALIPAY_SCAN |
NOT_APPLICABLE |
| SERVER_TO_H5WEB | NOT_APPLICABLE |
payer_agreement
Payer agreement represents a card of the customer. Merchant may use this object instead of bank_card object for security.
| Parameter | Description | constraints |
|---|---|---|
| usr_busi_agreement_id | This ID is a unique ID for each user of a merchant. | Lengths from 1 to 64 characters. |
| usr_pay_agreement_id | This ID is a unique ID for each card of a usr_busi_agreement_id. | Lengths from 1 to 64 characters. |
| gate_id | The bank code. As same as bank code, See banks supported by credit card payment and debit card payment. | ENUM |
| last_four_cardid | The last four card numbers. | Lengths are 4 characters. |
| valid_date | The valid date of card. | Must be encrypted |
| cvv2 | The CVV2 of card. | Must be encrypted |
| verify_code | String. Only available in bank_card payment. The bank should send a verification code to customer. This verification code will be submitted to bank to prevent fraud. | Lengths from 4 to 8 digital. |
pay_info
The pay_info object includes the information of WeChat In-App Payment and WeChat In-App Web-based Payment.
| Parameter | Description | constraints |
|---|---|---|
| app_id | String. The unique identifier of the Official Account of UMF | |
| time_stamp | The number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970. see date and timeformat |
YYYY-MM-DDThh:mm:ssTZD |
| sign_type | The type of signature. It will be “MD5” in this scenario. | ENUM |
| package | String. The ID of this WeChat payment. | |
| nonce_str | String. A random string for the generated signature. | |
| pay_sign | String. The signature of this request. |
payer_info
The information of payer.
| Parameter | Description | constraints |
|---|---|---|
| phone | The payer’s phone number. | String |
| name | The name of payer. | Must be encrypted |
| pay elements object | The name of this parts is different, depends on the payment_method. It can be the following objects. bank_card. For pay_type: CREDIT_CARD, DEBIT_CARD qr_code_scan. For pay_type: WECHAT_SCAN, ALIPAY_SCAN wechat_in_app For pay_type: WECHAT_IN_APP wechat_in_app_web For pay_type: WECHAT_WEB payer_agreement For pay_type: CREDIT_CARD, DEBIT_CARD wechat_H5 For pay_type: WECHAT_H5 |
Object |
payment
Payment object is the core concept of this API. It has the following information:
| parameters | Description | constraints |
|---|---|---|
| id | The ID of payment object. UMF will response it. | |
| payer | The payment information. | Object |
| order | The order information. Includes sub orders. | Object |
| state | -WAIT_BUYER_PAY: The payment need to be paid. -TRADE_SUCCESS: The payment was succcessufl. -TRADE_CLOSED:The payment was closed because the order was expired. -TRADE_CANCEL: The payment was cancelled. -TRADE_FAIL: The payment was failed. |
ENUM |
| notify_url | Url of the merchant server. To receive the payment result. | Lengths from 1 to 128 characters. |
| ret_url | The return url after the payment was done. Only availabled when the merchant uses the checkout web page of UMF. | Lengths from 1 to 128 characters. |
| execute_success_time | The time of transfer money from customer to UMF. | |
| mer_check_date | The date of this transaction. This date is from merchant system. It does not have timezone information. The transaction will be marked as this date in the transaction list and the reconciliation statement. | YYYYMMDD |
| settle_date | The date of this transaction in UMF. | YYYYMMDD |
| risk_info | The information for anti fraud. Its content depends on the contract between the merchant and UMF. | Object |
payment_summary
The summary of a payment object. It is contained in a transactions object or a reconciliations object.
| Parameter | Description | constraints |
|---|---|---|
| payment_id | The id of payment. | |
| phone_number | User’s phone number. Only available in transactions object. | |
| order_date | The date of order placed. | YYYYMMDD |
| mer_reference_id | The reference id of the order. | Lengths from 4 to 32 characters |
| amount | Includes the following parameters: total, total_cny, currency, exchange_rate. | Object. |
| settle_date | The date of charge request submitted. | YYYYMMDD |
| execute_success_time | The timestamp of charge. The timestamp of transaction done. | |
| state | See the define of payment. | |
| product_id | The product id of UMF. | Lengths 8 characters |
| service_fee | The service fee in CNY. Only available in reconciliations object. | |
| exchange_amount | The amount of make exchange, it is an amount object. Includes the following parameters: total, total_cny, currency, exchange_rate. Only available in reconciliations object. | Object. |
| exchange_date | The date of making exchange. Only available in reconciliations object. | YYYYMMDD |
qr_code_scan
Merchant creates QR code for each order. After users scan these codes by WeChat or AliPay, they can see related product information and transaction guides on their phone. This object can be used for WeChat or AliPay.
If the merchant want to show a QR-Code to customer for scanning, a wechat_qr_code object needs to include in the payer_info object.
| Parameter | Description | constraints |
|---|---|---|
| citizen_id_type | The type of citizen id. Currently, it must be IDENTITY_CARD. | ENUM |
| citizen_id_number | Citizen id number. | Must be encrypted |
| qr_code_url | String. The url of wechat QR-Code pay. This information is returned by UMF. |
The qr_code_url is the content of QR-Code. The merchant use standard tools transfer the url to a QR-Code. When user scan this QR-Code by WeChat or AliPay, they can pay with WeChat or AliPay.
reconciliations
The information of reconciliations.
| Parameter | Description | constraints |
|---|---|---|
| payment_summaries | Object Array of payment_summary. | |
| refund_summaries | Object Array of refund_summary. | |
| settle_date | The settlement date. | YYYYMMDD |
| amount | The total amount of this reconciliations. | |
| pagination | The pagination Object which gives you information about the number of pages in the result, and how many objects are returned. |
refund
Refund objects allow you to refund a payment that has previously been paid but not yet refunded. Funds will be refunded using the original method of payment.
| Parameters | Description | constraints |
|---|---|---|
| id | The ID of refund object. This information is returned by UMF. | |
| refund_info | It contains the refund mer_reference_id and the information of goods to be refunded. | |
| notify_url | The merchant service url. To receive the refund result. | Lengths from 1 to 128 characters. |
| state | The state of refund object. REFUND_PROCESS REFUND_SUCCESS REFUND_FAIL REFUND_CLOSE REFUND_RETRY |
ENUM |
refund_info
The refund information. The detail information of refund items must be in the sub_order object.
| Parameter | Description | constraints |
|---|---|---|
| mer_reference_id | The unique ID of each refund. | Lengths from 4 to 32 characters |
| mer_date | The refund date. This time will show as-is in the statement. | YYYYMMDD |
| amount | The refund amount of an order. | |
| refund_summary | The summary of an refund. | Lengths from 1 to 64 characters |
| sub_orders | Object Array. 1. One refund can contains more than one sub_order. The mer_sub_reference_id of refund sub_order should be the same as the ID of payment sub_order and refund amount is equal to the total amount of sub-orders to be refunded. 2. The paramter of trans_code should be sent and if it is 01122030 which means Goods trade then items should be sent. |
refund_summary
The summary of a payment object. It is contained in a transactions object or a reconciliations object.
| Parameter | Description | constraints |
|---|---|---|
| refund_id | The id of refund. | |
| payment_id | The id of parent payment. | |
| phone_number | User’s phone number. Only available in transactions object. | |
| amount | Object. Includes the following parameters: total, total_cny, currency, exchange_rate. | |
| settle_date | The date of refund request submitted. | YYYYMMDD |
| execute_success_time | The timestamp of transaction done. see date and timeformat | YYYY-MM-DDThh:mm:ssTZD |
| state | See the define of refund. | |
| mer_sub_reference_id | The reference id of sub-order. Only available in reconciliations object. |
risk_info
This object is the information of transaction. UMF uses this info to approve or deny the transaction. If the risk of fraud is too high, this transaction will be denied. The anti fraud algorithm will be periodically adjusted.The following parameter values are string types.
| Field name | desc | Field description | Send or not |
|---|---|---|---|
| goods_type | Category of commodities | ENUM. 0 virtual goods 1 physical goods 2 air ticket 3 electronic |
Y |
| real_name | Real name purchase | ENUM. 0 not real name system 1 real name system |
Y |
| business_type | Category of business | ENUM 3 Cross-border Payment |
Y |
| trans_type | Transaction type | ENUM. 01 Deposit 02 Purchase |
Y |
| receiver_name | Name of the recipient | When goods_type is either 1 or 3, it is required to send this field. |
C |
| receiver_moblie_id | Phone number of the recipient | When goods_type is either 1 or 3, it is required to send this field. Such as: 13800011111 |
C |
| receiver_address | Delivery address | When goods_type is either 1 or 3, it is required to send this field. |
C |
| registration_identify_code | identity card number | Registrant identity card number, When real_name is 1, it is required to send this field. |
C |
| registration_email | Registered email | Email of the customer used for registration, must be verified by the merchant | N |
| registration_moblie_id | mobile phone number | Registrant mobile phone number | N |
| device_id | Device identification | For example, the MAC code of mobile phone or the terminal identification ID defined internally. | N |
| device_type | Type of Device | If from the Web terminal, the user shall not be blank. APP can be blank. | N |
| user_id | User ID | UserID at the merchant platform | N |
| registration_time | User Registration time | The time that the user registers for the product, which shall be read exactly on the second. Such as:20150311120000 |
N |
| user_agent | Production form | ENUM. 1 android app 2 IOS app 3 PC (web page) 4 Mobile phone(wap, or html5 page); |
N |
| success_transactions_number | The number of successful transactions | The number of successful transactions on the merchant platform | N |
| is_receiver_bank_num | If the receiver’s mobile phone number is the same with user regirested in the bank. | ENUM. 0 not same 1 same |
Y |
| registration_days | The days the user has registered. | for example: three days | Y |
sub_order
The same trans_code of goods should in the same sub_order object.
| Parameter | Description | constraints |
|---|---|---|
| mer_sub_reference_id | The ID of sub_order object. | Lengths from 4 to 16 characters. |
| amount | The amount of sub_order. | |
| order_summary | The summary of sub_order. | Lengths from 1 to 32 characters |
| trans_code | The transaction code of goods. See Transaction encoding and transaction postscript description | ENUM |
| is_customs | If the merchant needs UMF to submit the payment information to customs. TRUE FALSE |
ENUM |
| invoice_id | This receipt of sub_order. | Lengths from 1 to 20 characters. |
| items | The array of item objects. | Object Array（The field must be submitted if trasaction type is goods） |
| sub_customs_trace | the trace of custom（The merchant don’t need to submit）. | Lengths 20 characters. |
| tracking_number | 物流单号.（更新物流单号时上传）. | Lengths 64 characters. |
transactions
The information of transactions.
| Parameter | Description | constraints |
|---|---|---|
| payment_summaries | Object Array of payment_summary. | |
| refund_summaries | Object Array of refund_summary. | |
| pagination | Object. The pagination Object which gives you information about the number of pages in the result, and how many objects are returned. |
wechat_in_app
The UMF will return all the information that WeChat SDK required to activate WeChat and make a payment. Some parametrs must be encrypted, see how to encrypt.
| Parameter | Description | constraints |
|---|---|---|
| citizen_id_type | The type of citizen id. Currently, it must be IDENTITY_CARD. | ENUM |
| citizen_id_number | Citizen id number. | Must be encrypted |
| pay_info | The information for calling WeChat native SDK to activate WeChat APP. |
wechat_in_app_web
The UMF will return all the information that WeChat SDK required to activate WeChat and make a payment. Merchant does not need to modify all the information that WeChat need. Some parametrs must be encrypted, see how to encrypt.
| Parameter | Description | constraints |
|---|---|---|
| open_id | String. The OpenID is a unique encrypted WeChat ID for each user of an official account, and users can have separate OpenIDs corresponding to different official accounts. | |
| citizen_id_type | The type of citizen id. Currently, it must be IDENTITY_CARD. | ENUM |
| citizen_id_number | Citizen id number. | Must be encrypted. |
| pay_info | Object. The information for calling WeChat JS-API to activate WeChat payment in WeChat browser. |
wechat_H5
The UMF will return all the information that WeChat SDK required to activate WeChat and make a payment. Some parametrs must be encrypted, see how to encrypt.
| Parameter | Description | constraints |
|---|---|---|
| citizen_id_type | The type of citizen id. Currently, it must be IDENTITY_CARD. | ENUM |
| citizen_id_number | Citizen id number. | Must be encrypted. |
| wechat_h5_url | after url encoded wechat h5 url | urlEncode |
settle_month_file
Settle Month Statements
| Parameter | Description | constraints |
|---|---|---|
| settle_month | settle month | Lengths 6 characters. |
national_inspection
national_inspection
| Parameter | Description | constraints |
|---|---|---|
| id | ID of this object. | |
| sub_order | The sub_order object. | Object. |
| mer_date | The order date. This time will show as-is in the statement. | format is yyyymmdd |
| ciq_code | The ciq channel number during ciq declaration. | for example: GJHP |
| plat_supplier_no | Account number of E-commerce platform in ciq’s system. | Lengths from 4 to 60 characters. |
| ciq_clearance_date | request ciq date. | format is yyyymmdd |
customs_declaration_only
customs_declaration_only
| Parameter | Description | constraints |
|---|---|---|
| id | ID of this object. | |
| mer_reference_id | The ID of order. The same order ID of a merchant will pay only once. | Lengths from 4 to 30 characters. |
| order_amount | Amount object. Freight payment. | Object |
| name | The name. | Lengths from 1 to 256 characters. |
| citizen_id_type | The type of citizen id. Currently, it must be IDENTITY_CARD. | ENUM |
| citizen_id_number | Citizen id number. | Must be encrypted |
| mer_pay_date | request pay date. | format is YYYYMMDD |
| mer_pay_time | request pay time. | format is HHmmss |
| phone | payer mobile number. | |
| customs_id | The customs channel number during customs declaration. NB for NingBo Customs GZHG for GuangZhou Customs HZHG for HangZhou Customs |
ENUM |
| mer_customs_code | The merchant ID in customs. | Lengths from 1 to 15 characters. |
| ec_plat_id | Account number of E-commerce platform in Customs’s system. | Lengths from 4 to 60 characters. |
| freight_amount | Amount object. Freight payment. | Object |
| tax_amount | Amount object. Customs tax. | Object |
| state | ACCEPTED SUBMITTED SUCCESS FAIL. |
ENUM |
| customs_clearance_date | request customs date. | format is yyyymmdd |
| pay_trace | Original payment flow number.Not required.It will return this if not input | String.Lengths from 4 to 32 characters. |
| notify_url | customs notify url. | |
| paye_code | paye_code.Customer CIQ record number. If the customer applies for Pingtan Customs and applies for CIQ at the same time, the field is required. | String. |
| goods_info | Goods Information | String. |
| tracking_number | Logistics Document Number | String. |
bind
Contract information
| Parameter | Description | constraints |
|---|---|---|
| id | id(You don’t need to send it up when you ask to sign) | String. |
| number | card number | String. Must be encrypted. |
| citizen_id_number | Id card number. | String. Must be encrypted. |
| citizen_id_type | The current citizenship type. The enumeration value is*IDENTITY_CARD* | Enum. |
| name | payer name. | String. Must be encrypted.String.Lengths from 1 to 128 characters. |
| phone | Bank reserve number. | String. |
| bank_code | Bank hereinafter referred to as. | String. |
| verify_code | verify code. | String. |
bind_payment
One-click payment object is the core of API interface. It contains the following information:
| Parameter | Description | constraints |
|---|---|---|
| id | id.(The ID of payment object. UMF will response it.) | String |
| order | Order information. Contains sub-orders. | Object |
| state | -WAIT_BUYER_PAY: The payment need to be paid. -TRADE_SUCCESS: The payment was succcessufl. -TRADE_CLOSED:The payment was closed because the order was expired. -TRADE_CANCEL: The payment was cancelled. -TRADE_FAIL: The payment was failed. |
ENUM |
| ret_url | The return url after the payment was done. Only availabled when the merchant uses the checkout web page of UMF. | Lengths from 1 to 128 characters. |
| notify_url | Url of the merchant server. To receive the payment result. | Lengths from 1 to 128 characters |
| execute_success_time | The time of transfer money from customer to UMF. | |
| mer_check_date | The date of this transaction. This date is from merchant system. It does not have timezone information. The transaction will be marked as this date in the transaction list and the reconciliation statement. | YYYYMMDD |
| settle_date | The date of this transaction in UMF. | YYYYMMDD |
| risk_info | The information for anti fraud. Its content depends on the contract between the merchant and UMF. | |
| usr_pay_agreement_id | String. User’s payment protocol number. | |
| bank_code | String. The abbreviation of bank. Available in China. Seebanks |
account_balance
Account balance. It contains the following information:
| Parameter | Description | constraints |
|---|---|---|
| balance | Refundable balance (Currency:CNY, Units: Yuan) | String |
ciq_declaration_only
独立报检信息
| 参数 | 描述 | 约束 |
|---|---|---|
| id | ID of this object. | |
| ciq_id | The ciq channel number during ciq declaration. HPGJ for HuangPu Ciq |
ENUM |
| mer_ciq_code | The merchant ID in ciq. | Lengths from 1 to 15 characters. |
| ec_plat_id | Account number of E-commerce platform in Ciq’s system. | Lengths from 4 to 60 characters. |
| state | ACCEPTED SUBMITTED SUCCESS FAIL. |
ENUM |
| ciq_clearance_date | request customs date. | format is yyyymmdd |
| pay_trace | Original payment flow number.Not required | String.Lengths from 4 to 32 characters. |
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 Enterprise Qualification Report Information
| Parameter | Description | constraints |
|---|---|---|
| cust_code | Unified Social Credit Code or Organization Code. | String.Lengths from 1 to 18 characters.(Must be encrypted). Required |
| cust_name | Organization Name. | String.Lengths from 1 to 128 characters.(Must be encrypted). Required |
| area_code | Residence/place of business. | String.Lengths from 6 characters. Required Must be a record that exists in the administrative division table, but cannot select 100000 |
| cust_addr | Company Registered Address. | String.Lengths from 1 to 200 characters(Must be encrypted). |
| industry_code | Industry attribute code. | String.Lengths from 4 characters. Required Must be the most subdivided record present in the Industry Attribute Code table |
| attr_code | Economic Type Code. | String.Lengths from 3 characters. Required Must be the most subdivided record present in the Economic Type Code table |
| country_code | Country code of residence. | String.Lengths from 3 characters. Required Letter code, see the dictionary table country (region) code for details |
| is_tax_free | Whether it is an enterprise in the special economic zone. | String.Lengths from 1 characters. Required N-Enterprises in non-special economic zones Y-Enterprises in special economic zones |
| tax_free_code | Business Type Code. | String.Lengths from 2 characters. Required When ISTAXFREE=N, only 00-general trade area can be entered, which must be a record in the special economic zone type code table; Input other than 00 when ISTAXFREE=Y. See Types of Enterprises in Special Economic Zones |
| rep_nm | Enterprise legal person name. | String.Lengths from 1 to 128 characters.(Must be encrypted). |
| cert_type | Enterprise legal person certificate type. | String.Lengths from 2 characters. 1- ID card |
| cert_num | Enterprise legal person ID number. | String.Lengths from 1 to 18 characters(Must be encrypted). |
| phone | Enterprise legal person contact number. | String.Lengths from 11 characters(Must be encrypted). |
| cont_aact | Unit contact name. | String.Lengths from 1 to 18 characters(Must be encrypted). Required |
| company_phone | Unit contact phone number. | String.Lengths from 11 characters(Must be encrypted). Required |
query_enterprise
Enterprise qualification submission request information
| Parameter | Description | constraints |
|---|---|---|
| cust_code | Unified Social Credit Code or Organization Code. | String.Lengths from 1 to 18 characters.(Must be encrypted).Required |
| cust_name | Organization Name. | String.Lengths from 1 to 128 characters.(Must be encrypted) |
query_enterprise_id
Enterprise qualification report result information
| Parameter | Description | constraints |
|---|---|---|
| cust_code | Unified Social Credit Code or Organization Code. | String.Lengths from 1 to 18 characters. Required Encrypt as parameter |
| cust_name | Organization Name. | String.Lengths from 1 to 128 characters. Required Encrypt as parameter |
| cust_no | Merchant ID. | String.Lengths from 4 to 8 characters. Required |
| trace_date | submission date. | String.Maximum Lengths of 20 characters. Required Format：yyyy-MM-dd HH:mm:ss |
| area_code | Residence/place of business. | String.Lengths from 6 characters. Required Must be a record that exists in the administrative division table, but cannot select 100000 |
| cust_addr | Company Registered Address. | String.Lengths from 1 to 200 characters. |
| industry_code | Industry attribute code. | String.Lengths from 4 characters. Required Must be the most subdivided record present in the Industry Attribute Code table |
| attr_code | Economic Type Code. | String.Lengths from 3 characters. Required Must be the most subdivided record present in the Economic Type Code table |
| country_code | Country code of residence. | String.Lengths from 3 characters. Required Letter code, see the dictionary table country (region) code for details |
| is_tax_free | Whether it is an enterprise in the special economic zone. | String.Lengths from 1 characters. Required N-Enterprises in non-special economic zones Y-Enterprises in special economic zones |
| tax_free_code | Business Type Code. | String.Lengths from 2 characters. Required When ISTAXFREE=N, only 00-general trade area can be entered, which must be a record in the special economic zone type code table; Input other than 00 when ISTAXFREE=Y. See Types of Enterprises in Special Economic Zones |
| rep_nm | Enterprise legal person name. | String.Lengths from 1 to 128 characters. |
| cert_type | Enterprise legal person certificate type. | String.Lengths from 2 characters. 1- ID card |
| cert_num | Enterprise legal person ID number. | String.Lengths from 1 to 18 characters. |
| phone | Enterprise legal person contact number. | String.Lengths from 11 characters. |
| status | Declaration status. | String.Lengths from 1 characters. Required 0-Not declared 1-Declared successful 9-Processing 3-Declared failed |
| desc | Description of declaration status. | String.Lengths from 1 to 600 characters. Required |
b2bouter_order
Transaction Details
| Parameter | Description | constraints |
|---|---|---|
| mer_batchno | Merchant batch number | String.Maximum Lengths of 16 characters.Required |
| mer_orderId | Merchant order number | String.Maximum Lengths of 64 characters.Required |
| contract_no | Transaction contract number or order number | String.Maximum Lengths of 128 characters.Required |
| contract_date | Contract date | String.Maximum Lengths of 8 characters.Required Format:YYYYMMDD |
| business_code | Service code | String.Maximum Lengths of 8 characters.Required |
| val_pattern | Pricing method Enumeration value | Enumeration .Required -CNY_VALUATION: RMB pricing. -FOREIGN_VALUATION: Foreign currency pricing. -RMB_PAYMENT: Cross-border RMB payments. |
| currency | Currency | String. Fixed length 3.Required |
| Damount | Transaction amount | String. Maximum length 12 .Required. When the pricing type is denominated in a foreign currency, the amount is the amount in the foreign currency. When the pricing type is denominated in RMB, the amount is the amount in RMB |
| order_sub_type | Transaction ID | When the business code is 01121990, 01122030, you need to fill in (code: 1 clothing, 2 food, 3 electronic products, 4 others) When the business code is under trade in services, you need to fill in (5 hotel accommodation, 6 air tickets, 7 study abroad, 8 others).Required |
| logistics_no | Logistics tracking number | String. Maximum length 64.Required |
payment_sub
Payment Form Submission Information
| Parameter | Description | constraints |
|---|---|---|
| mer_batchno | Merchant batch number | String.Maximum Lengths of 16 characters.Required |
| payee_account | Recipient account number | String(Must be encrypted).Required |
| business_code | Service code | String.Maximum Lengths of 8 characters.Required |
| currency | Currency | String.Fixed length 3.Required |
| val_pattern | Pricing method Enumeration value | Enumeration .Required -CNY_VALUATION: RMB pricing. -FOREIGN_VALUATION: Foreign currency pricing. -RMB_PAYMENT: Cross-border RMB payments. |
| remit_information | Remittance Postscript | String. Maximum length 64.Required |
| Oamount | Transaction amount | String. Maximum length 12.Required |
| cost_way | Whether the full amount is received | Enumeration.Required Enumeration value -FULL_AMOUNT: Full amount. -UN_FULL_AMOUNT: Not in full. |
query_order
Payment order transaction query information
| Parameter | Description | constraints |
|---|---|---|
| trade_no | Third Party System Transaction Number. | String.Maximum Lengths of 20 characters. Required |
| fee | handling fee. | String.Maximum Lengths of 12 characters. Required |
| buy_rate | foreign exchange rate. | String.Maximum Lengths of 8 characters. This value is only available in foreign currency transactions |
| pay_amt | Payment amount. | String.Maximum Lengths of 12 characters. Required |
| payee_account | Payee account. | String.Maximum Lengths of 32 characters. Required |
| payee_name | Payee name. | String.Maximum Lengths of 200 characters. Required |
| currency | Transaction currency. | String.Lengths from 3 characters. Required |
| trace_date | transaction date. | String.Maximum Lengths of 20 characters. Required Format：yyyy-MM-dd HH:mm:ss |
6. Errors
API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request – The server cannot or will not process the request due to an apparent client error. |
| 401 | Unauthorized – Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. |
| 403 | Forbidden – The request was valid, but the server is refusing action. |
| 404 | Not Found – The requested resource could not be found but may be available in the future. |
| 405 | Method Not Allowed – A request method is not supported for the requested resource; for example, a GET request on a form that requires data to be presented via POST, or a PUT request on a read-only resource. |
| 406 | Not Acceptable – The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request. |
| 410 | Gone – Indicates that the resource requested is no longer available and will not be available again. |
| 429 | Too Many Requests – The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes. |
| 500 | Internal Server Error – A generic error message, given when an unexpected condition was encountered and no more specific message is suitable. |
| 503 | Service Unavailable – The server is currently unavailable (because it is overloaded or down for maintenance). |
7. Frequently Asked Questions
About UMF
What is UMF International?
UMF International (USA, “UMPIRE”) is a subsidiary of Union Mobile Financial Technology, a Shenzhen-listed company and a pioneer in China’s payments and financial technology market. In 2015, UMF International received its cross-border currency conversion license from China’s State Administration of Foreign Exchange. For more information [http://www.umfintech.com/en/index/].(#http://www.umfintech.com/en/index/)
What are the licenses that UMF have?
UMF has a Payment Business License in China (for nationwide Internet payments, mobile phone payment, and bank card acceptance) from the People’s Bank of China, the business permit for payment and settlement of fund sales of CSRC, the pilot qualification for cross-border foreign exchange payment from the State Administration of Foreign Exchange Beijing Branch and the pilot qualification for Cross-border RMB payment from People’s Bank of China.
- Payment Business License from People’s Bank of China – for Cross Border RMB
- Fund Sales Payment and Settlement License from CSRC
- Pioneer Enterprise Unit of Cross-Border RMB Payment from Beijing Branch of SAFE
- Trans-regional Value-Added Telecommunication Business License from MIIT
- Use of Short Message Access Code Certification from MIIT (Ministry of Industry and Information Technology)
- Telecommunication and Information Service Business License (Beijing ICP Certification) from Beijing Communications Authority
- Payment Card Industry (PCI) Data (PCI DSS)
Policies
Why UMF needs the details of each payment?
Because of the requirement of Chinese State Administration of Foreign Exchange, every transaction needs the detail information to prove it is the real transaction.
The following is the queto of that document:
Article 19.In handling cross-border foreign exchange payment business, a payment institution shall acquire the true transaction information, collect the detailed data of each transaction under the principles of completeness and traceability, and keep them for future reference.
The detailed data under trade in goods shall, in principle, include the name and quantity of the subject matter, transaction currency, amount, parties of transaction and countries they are from, and order time; the detailed data under trade in services shall, in principle, include the type of service, specific transaction information (such as the scheduled flight and time under air ticket, the hotel name and time of accommodation, letter of admission under overseas study, etc.), quantity, transaction currency, amount, parties of transaction and their location, and order time.
The links of the original documents.
Settlement & Fee
What currencies does UMF cover?
UMF support major currencies including but not limited to GBP, HKD, USD, JPY, CAD, AUD, EUR, NZD settlement. WeChat Pay will have settlement with vendors according to the price in local currency. For unsupported currencies, trade can be made through settlement on US dollar.
How is exchange rate determinted?
The spot exchange rate provided by partner settlement banks (China Citic Bank) is used in the UMF Cross-Border Service.
There are two scenarios:
– The price is in local currency, such as USD.
When a buyer purchases a product from a merchant, the buyer will pay it in CNY with the realtime exchange rate. The merchant should get the money in USD. UMF will make exchange twice times each day. UMF will take the gain and lost of exchange.
– The price is in CNY.
When a buyer purchases a product from a merchant, the buyer will pay it in CNY. The merchant will get the money in CNY. UMF will make exchange twice times each day. The merchant will take the gain and lost of exchange.
8. Appendix
Transaction encoding and transaction postscript description
| Trading Codes | Types of trade | Transaction code | Transaction postscript |
|---|---|---|---|
| 01122030 | Goods trade | 122030 | E-Commerce |
| 02223022 | Study Abroad | 223022 | Tuition travel for study abroad and education (above one year) |
| 02223023 | Study Abroad | 223023 | Tuition travel for study abroad and education (one year or less) |
| 03222024 | Air ticket | 222024 | Air ticket for going abroad |
| 03223010 | Air ticket | 223010 | Business trip air ticket |
| 03223021 | Air ticket | 223021 | Air ticket for receiving medical treatment and health examination |
| 03223022 | Air ticket | 223022 | Air ticket for study abroad and education (above one year) |
| 03223023 | Air ticket | 223023 | Air ticket for study abroad and education (one year or less) |
| 03223029 | Air ticket | 223029 | Other private travel air ticket |
| 04223010 | Hotel Booking | 223010 | Hotel for study abroad and education (one year or less) |
| 04223021 | Hotel Booking | 223021 | Other private travel hotel |
| 04223022 | Hotel Booking | 223022 | Business trip hotel |
| 04223023 | Hotel Booking | 223023 | Hotel for receiving medical treatment and health examination |
| 04223029 | Hotel Booking | 223029 | Hotel for study abroad and education (above one year) |
| 05227010 | Phone Bill | 227010 | Mobile telecommunications service |
| 06223010 | Travelling | 223010 | Business trip |
| 06223021 | Travelling | 223021 | Trip for receiving medical treatment and health |
| 06223022 | Travelling | 223022 | Study abroad and education (above one year) |
| 06223023 | Travelling | 223023 | Study abroad and education (one year or less) |
| 06223029 | Travelling | 223029 | Other private travelling |
| 07222012 | Transportation | 222012 | Ocean freight service (import to China) |
| 07222022 | Transportation | 222022 | Air freight service (import to China) |
| 07222032 | Transportation | 222032 | Other Freight service (import to China) |
| 08227020 | Software service | 227020 | Software service |
| 08231030 | Software service | 231030 | License fee for copying or distributing computer software |
| 09228025 | International exhibition | 228025 | Exhibition services |
| 00228024 | Advertising services | 228025 | Advertising services |
Description of return code
| No. | Return code | Description |
|---|---|---|
| 1 | 0000 | Successful |
| 2 | 00060999 | System error |
Description of transaction error code
| No. | Error code | Description |
|---|---|---|
| 1 | 0000 | Payment transaction success. |
| 2 | 00060076 | Unsupported bank card account. |
| 3 | 00060112 | Please input user’s real name again. |
| 4 | 00060114 | Merchant permissions restricted. |
| 5 | 00060305 | Invalid card number. |
| 6 | 00060306 | Card locked, cannot process the payment. |
| 7 | 00060309 | Order amount is greater than maximum allowed for one order. |
| 8 | 00060310 | User has not signed the services terms and conditions. |
| 9 | 00060405 | Payment password was inputted incorrectly for more than three times. |
| 10 | 00060490 | User‘s one day total order amount is greater than maximum allowed for one order. |
| 11 | 00060544 | Payment amount exceeds maximum bank allowed. Please contact your bank. |
| 12 | 00060550 | Payment declined by the bank. |
| 13 | 00060700 | Data validation failure. |
| 14 | 00060702 | Timeout. |
| 15 | 00060710 | Merchant signature validation failure. |
| 16 | 00060711 | Merchant has not registered. |
| 17 | 00060720 | Invalid phone number. |
| 18 | 00060721 | The user chose the online bank he or she does not have. |
| 19 | 00060722 | Please reselect the bank. |
| 20 | 00060723 | Wrong password, please re-enter. |
| 21 | 00060724 | Payment password was incorrect more than three times. |
| 22 | 00060740 | Failed to generate payment order. |
| 23 | 00060750 | Payment failure |
| 24 | 00060751 | Overtime payment has been refunded. |
| 25 | 00060760 | Payment not exists. |
| 26 | 00060761 | Payment processing. Please wait. |
| 27 | 00060762 | Order expired, please order again. |
| 28 | 00060763 | The order has been stopped. |
| 29 | 00060764 | Orders have not been paid, please continue to pay. |
| 30 | 00060765 | Payment failure, please re-select the payment method. |
| 31 | 00060766 | Refund unavailable. |
| 32 | 00060767 | Refund failed. |
| 33 | 00060768 | Refund amount is inconsistent with the payment amount. |
| 34 | 00060774 | Accumulated refund amount larger than the payment amount. |
| 35 | 00060778 | Refund record not found. |
| 36 | 00060780 | Payment success. No need to pay again. |
| 37 | 00060861 | Financial processing. |
| 38 | 00060874 | Refund is not allowed during this time period［23:45~00:25］. |
| 39 | 00060920 | Merchant not support for T+0 refund. |
| 40 | 00060931 | Unidentified refund result. |
| 41 | 00060999 | System error. |
| 42 | 00071024 | Transaction cannot complete. Please contact the card issuing bank. |
| 43 | 00071039 | Transaction not allowed. |
| 44 | 00080530 | User account balance is insufficient. |
| 45 | 00080531 | Transaction failure due to expired bank card or wrong expiry date, please contact the card issuing bank. |
| 46 | 00080534 | Wrong phone number or CVV2. |
| 47 | 00080535 | Card Information and ID mismatch. |
| 48 | 00080537 | Transaction failure. Please contact the card issuing bank. |
| 49 | 00080541 | Payment timeout. |
| 50 | 00080542 | Transaction rejected by bank. |
| 51 | 00080545 | Enter Invalid card password more than the limitation. |
| 52 | 00080557 | Bank return failure |
| 53 | 00080559 | Transaction Failure. Please contact the issuing bank. |
| 54 | 00080711 | Verification code is invalid. |
| 55 | 00080722 | Verification code expired |
| 56 | 00080730 | Transaction is canceled. |
| 57 | 00080732 | Transaction in process, please change a different bank card |
| 58 | 00080748 | Card type not supported, please change a different bank card. |
| 59 | 00081550 | Order amount is greater than maximum allowed. |
| 60 | 00090020 | Card expired or expiration date wrong. |
| 61 | 00090021 | Payment failure. |
| 62 | 00090230 | Transaction unsupported. |
| 63 | 00090239 | There’s an error with this card. |
| 64 | 00090255 | User’s bank does not support this transaction. |
| 65 | 00090361 | Exceed the maximum amount of daily transactions. |
| 66 | 00090362 | There’s an error with this transaction. |
| 67 | 00090388 | Payment failure due to risk. |
| 68 | 00090412 | Transaction record not found. |
| 69 | 00090470 | Exceed the order amount limit per order. |
| 70 | 00090504 | Bank network error. |
| 71 | 00090511 | Transaction rejected. |
| 72 | 00131040 | Transaction failure. Please contact the issuing bank or try later. |
| 73 | 00131072 | Insufficient balance in account, please try again after confirmation. |
| 74 | 00160079 | Phone number and Name mismatch. |
| 75 | 00160080 | Phone number and ID mismatch. |
| 76 | 00180008 | Unidentified payment result, please check later. |
| 77 | 00180018 | Abnormal state of order, please pay again. |
| 78 | 00200005 | SMS verification code not found. |
| 79 | 00200013 | Merchant has not opened this bank channel. |
| 80 | 00200014 | Error. Please try later. |
| 81 | 00200025 | Validation failure. |
| 82 | 00200029 | Abnormal communication in system. |
| 83 | 00200073 | Card validation failure. |
| 84 | 00200075 | Bank card type and payment method mismatch. |
| 85 | 00200076 | Merchant has not opened this service. |
| 86 | 00200077 | Cannot generate order. |
| 87 | 00200078 | Order not found. |
| 88 | 00200079 | Order timeout. |
| 89 | 00200080 | Order closed |
| 90 | 00200081 | This transaction does not exist. |
| 91 | 00200082 | Exceed the limitation of validation code request. |
| 92 | 00200083 | Validation code incorrect. |
| 93 | 00200084 | Exceed the limitation times of incorrect validation code. |
| 94 | 00200085 | Incorrect validation code. |
| 95 | 00200086 | Verification code only can be requested once in a minute. |
| 96 | 00200088 | Exceed the limit times of incorrect validation code. |
| 97 | 00200089 | Mismatch phone number. |
| 98 | 00200090 | Invalid validation code. |
| 99 | 00200091 | Processing. Cannot be canceled. |
| 100 | 00200092 | Cancel amount and payment amount mismatch. |
| 101 | 00200093 | QR code expired. |
| 102 | 00200094 | QR code expired. |
| 103 | 00200096 | Refund is processed and not accept duplicate application. |
| 104 | 00202000 | The exchange rate quire response parameter error. |
| 105 | 00202001 | The foreign currency amount of order must not be blank. |
| 106 | 00202002 | Identity number not found, please check again. |
| 107 | 00202003 | Order amount should be greater than 0. |
| 108 | 00202004 | Incomplete data when ordering the products. |
| 109 | 00202005 | Incorrect bank card number. |
| 110 | 00202006 | Name too long or not in Chinese character. |
| 111 | 00202007 | ID and Card number mismatch. |
| 112 | 00202008 | The cross-border order extension data is absent. |
| 113 | 00202009 | Incorrect Identity number. |
| 114 | 00202010 | The refund amount in the refund application is inconsistent with the original order amount. |
| 115 | 00202011 | The currency in the refund application is inconsistent with the original order currency. |
| 116 | 00202012 | User’s card has not opened online payment. |
| 117 | 00202013 | The customs information has been updated and shall not be updated again. |
| 118 | 00202016 | The cross-border cargo information sheet is absent. |
| 119 | 00202017 | Incorrect payment method. |
| 120 | 00202018 | Absence of necessary payment information. |
| 121 | 00202019 | Duplication of sub-order number in one day. |
| 122 | 00202020 | Duplication of product code in the sub-order in one day |
| 123 | 00202021 | Anomaly on requesting real-name authentication in “GuoZhengTong.” |
| 124 | 00202022 | Duplicate order, information in sub-order and original order not match. |
| 125 | 00202023 | Order amont exceeds the limit requird by Administration of Exchange Control. |
| 126 | 00202024 | Wrong coding on business code. |
| 127 | 00202025 | Business category has not been configured. |
| 128 | 00202026 | Not support refund in prescribed time. |
| 129 | 00210008 | Format incorrect. |
| 130 | 00210028 | Card information mismatch. |
| 131 | 00210037 | Incorrect information or has not opened express online payment. |
| 132 | 00210040 | Bank System Error. |
| 133 | 00210051 | Wrong user name. |
| 134 | 00210059 | Wrong card information. |
| 135 | 00210077 | Exceed bank’s limit of daily transaction amount. |
| 136 | 00230001 | Order date mismatch. |
| 137 | 00230005 | Field is too long. |
| 138 | 00230006 | Order status mismatch. |
| 139 | 00230009 | Transaction status mismatch. |
| 140 | 00230012 | transaction terminated. |
| 141 | 00230017 | Wrong order date. |
| 142 | 00252001 | Transaction failed due to banned account. |
| 143 | 00252002 | Transaction failed due to banned bank card. |
| 144 | 00252003 | Transaction failed due to banned user ID. |
| 145 | 00252004 | Transaction failed due to banned merchant. |
| 146 | 00252006 | Transaction failed due to banned payment product. |
| 147 | 00252007 | Transaction failed due to banned phone number. |
| 148 | 00252008 | Transaction failed due to banned ID number. |
| 149 | 00252009 | Transaction failed due to banned terminal ID. |
| 150 | 00252010 | Transaction failed due to banned IP address. |
| 151 | 00253001 | Exceed the maximum transaction amount within 1 hour. |
| 152 | 00253002 | Exceed the maximum transaction amount within day. |
| 153 | 00253003 | Exceed the maximum transaction amount within 30 days. |
| 154 | 00253010 | User’s phone number exceeded the maximum transaction amount within 1 hour |
| 155 | 00253011 | User’s phone number exceed the maximum transaction amount within day. |
| 156 | 00253012 | User’s phone number exceed the maximum transaction amount within 30 days. |
| 157 | 00253022 | Exceed the maximum transaction amount within 1 hour for this card |
| 158 | 00253024 | Exceed the maximum transaction amount within 30 days for this card |
| 159 | 00253034 | This phone number exceeded the maximum transaction amount per hour. |
| 160 | 00253035 | This phone number exceeded the maximum transaction amount per day. |
| 161 | 00253036 | This phone number exceeded the maximum transaction amount per month. |
| 162 | 00253044 | Your order exceeds the merchant’s per transaction limit |
| 163 | 00253048 | Order amount is greater than maximum allowed for the first order. |
| 164 | 00253049 | New user’s phone number exceeded the maximum transaction amount per hour. |
| 165 | 00253052 | New user’s phone number exceeded the maximum amount per transaction. |
| 166 | 00254001 | This phone number exceeded the maximum transaction times per hour. |
| 167 | 00254002 | This phone number exceeded the maximum transaction times per day. |
| 168 | 00254003 | This phone number exceeded the maximum transaction times per month. |
| 169 | 00254014 | Exceed the maximum transaction times within day. |
| 170 | 00254015 | Exceed the maximum transaction times within 30 days. |
| 171 | 00254022 | This card exceeds the maximum transaction times per hour. |
| 172 | 00254023 | This card exceeds the maximum transaction times per day. |
| 173 | 00254024 | This card exceeds the maximum transaction times per 30 days. |
| 174 | 00254028 | Exceed the maximum transaction times within 1 hour . |
| 175 | 00254029 | Exceed the maximum transaction times within 1 day. |
| 176 | 00254037 | New user exceeded the maximum transaction times per hour. |
| 177 | 00254038 | New user exceeded the maximum transaction times per day. |
| 178 | 00255003 | Insufficient balance in account happened too many times. Payment refused due to risk. |
| 179 | 00280036 | The merchant has not given permission to use this currency. |
| 180 | 00280037 | Data validation failure. |
| 181 | 00280038 | The merchant has not given permission for customs declaration. |
| 182 | 00280039 | The merchant doesn’t support payment for goods trade. |
| 183 | 00280040 | The field “mer_cust_id” and “usr_busi_agreement_id” at least one is required. |
| 184 | 00280041 | The value of the field “pay_type” is out of the range. |
| 185 | 00280042 | The field “user business agreement number” and “merchant-user identification” don’t match. |
| 186 | 00280043 | The order has been declared to the customs. |
| 187 | 00280044 | The order’s information is wrong. |
| 188 | 00280045 | The order has not been sent. |
| 189 | 00280046 | The order has been sent to be treated. |
| 190 | 00280047 | The order failed to declaration custom. |
| 191 | 00280048 | Only goods suborder type support CIQ applying. |
| 192 | 00280049 | The order has been sent to and processing by CIQ. |
| 193 | 00280050 | The order has applied for CIQ successfully, no need for another application. |
| 194 | 00280051 | The inspection date is 30 days after the date of order. |
| 195 | 00280052 | The customCode must fail, check does not pass. |
| 196 | 00280053 | The merchant is not configured. |
| 197 | 00280054 | The merchant did not open any bank passages. |
| 198 | 00280055 | The dealer configures the channel and does not support the currency. |
| 199 | 00280056 | The merchant did not configure the independent customs declaration fee. |
| 200 | 00280057 | The merchant did not open an independent declaration. |
| 201 | 00280058 | The data is exist. |
| 202 | 00280059 | The file is not exist. |
| 203 | 00280064 | The submitted customs data doesn’t exist and is not allowed to be submitted to CIQ. |
| 204 | 00280065 | Order amount > set amount ( not need to send SMS) |
| 205 | 00280066 | Bank unsigned. |
| 206 | 00281017 | Merchant has not open this currency channel. |
| 207 | 00282014 | Merchnat has not declare with customs, require to updating the customs information. |
| 208 | 00282015 | The sub-order absent. |
| 209 | 00282016 | No corresponding goods information. |
| 210 | 00283087 | Merchant configuration query. Merchants is invalid. |
| 211 | 00284003 | Field validation of real-name authentication failed. |
| 212 | 00290502 | Identification record mismatch. |
| 213 | 00290508 | Validation information mismatch. |
| 214 | 00290511 | Bank card and full name mismatch. |
| 215 | 00290512 | Phone mismatch. |
| 216 | 00290521 | Unsupported ID type. |
| 217 | 00280702 | Input data doesn’t meet regular expressions. |
| 218 | 00284000 | Authentication request exception. |
| 219 | 00284001 | Authentication failed. |
| 220 | 00284002 | Authentication request timeout. |
| 221 | 00060406 | failed to query media corresponding users. |
| 222 | 00060124 | The payment protocol relationship that the business protocol depends on does not exist. |
| 223 | 00160108 | This bankcard has been signed. |
| 224 | 00060072 | Agreement does not exist. |
| 225 | 00210011 | Mobile phone verification failed. |
| 226 | 00280701 | Data valid_date must fail, check does not pass. |
| 227 | 00280703 | Data Token is expired checksum does not pass. |
| 228 | 00202012 | “User’s card has not opened online payment. |
| 229 | 00160107 | The information of your bank card is wrong. |
| 230 | 00290010 | ID is null or format error. |
| 231 | 00281019 | Merchant has not open. |
Transaction status description
| No. | Enumeration name | Description | Note |
|---|---|---|---|
| 1 | WAIT_BUYER_PAY | Was accepted, waiting for the buyer to pay. | |
| 2 | TRADE_SUCCESS | The transaction was successful. | |
| 3 | TRADE_CLOSED | Transaction was closed since transaction expired. | |
| 4 | TRADE_FAIL | Failed. |
Refund status description
| No. | Enumeration name | Description | Note |
|---|---|---|---|
| 1 | REFUND_SUCCESS | Refund successful. | |
| 2 | REFUND_CLOSE | Refund is closed. | |
| 3 | REFUND_PROCESS | Refund in process. | |
| 4 | REFUND_FAIL | Refund failed. |
Currency codes
| No | Currency code | Currency description |
|---|---|---|
| 1 | CNY | Chinese yuan |
| 2 | HKD | Hong Kong dollar |
| 3 | USD | United States dollar |
| 4 | EUR | EURO |
| 5 | JPY | Japanese Yen |
| 6 | GBP | Pound |
| 7 | AUD | Australian dollar |
| 8 | CAD | Canadian dollar |
| 9 | NZD | New Zealand dollar |
| 10 | SGD | Singapore dollar |
| 11 | MOP | Macau Pataca |
| 12 | CHF | Swiss Franc |
| 13 | SEK | Swedish Krona |
| 14 | DKK | Danish Kroner |
| 15 | NOK | Norwegian Krona |
| 16 | MOP | Norwegian Krona |
Banks supported by credit card payment
| No. | Bank code | Bank |
|---|---|---|
| 1 | ICBC | Industrial and Commercial Bank of China |
| 2 | CCB | China Construction Bank |
| 3 | ABC | Agricultural Bank of China |
| 4 | BOC | Bank of China |
| 5 | PSBC | Postal Savings Bank of China |
| 6 | COMM | Bank of Communications |
| 7 | CITIC | China Citic Bank |
| 8 | CEB | China Everbright Bank |
| 9 | HXB | Hua Xia Bank |
| 10 | CMBC | China Minsheng Bank |
| 11 | CMB | China Merchants Bank |
| 12 | SHB | Bank of Shanghai |
| 13 | BJB | Bank of Beijing |
| 14 | BEA | Bank of East Asia |
| 15 | CIB | China Industrial Bank |
| 16 | NBB | Bank of Ningbo |
| 17 | SPDB | Shanghai Pudong Development Bank |
| 18 | GDB | Guangdong Development Bank |
| 19 | SPAB | Ping An Bank |
| 20 | BSB | Baoshang Bank |
| 21 | CSCB | Bank of Changsha |
| 22 | CDB | Bank of Chengde |
| 23 | CDRCB | Chengdu Rural Commercial Bank |
| 24 | CRCB | Chongqing Rural Commercial Bank |
| 25 | CQB | Bank of Chongqing |
| 26 | DLB | Bank of Dalian |
| 27 | DYCCB | Dongying Commercial Bank |
| 28 | ORBANK | Erdos Bank |
| 29 | FJNXB | Rural Credit Cooperative of Fujian |
| 30 | GYB | Bank of Guiyang |
| 31 | GCB | Bank of Guangzhou |
| 32 | GRCB | Guangzhou Rural Commercial Bank |
| 33 | HEBB | Harbin Bank |
| 34 | HNNXB | Rural Credit Cooperative of Hunan |
| 35 | HSB | Huishang Bank |
| 36 | BHB | Bank of Hebei |
| 37 | HZCB | Bank of Hangzhou |
| 38 | BOJZ | Bank of Jinzhou |
| 39 | CSRCB | Jiangsu Changshu Rural Commercial Bank |
| 40 | JSB | Bank of Jiangsu |
| 41 | JRCB | Jiangyin Rural Commercial Bank |
| 42 | JJCCB | Bank of Jiujiang |
| 43 | LZB | Bank of Lanzhou |
| 44 | DAQINGB | Bank of Longjiang |
| 45 | QHB | Bank of Qinghai |
| 46 | SHRCB | Shanghai Rural Commercial Bank |
| 47 | SRB | Bank of Shangrao |
| 48 | SDEB | Shunde Rural Commercial Bank |
| 49 | TZCB | Bank of Taizhou |
| 50 | WHSHB | Weihai City Commercial Bank |
| 51 | WFCCB | Bank of Weifang |
| 52 | WZCB | Bank of Wenzhou |
| 53 | URMQCCB | Urumqi City Commercial Bank |
| 54 | WRCB | Wuxi Rural Commercial Bank |
| 55 | YCCB | Yichang City Commercial Banks |
| 56 | YZB | Bank of Yinzhou |
| 57 | CZCB | Zhejiang Chouzhou Commercial Bank |
| 58 | ZJTLCB | Zhejiang Tailong Commercial Bank |
| 59 | MTBANK | Zhejiang Mintai Commercial Bank |
| 60 | NJCB | Bank of Nanjing |
| 61 | NCB | Bank of Nanchang |
| 62 | QLBANK | Qilu Bank |
| 63 | YDRCB | Yaodu Rural Commercial Bank |
| 64 | WJRCB | Wujiang Rural Commercial Bank |
| 65 | CZSB | CHINA ZHESHANG BANK CO., LTD. |
Banks supported by debit card payment
| NO. | Bank code | Bank |
|---|---|---|
| 1 | SPDB | Shanghai Pudong Development Bank |
| 2 | CCB | China Construction Bank |
| 3 | ABC | Agricultural Bank of China |
| 4 | BOC | Bank of China |
| 5 | CITIC | China Citic Bank |
| 6 | CEB | China Everbright Bank |
| 7 | CMB | China Merchants Bank |
| 8 | ICBC | Industrial and Commercial Bank of China |
| 9 | CMBC | China Minsheng Bank |
| 10 | GDB | Guangdong Development Bank |
| 11 | COMM | Bank of Communications |
| 12 | SPAB | Ping An Bank |
| 13 | CIB | China Industrial Bank |
| 14 | SHB | Bank of Shanghai |
| 15 | CZSB | CHINA ZHESHANG BANK CO., LTD. |
Supported Customs
| NO. | Custom code | Custom |
|---|---|---|
| 1 | CQZS | Chongqing General Administration |
| 2 | GZHG | Guangzhou Customs |
| 3 | BJZS | Beijing Customs |
| 4 | NB | Ningbo Customs |
| 5 | ZZZS | Zhengzhou Customs |
| 6 | QDZS | Qingdao Customs |
| 7 | SZHG | Shenzhen Customs |
| 8 | HZHG | Hangzhou Customs |
| 9 | SHHG | Shanghai Customs |
| 10 | FZHG | FuZhou Customs |
| 11 | PTHG | PingTan Customs |
| 12 | FSHG | Foshan Customs |
| 12 | WHHG | WuHan Customs |
Supported CIQ
| NO. | CIQ code | CIQ Name |
|---|---|---|
| 1 | GJHP | GuangZhouHuangPu CIQ |
| 2 | GJNS | GuangZhouZanZha CIQ |
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 | The receiver failed to receive the message |
| 3 | 00280071 | The recipient information already exists |
| 4 | 00280073 | Input order details failed |
| 5 | 00280074 | The order details already exist |
| 6 | 00280076 | Please be patient while the payment is being processed |
| 7 | 00280077 | Payment failed – the order details corresponding to this batch could not be found. Please input the order details first before payment |
| 8 | 00280078 | Payment failed – the payee information corresponding to this batch cannot be found. Please send the payee data first before payment |
| 9 | 00280079 | Payment failed – the payment amount for this batch is not consistent with the accumulated amount of the corresponding order details |
| 10 | 00280080 | Payment failed – payment failed and the balance is insufficient. Please confirm that the amount of U payment account is sufficient |
| 11 | 00280081 | Payment failed – the bank verification data failed, please contact the operation personnel to check the payment information |
| 12 | 00280083 | Exchange rate inquiry failed |
| 13 | 00280084 | Recipient information does not exist |
| 14 | 00280085 | Corresponding payment order was not found |
| 15 | 00280086 | The order payment is in progress |
| 16 | 00280087 | The result of recipient information query is not unique |
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 Payment
Payment sequence diagram.
sequenceDiagram
participant Merchant
participant UMF
Merchant-->>UMF: 1.send_enterprise_qualification
UMF-->>Merchant: 2.Return the processing result
Merchant-->>UMF: 3.query_enterprise_id
UMF-->>Merchant: 4.Return query_enterprise_id object
Merchant-->>UMF: 5.send_payee_infor
UMF-->>Merchant: 6.Return the processing result
Merchant-->>UMF: 7.send_b2bouter_order_detail
UMF-->>Merchant: 8.Return the processing result
Merchant-->>UMF: 9.send_b2b_order
UMF-->>Merchant: 10.Return the processing result
Merchant-->>UMF: 11.query_order
UMF-->>Merchant: 12.Return query_order object
11.1 Enterprise qualification submission
## 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"
}
}
Request
POST: /send_enterprise_qualification
Merchants should register users with UMF, and the reporting status of the enterprise is “0” when it is created. After that, the merchant should submit the required documents to UMF offline, and UMF will submit the documents to the bank where the enterprise opened an account. If the verification is successful, the status will be changed to “1”.
Parameter
| Parameter | Description |
|---|---|
| send_enterprise_qualification | Object, enterprise qualification reporting information. |
Response
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
11.2 Enterprise qualification query
## 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"
}
}
Request
POST: /query_enterprise_id
To query the results of the enterprise qualification submission, it must be executed first (enterprise qualification submission)
Parameter
| Parameter | Description |
|---|---|
| query_enterprise | Object, enterprise qualification report result information. |
Response
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
| query_enterprise_id | Object, the file path of the response. |
11.3 Payee information submission
## 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"
}
}
Request
POST: /send_payee_infor
Payee information submission
Parameter
| Parameter | Description |
|---|---|
| payee_infor | Object, transaction details. |
Response
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
11.4 B2B cross-border foreign currency details are sent
## 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"
}
}
Request
POST: /send_b2bouter_order_detail
B2B cross-border foreign currency details are sent
Parameter
| Parameter | Description |
|---|---|
| b2bouter_order | Object, transaction details. |
Response
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
11.5 Confirm payment receipt information
## 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"
}
]
}
Request
POST: /send_b2b_order
Confirm payment receipt information
Parameter
| Parameter | Description |
|---|---|
| payment_sub | Object, transaction details. |
Response
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
| links | object array. The links of next steps. |
11.6 Payment slip transaction query
## 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"
}
}
Request
GET: /{payment_id}/query_order
Payment slip transaction query
Response
| Parameter | Description |
|---|---|
| meta | object. The common information of response. |
| query_order | object，query_order. |