Nomad payment provider aggregation, including make payments, and customs declaration for orders and etc.
This is the documentation for version 1.6.6
of the API. Last update on Apr 7, 2022.
https://nomad.samarkand-global.cn/broker/v1Merchant queries customs clearance information by order number
Merchant name to payment company, e.g. wechat.prod
Customs code, available options: GUANGZHOU_ZS, HANGZHOU_ZS, NINGBO, ZHENGZHOU_BS, CHONGQING, SHANGHAI_ZS, SHENZHEN, ZHENGZHOU_ZH_ZS
Values are GUANGZHOU_ZS, HANGZHOU_ZS, NINGBO, ZHENGZHOU_BS, CHONGQING, SHANGHAI_ZS, SHENZHEN, ZHENGZHOU_ZH_ZS, or TIANJIN. Default value is GUANGZHOU_ZS.
The internal order number of the merchant system
Payment system internal order number
The internal sub-order number of the merchant system
The internal sub-order number of the payment company system
Must be wechatpay or alipay
Values are wechatpay or alipay.
Get a payment declaration result to customs successfully.
Response message
Original customs return message from payment company
The third party response code
Transaction ID returned by payment company
Contents of payment order
Status code, UNDECLARED: not declared (If the order has been sent to the customs, the merchant resubmits and the customs still has the modification interface); PROCESSING: reporting; SUCCESS: Declaration is successful; FAIL: failed to declare; EXCEPT: The customs interface is abnormal
The internal order number of the merchant system
Transaction ID returned by payment company
The merchant’s record number registered in the customs
The declaration result indicates that if the status is failed or abnormal, the failure reason is displayed
Customs code
The last update time, time zone is GMT+8 beijing
Tariff, divided into units
The currency used for payment of payment company orders is currently only supported in RMB CNY. If there is an order split, it must be sent.
Default value is CNY.
The amount of the sub-order, in cents, cannot exceed the amount of the original order, order_fee=transport_fee+product_fee (amount payable = logistics fee + product price), if there is a split order, it must be passed.
The logistics cost is divided into units, and must be passed if there is a split order.
Commodity costs, in units of cents, must be passed if there is a split order.
Only mainland ID cards are supported temporarily.
Default value is IDCARD.
UNCHECKED: did not check the identity information of the order; SAME: consistent with the identity information of the payer; DIFFERENT: inconsistent with the identity information of the payer
The verification agencies
Transaction serial number, from the verification agency, such as the transaction serial number recorded by UnionPay, for merchants to report to the customs
Request validation failure
Not Authenticated.
Something wrong when declaring the payment.
curl \
-X GET https://nomad.samarkand-global.cn/broker/v1/customs/payment/wechat.prod?customs=GUANGZHOU_ZS&app-api-key=api_token_value{
"code": 200,
"message": "success",
"customsMessage": "<xml><return_code><![CDATA[SUCCESS]]></return_code>...</xml>",
"resultCode": "success",
"transactionId": "1000320306201511078440737890",
"orders": [
{
"state": "UNDECLARED",
"subOrderNo": "1000320306201511078440737890",
"subOrderId": "4200001306202110500000000000.0",
"mchCustomsNo": "31123452K0",
"explanation": "string",
"customs": "string",
"modifyTime": "20091227091010",
"duty": 88,
"feeType": "CNY",
"orderFee": 88,
"transportFee": 88,
"productFee": 88,
"certType": "IDCARD",
"certCheckResult": "UNCHECKED",
"verifyDepartment": "OTHERS",
"verifyDepartmentTradeId": "OTHERS"
}
]
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Merchant name to payment company, e.g. wechat.prod
Customs codes
Values are GUANGZHOU_ZS, HANGZHOU_ZS, NINGBO, ZHENGZHOU_BS, CHONGQING, SHANGHAI_ZS, SHENZHEN, ZHENGZHOU_ZH_ZS, or TIANJIN. Default value is GUANGZHOU_ZS.
The merchant’s record number registered in the customs
The internal order number of the merchant system, only numbers, uppercase and lowercase letters, and it is unique under the same merchant number.
Transaction ID returned by payment company
Merchant's sub-order number, must be passed if there is a split order
Do not fill in the sub-order number. Order number returned by payment company
Payment method, must be wechatpay or alipay
Values are wechatpay or alipay.
Payment response.
Response message
Original customs return message from payment company
The third party response code
Status code, UNDECLARED: not declared (If the order has been sent to the customs, the merchant resubmits and the customs still has the modification interface); PROCESSING: reporting; SUCCESS: Declaration is successful; FAIL: failed to declare; EXCEPT: The customs interface is abnormal
Transaction ID returned by payment company
The internal order number of the merchant system
The internal order number of the merchant system
The last update time, time zone is GMT+8 beijing
UNCHECKED: did not check the identity information of the order; SAME: consistent with the identity information of the payer; DIFFERENT: inconsistent with the identity information of the payer
The verification agencies
Transaction serial number, from the verification agency, such as the transaction serial number recorded by UnionPay, for merchants to report to the customs
Request validation failure
Not Authenticated.
Something wrong when redeclare the payment.
curl \
-X PUT https://nomad.samarkand-global.cn/broker/v1/customs/payment/wechat.prod?app-api-key=api_token_value \
-H "Content-Type: application/json" \
-d '{"customs":"GUANGZHOU_ZS","mchCustomsNo":"31123452K0","orderNo":"test2021101901","transactionId":"4200001306202110500000000000.0","subOrderNo":"1000320306201511078440737890","subOrderId":"4200001306202110500000000000.0","paymentMethod":"wechatpay"}'{
"customs": "GUANGZHOU_ZS",
"mchCustomsNo": "31123452K0",
"orderNo": "test2021101901",
"transactionId": "4200001306202110500000000000.0",
"subOrderNo": "1000320306201511078440737890",
"subOrderId": "4200001306202110500000000000.0",
"paymentMethod": "wechatpay"
}{
"code": 200,
"message": "success",
"customsMessage": "<xml><return_code><![CDATA[SUCCESS]]></return_code>...</xml>",
"resultCode": "success",
"state": "UNDECLARED",
"transactionId": "1000320306201511078440737890",
"orderNo": "1000320306201511078440737890",
"subOrderNo": "1000320306201511078440737890",
"modifyTime": "20091227091010",
"certCheckResult": "UNCHECKED",
"verifyDepartment": "OTHERS",
"verifyDepartmentTradeId": "OTHERS"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Merchant name to payment company, e.g. wechat.prod
The internal order number of the merchant system, only numbers, uppercase and lowercase letters, and it is unique under the same merchant number.
Transaction ID returned by Payment company
Customs codes
Values are GUANGZHOU_ZS, HANGZHOU_ZS, NINGBO, ZHENGZHOU_BS, CHONGQING, SHANGHAI_ZS, SHENZHEN, ZHENGZHOU_ZH_ZS, or TIANJIN. Default value is GUANGZHOU_ZS.
Payment method, must be wechatpay or alipay
Values are wechatpay or alipay.
The merchant’s record number registered in the customs
Only mainland ID cards are supported temporarily.
Default value is IDCARD.
The user's mainland ID number, the ID number ending in the letter X, please capitalize the letter X.
User name.
Tariff, divided into units
ADD New customs declaration application, MODIFY modification. Default is ADD
Values are ADD or MODIFY. Default value is ADD.
Merchant's sub-order number, must be passed if there is a split order
The currency used for payment of Payment company orders is currently only supported in RMB CNY. If there is an order split, it must be sent.
Default value is CNY.
The amount of the sub-order, in cents, cannot exceed the amount of the original order, order_fee=transport_fee+product_fee (amount payable = logistics fee + product price), if there is a split order, it must be passed.
The logistics cost is divided into units, and must be passed if there is a split order.
Commodity costs, in units of cents, must be passed if there is a split order.
Declare payment to customs successfully.
Response message
Original customs return message from payment company
The third party response code
Status code, UNDECLARED: not declared (If the order has been sent to the customs, the merchant resubmits and the customs still has the modification interface); PROCESSING: reporting; SUCCESS: Declaration is successful; FAIL: failed to declare; EXCEPT: The customs interface is abnormal
Transaction ID returned by payment company
The internal order number of the merchant system
The internal order number of the merchant system
The last update time, time zone is GMT+8 beijing
UNCHECKED: did not check the identity information of the order; SAME: consistent with the identity information of the payer; DIFFERENT: inconsistent with the identity information of the payer
The verification agencies
Transaction serial number, from the verification agency, such as the transaction serial number recorded by UnionPay, for merchants to report to the customs
Request validation failure
Not Authenticated.
Something wrong when declaring the payment.
curl \
-X POST https://nomad.samarkand-global.cn/broker/v1/customs/payment/wechat.prod?app-api-key=api_token_value \
-H "Content-Type: application/json" \
-d '{"orderNo":"test2021101901","transactionId":"4200001306202110500000000000.0","customs":"GUANGZHOU_ZS","paymentMethod":"wechatpay","mchCustomsNo":"31123452K0","certType":"IDCARD","certId":330821198809085200,"name":"Zhangsan","duty":88,"actionType":"ADD","subOrderNo":20150806125346,"feeType":"CNY","orderFee":88,"transportFee":88,"productFee":88}'{
"orderNo": "test2021101901",
"transactionId": "4200001306202110500000000000.0",
"customs": "GUANGZHOU_ZS",
"paymentMethod": "wechatpay",
"mchCustomsNo": "31123452K0",
"certType": "IDCARD",
"certId": 330821198809085200,
"name": "Zhangsan",
"duty": 88,
"actionType": "ADD",
"subOrderNo": 20150806125346,
"feeType": "CNY",
"orderFee": 88,
"transportFee": 88,
"productFee": 88
}{
"code": 200,
"message": "success",
"customsMessage": "<xml><return_code><![CDATA[SUCCESS]]></return_code>...</xml>",
"resultCode": "success",
"state": "UNDECLARED",
"transactionId": "1000320306201511078440737890",
"orderNo": "1000320306201511078440737890",
"subOrderNo": "1000320306201511078440737890",
"modifyTime": "20091227091010",
"certCheckResult": "UNCHECKED",
"verifyDepartment": "OTHERS",
"verifyDepartmentTradeId": "OTHERS"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Upload the payer identity information which will be re-verified by payment provider, supported payment method: wechatpay
Merchant name to payment company, e.g. wechat.prod
The internal order number of the merchant system, only numbers, uppercase and lowercase letters, and it is unique under the same merchant number.
Transaction ID returned by Payment company
Merchant's sub-order number, must be passed if there is a split order
Customs codes
Values are GUANGZHOU_ZS, HANGZHOU_ZS, NINGBO, ZHENGZHOU_BS, CHONGQING, SHANGHAI_ZS, SHENZHEN, ZHENGZHOU_ZH_ZS, or TIANJIN. Default value is GUANGZHOU_ZS.
Payment method, must be wechatpay or alipay
Values are wechatpay or alipay.
The merchant’s record number registered in the customs
Only mainland ID cards are supported temporarily.
Default value is IDCARD.
The user's mainland ID number, the ID number ending in the letter X, please capitalize the letter X.
Payer name.
Declare payment to customs successfully.
Response message
The internal order number of the merchant system.
Transaction ID returned by Payment company
Merchant's sub-order number, must be passed if there is a split order
Customs code
The merchant’s record number registered in the customs
Only mainland ID cards are supported temporarily.
Default value is IDCARD.
The user's mainland ID number, the ID number ending in the letter X, please capitalize the letter X.
Payer name.
Request validation failure
Not Authenticated.
Something wrong when declaring the payment.
curl \
-X POST https://nomad.samarkand-global.cn/broker/v1/customs/identification/wechat.prod?app-api-key=api_token_value \
-H "Content-Type: application/json" \
-d '{"orderNo":"test2021101901","transactionId":"4200001306202110500000000000.0","subOrderNo":20150806125346,"customs":"GUANGZHOU_ZS","paymentMethod":"wechatpay","mchCustomsNo":"31123452K0","certType":"IDCARD","certId":330821198809085200,"certName":"Zhangsan"}'{
"orderNo": "test2021101901",
"transactionId": "4200001306202110500000000000.0",
"subOrderNo": 20150806125346,
"customs": "GUANGZHOU_ZS",
"paymentMethod": "wechatpay",
"mchCustomsNo": "31123452K0",
"certType": "IDCARD",
"certId": 330821198809085200,
"certName": "Zhangsan"
}{
"code": 200,
"message": "success",
"orderNo": "test2021101901",
"transactionId": "4200001306202110500000000000.0",
"subOrderNo": 20150806125346,
"customs": "string",
"mchCustomsNo": "31123452K0",
"certType": "IDCARD",
"certId": 330821198809085200,
"certName": "Zhangsan"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Merchant name to payment company, e.g. weixinpay.test
Merchant order no.
Must be wechatpay or alipay
Values are wechatpay or alipay.
Query a payment successfully.
Response message
Merchant system order number
Paymer amount currency
Amount currency
Payer total amount, unit is fen
Order actual amount, which uses the base unit of current currency
Total amount, unit is fen
Bank type
Payment time
Transaction ID
Trade state
Trade state description
Trade type
Not Authenticated.
Something wrong when making the payment.
curl \
-X GET https://nomad.samarkand-global.cn/broker/v1/payment/wechat.test?order_ref=test202101&app-api-key=api_token_value{
"code": 200,
"message": "success",
"orderRef": "test202103",
"payerCurrency": "CNY",
"currency": "CNY",
"payerTotal": 10,
"actualAmount": 2200,
"total": 10,
"bankType": "string",
"Timing": "2021-11-02T17:03:38+08:00",
"transactionId": "4200001148202111020556019250",
"tradeState": "SUCCESS",
"tradeStateDesc": "支付成功",
"tradeType": "MWEB"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Merchant name to payment company, e.g. weixinpay.test
Payment method, must be wechatpay or alipay
Values are wechatpay or alipay.
Payment companies have different payment types
Values are NATIVE, H5, JSAPI, MINIPRO, or APP.
Merchant system order number
Order actual amount, which uses the base unit of current currency
Order total amount, which uses the base unit of current currency
Subsidy amount, only works when profitSharing is True
When the original order price is not equal to the payment amount, the discount will not be enjoyed. This field is mainly used to prevent the same invoice from being paid multiple times to enjoy multiple discounts.
Merchant invoice ID, need to use with products data
Must be CNY or GBP
Whether the order is going to share profit
Default value is true.
All products data for current order, used when the order includes discounts
Goods name.
The merchant's own classification， for example, with/interval.
Goods unit price, unit is cent
Goods quantity
Product ID in merchant side
Product ID in payment company side
Order product description
Payment attach data, which could be used by payment notifies
Payment due time
Coupon goods tag
Payer ID of customer in service provider side.
Payer ID of customer in merchant side.
Notify url, that is used by payment company.
Success url, that is used by alipay company.
Cancel url, that is used by alipay company.
Create a payment successfully.
Response message
Payment message responsed from payment company
Payment invoked message responsed from payment company
Timestamp, used to sign
Random string up to 32 characters, used to sign
Not Authenticated.
Request validation failure
Something wrong when making the payment.
curl \
-X POST https://nomad.samarkand-global.cn/broker/v1/payment/wechat.test?app-api-key=api_token_value \
-H "Content-Type: application/json" \
-H "X-Real-Ip: string" \
-H "Client-Id: string" \
-d '{"paymentMethod":"wechatpay","paymentType":"H5","orderRef":"O123456789","actualAmount":2200,"total":2200,"subsidyAmount":0,"costPrice":0,"invoiceId":"string","currency":"CNY","profitSharing":true,"products":[{"goodsName":"Orange","goodsCategory":"health-beauty/fragrance","goodsUnitPrice":12,"goodsQuantity":1,"merchantProductId":"barcode123456","paymentProductId":1246464644}],"description":"面膜 mask","attach":"Payment attach mark","timeExpire":"2022-02-24T14:02:38Z","goodsTag":"new","payerId":"osGEYs0HfdUF4R965HMmEPKqOSWw","merchantPayerId":"osGEYs0HfdUF4R965HMmEPKqOSWw","notifyUrl":"https://www.weixin.qq.com/wxpay/pay.php","successUrl":"https://www.weixin.qq.com/wxpay/pay.php","cancelUrl":"https://www.weixin.qq.com/wxpay/pay.php"}'# Headers
X-Real-Ip: string
Client-Id: string
# Payload
{
"paymentMethod": "wechatpay",
"paymentType": "H5",
"orderRef": "O123456789",
"actualAmount": 2200,
"total": 2200,
"subsidyAmount": 0,
"costPrice": 0,
"invoiceId": "string",
"currency": "CNY",
"profitSharing": true,
"products": [
{
"goodsName": "Orange",
"goodsCategory": "health-beauty/fragrance",
"goodsUnitPrice": 12,
"goodsQuantity": 1,
"merchantProductId": "barcode123456",
"paymentProductId": 1246464644
}
],
"description": "面膜 mask",
"attach": "Payment attach mark",
"timeExpire": "2022-02-24T14:02:38Z",
"goodsTag": "new",
"payerId": "osGEYs0HfdUF4R965HMmEPKqOSWw",
"merchantPayerId": "osGEYs0HfdUF4R965HMmEPKqOSWw",
"notifyUrl": "https://www.weixin.qq.com/wxpay/pay.php",
"successUrl": "https://www.weixin.qq.com/wxpay/pay.php",
"cancelUrl": "https://www.weixin.qq.com/wxpay/pay.php"
}{
"code": 200,
"message": "success",
"payMessage": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx031",
"payInvokeMessage": "weixin://wap/pay?prepayid%3Dwx03143347..",
"timeStamp": 1414561699,
"nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Must be wechatpay or alipay
Values are wechatpay or alipay.
curl \
-X POST https://nomad.samarkand-global.cn/broker/v1/payment/close/wechat.test/orderno2022030300011?app-api-key=api_token_value{
"code": 200,
"message": "success",
"paymentMessage": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Merchant name to payment company, e.g. weixinpay.test
Payment method, must be wechatpay or alipay
Values are wechatpay or alipay.
Payment companies have different payment types
Values are NATIVE, H5, JSAPI, MINIPRO, or APP.
Pay message responsed from payment company
This url is notified when the payment succeeds
A random string of up to 32 characters
Invoke a payment order successfully.
Response message
Payment message responsed from payment company
Payment invoked message responsed from payment company
Timestamp, used to sign
Random string up to 32 characters, used to sign
Not Authenticated.
Request validation failure
Something wrong when making the payment.
curl \
-X POST https://nomad.samarkand-global.cn/broker/v1/payment/invocation/wechat.test?app-api-key=api_token_value \
-H "Content-Type: application/json" \
-d '{"paymentMethod":"wechatpay","paymentType":"H5","payMessage":"https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx2711083","timeStamp":1414561699,"nonceStr":"5K8264ILTKCH16CQ2502SI8ZNMTM67VS"}'{
"paymentMethod": "wechatpay",
"paymentType": "H5",
"payMessage": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx2711083",
"timeStamp": 1414561699,
"nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS"
}{
"code": 200,
"message": "success",
"payMessage": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx031",
"payInvokeMessage": "weixin://wap/pay?prepayid%3Dwx03143347..",
"timeStamp": 1414561699,
"nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Merchant name to payment company, e.g. weixinpay.test
Must be wechatpay or alipay
Values are wechatpay or alipay.
Merchant order no.
Payment order transaction ID.
Payment info in Nomad management system.
Response message
An array of data related to broker
Transaction ID reponsed from payment company
Transaction state of the payment company
Payer transaction amount
Transaction currency
Transaction total amount
Transaction currency
Merchant system order number
Payer open id in payment company side
Success time of transaction
Bank type of transaction
Error info of transaction operation
Not Authenticated.
Something wrong when making the payment.
curl \
-X GET https://nomad.samarkand-global.cn/broker/v1/payms/wechat.test?app-api-key=api_token_value{
"code": 200,
"message": "success",
"data": [
{
"transactionId": "4200001347202202070541113364",
"transactionState": "SUCCESS",
"amount": {
"payerTotal": 42,
"payerCurrency": "string",
"total": 42,
"currency": "string"
},
"orderRef": "test20220207013",
"payerOpenId": "osGEYs0HfdUF4R965HMmEPKqOSWw",
"successTime": "2022-02-07T16:50:57+08:00",
"bankType": "2022-02-07T16:50:57+08:00",
"error": "Failed to decrypt VDpnk: Incorrect padding"
}
]
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Merchant name to payment company, e.g. wechat.prod
Payment method, must be wechatpay or alipay
Values are wechatpay or alipay.
Nomad system operations, DECRYPT_NOTIFICATION: decrypt payment company notification
Payment company notification items, used when operation is DECRYPT_NOTIFICATION
Not more than 100 elements.
Payment company notification cipher text
Payment company notification nounce
Payment company associated data
Payout funds transactions operation execute successfully.
Response message
An array of data related to broker
Transaction ID reponsed from payment company
Transaction state of the payment company
Payer transaction amount
Transaction currency
Transaction total amount
Transaction currency
Merchant system order number
Payer open id in payment company side
Success time of transaction
Bank type of transaction
Error info of transaction operation
Request validation failure
Not Authenticated.
Something wrong when download the payout bill.
curl \
-X POST https://nomad.samarkand-global.cn/broker/v1/payms/{merchant}?app-api-key=api_token_value \
-H "Content-Type: application/json" \
-d '{"paymentMethod":"wechatpay","operation":"DECRYPT_NOTIFICATION","notifyItems":[{"cipherText":"VDpnk1kbgBRJKJFlQKYO2mDWRDxmVvBgCgUjoBnOusp6Et8wcx...","nonce":"cdcO3WeDbRgR","associatedData":"transaction"}]}'{
"paymentMethod": "wechatpay",
"operation": "DECRYPT_NOTIFICATION",
"notifyItems": [
{
"cipherText": "VDpnk1kbgBRJKJFlQKYO2mDWRDxmVvBgCgUjoBnOusp6Et8wcx...",
"nonce": "cdcO3WeDbRgR",
"associatedData": "transaction"
}
]
}{
"code": 200,
"message": "success",
"data": [
{
"transactionId": "4200001347202202070541113364",
"transactionState": "SUCCESS",
"amount": {
"payerTotal": 42,
"payerCurrency": "string",
"total": 42,
"currency": "string"
},
"orderRef": "test20220207013",
"payerOpenId": "osGEYs0HfdUF4R965HMmEPKqOSWw",
"successTime": "2022-02-07T16:50:57+08:00",
"bankType": "2022-02-07T16:50:57+08:00",
"error": "Failed to decrypt VDpnk: Incorrect padding"
}
]
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Broker callback managment for payment company
Merchant name to payment company, e.g. wechat.prod
Callback request ID
Create time of callback request
Resource type
Event type of current callback request
Summary of callback request
Resource of callback request
Payment company callback original type
Payment company callback algorithm used to encrypt
Payment company transaction data ciphertext
Associated data with ciphertext
Nonce string with ciphertext
curl \
-X POST https://nomad.samarkand-global.cn/broker/v1/payms/callback/{merchant}?app-api-key=api_token_value \
-H "Content-Type: application/json" \
-d '{"id":"20fac95b-aa12-529c-9c2d-44b9779703fd","create_time":"2022-02-07T16:50:57+08:00","resource_type":"encrypt-resource","event_type":"TRANSACTION.SUCCESS","summary":"支付成功","resource":{"original_type":"transaction","algorithm":"AEAD_AES_256_GCM","ciphertext":"VDpnk1kbgBRJKJFlQKYO2mDWRDxmVvBgCgUjoBnOusp6Et8wcx...","associated_data":"transaction","nonce":"cdcO3WeDbRgR"}}'{
"id": "20fac95b-aa12-529c-9c2d-44b9779703fd",
"create_time": "2022-02-07T16:50:57+08:00",
"resource_type": "encrypt-resource",
"event_type": "TRANSACTION.SUCCESS",
"summary": "支付成功",
"resource": {
"original_type": "transaction",
"algorithm": "AEAD_AES_256_GCM",
"ciphertext": "VDpnk1kbgBRJKJFlQKYO2mDWRDxmVvBgCgUjoBnOusp6Et8wcx...",
"associated_data": "transaction",
"nonce": "cdcO3WeDbRgR"
}
}"success""failure"Merchant name to payment company, e.g. wechat.prod
The payout number of the merchant, shall be generated by the merchant when initiating the payout request
Payment system internal order number
Must be wechatpay or alipay
Values are wechatpay or alipay.
Query funds to abroad order successfully.
Response message
The payout number of the merchant, shall be generated by the merchant when initiating the payout request
Payment company payout number
The payout number of the merchant, shall be generated by the merchant when initiating the payout request
Payout order result state
Values are ACCEPT, SUCCESS, or FAIL.
Payout order failed reason. Request status that can be retried: BALANCE_NOT_ENOUGH
Amount of RMB to be payout, unit is cent
Foreign amount to be payout, minimum unit of money
Foreign currency of amount
The ratio of the quoted currency to the payment currency multiplied by 10 to the eighth Value, for example, if the ratio of USD to RMB is 6.5, rate=650000000
Exchange rate time，east 8 regional time
Estimate exchange rate time，east 8 regional time
Available abroad amounts, unit is cent
Request validation failure
Not Authenticated.
Something wrong when query the payout.
curl \
-X GET https://nomad.samarkand-global.cn/broker/v1/payout/abroad/wechat.prod?out_order_id=string&transaction_id=string&app-api-key=api_token_value{
"code": 200,
"message": "success",
"outOrderId": "string",
"transactionId": "42000000000_123123",
"payoutOrderId": "string",
"result": "SUCCESS",
"failReason": "BALANCE_NOT_ENOUGH",
"amount": 88,
"foreignAmount": 88,
"foreignCurrency": 88,
"rate": 88,
"exchangeRateTime": "2015-05-20T13:29:35.120+08:00",
"estimateExchangeRateTime": "2015-05-20T13:29:35.120+08:00",
"availableAbroadAmount": 88
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Merchant name to payment company, e.g. wechat.prod
The payout number of the merchant, shall be generated by the merchant when initiating the payout request
Payment company transaction number
Payment method, must be wechatpay or alipay
Values are wechatpay or alipay.
Amount of RMB to be payout, unit is cent
Currency of overseas payment. Note: The currency field is related to Payment company payee ID
Goods information, the number cannot exceed 10
Goods name.
The merchant's own classification， for example, with/interval.
Goods unit price, unit is cent
Goods quantity
Name of operator of overseas seller
Name of the overseas seller's shop
The ID of the seller inside the merchant system
Logistics order number
Name of logistics provider
The payee ID assigned by Payment company when accessing the outbound service of Pay.
Create funds to abroad order successfully.
Response message
The payout number of the merchant, shall be generated by the merchant when initiating the payout request
Payment company payout number
The payout number of the merchant, shall be generated by the merchant when initiating the payout request
Payout order result state
Values are ACCEPT, SUCCESS, or FAIL.
Payout order failed reason. Request status that can be retried: BALANCE_NOT_ENOUGH
Amount of RMB to be payout, unit is cent
Foreign amount to be payout, minimum unit of money
Foreign currency of amount
The ratio of the quoted currency to the payment currency multiplied by 10 to the eighth Value, for example, if the ratio of USD to RMB is 6.5, rate=650000000
Exchange rate time，east 8 regional time
Estimate exchange rate time，east 8 regional time
Available abroad amounts, unit is cent
Request validation failure
Not Authenticated.
Something wrong when query the payout.
curl \
-X POST https://nomad.samarkand-global.cn/broker/v1/payout/abroad/wechat.prod?app-api-key=api_token_value \
-H "Content-Type: application/json" \
-d '{"outOrderId":"string","transactionId":"transaction_id_123","paymentMethod":"wechatpay","amount":88,"foreignCurrency":"USD","goodsInfo":[{"goodsName":"Orange","goodsCategory":"health-beauty/fragrance","goodsUnitPrice":12,"goodsQuantity":1}],"sellerInfo":{"overseaBusinessName":"香港 xxxx 公司","overseaShopName":"香港 xxx 公司 xxx 店铺","sellerId":"id2123123123"},"expressInfo":{"courierNumber":"SF1341558741234","expressCompanyName":"国际 xxx 物流"},"payeeInfo":{"payeeId":"id123112312"}}'{
"outOrderId": "string",
"transactionId": "transaction_id_123",
"paymentMethod": "wechatpay",
"amount": 88,
"foreignCurrency": "USD",
"goodsInfo": [
{
"goodsName": "Orange",
"goodsCategory": "health-beauty/fragrance",
"goodsUnitPrice": 12,
"goodsQuantity": 1
}
],
"sellerInfo": {
"overseaBusinessName": "香港 xxxx 公司",
"overseaShopName": "香港 xxx 公司 xxx 店铺",
"sellerId": "id2123123123"
},
"expressInfo": {
"courierNumber": "SF1341558741234",
"expressCompanyName": "国际 xxx 物流"
},
"payeeInfo": {
"payeeId": "id123112312"
}
}{
"code": 200,
"message": "success",
"outOrderId": "string",
"transactionId": "42000000000_123123",
"payoutOrderId": "string",
"result": "SUCCESS",
"failReason": "BALANCE_NOT_ENOUGH",
"amount": 88,
"foreignAmount": 88,
"foreignCurrency": 88,
"rate": 88,
"exchangeRateTime": "2015-05-20T13:29:35.120+08:00",
"estimateExchangeRateTime": "2015-05-20T13:29:35.120+08:00",
"availableAbroadAmount": 88
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Merchant name to payment company, e.g. wechat.prod
Bill date. Query format YYYY-MM-DD, for example, 2021-01-01
Merchant ID of merchant.
Must be wechatpay or alipay
Values are wechatpay or alipay.
curl \
-X GET https://nomad.samarkand-global.cn/broker/v1/payout/bill/abroad/{merchant}?bill_date=string&app-api-key=api_token_value{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Merchant name to payment company, e.g. wechat.prod
Abroad payout bill operations, available: GetAvailableAbroadAmounts
Payment company transaction number
Payment method, must be wechatpay or alipay
Values are wechatpay or alipay.
Payout funds transactions operation execute successfully.
Response message
The payout number of the merchant, shall be generated by the merchant when initiating the payout request
Payment company payout number
The payout number of the merchant, shall be generated by the merchant when initiating the payout request
Payout order result state
Values are ACCEPT, SUCCESS, or FAIL.
Payout order failed reason. Request status that can be retried: BALANCE_NOT_ENOUGH
Amount of RMB to be payout, unit is cent
Foreign amount to be payout, minimum unit of money
Foreign currency of amount
The ratio of the quoted currency to the payment currency multiplied by 10 to the eighth Value, for example, if the ratio of USD to RMB is 6.5, rate=650000000
Exchange rate time，east 8 regional time
Estimate exchange rate time，east 8 regional time
Available abroad amounts, unit is cent
Request validation failure
Not Authenticated.
Something wrong when download the payout bill.
curl \
-X POST https://nomad.samarkand-global.cn/broker/v1/payout/bill/abroad/{merchant}?app-api-key=api_token_value \
-H "Content-Type: application/json" \
-d '{"operation":"GetAvailableAbroadAmounts","transactionId":"transaction_id_123","paymentMethod":"wechatpay"}'{
"operation": "GetAvailableAbroadAmounts",
"transactionId": "transaction_id_123",
"paymentMethod": "wechatpay"
}{
"code": 200,
"message": "success",
"outOrderId": "string",
"transactionId": "42000000000_123123",
"payoutOrderId": "string",
"result": "SUCCESS",
"failReason": "BALANCE_NOT_ENOUGH",
"amount": 88,
"foreignAmount": 88,
"foreignCurrency": 88,
"rate": 88,
"exchangeRateTime": "2015-05-20T13:29:35.120+08:00",
"estimateExchangeRateTime": "2015-05-20T13:29:35.120+08:00",
"availableAbroadAmount": 88
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}Merchant name to payment company, e.g. wechat.prod
The profit sharing number of the merchant, shall be unique within merchant system
Payment system internal order number
Must be wechatpay or alipay
Values are wechatpay or alipay.
Query a profit order successfully.
Response message
The profit sharing number of the merchant
Transaction ID of payment company
Payment system order number, the unique identifier returned by the payment system
Profit sharing order status
Values are PROCESSING or FINISHED.
Receivers of the profit sharing
Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal. PERSONAL_OPENID is not available
Values are MERCHANT_ID or PERSONAL_OPENID.
The receiver account.
The amount of account allocation, in cent, cannot exceed the payment amount of the original order and the maximum proportion of account allocation
The description of profit sharing.
Merchant ID of receiver.
Profit sharing order result
Values are PENDING, SUCCESS, REFUND, or CLOSED.
The finish time of profit sharing with the rfc3339 standard format.
The failed reason of profit sharing.
Values are ACCOUNT_ABNORMAL, NO_RELATION, or RECEIVER_HIGH_RISK.
Profit sharing detailed order number, which can be used for reconciliation with the fund bill.
Description of the end of the profit sharing
The amount of the end of the profit sharing, in cent
Request validation failure
Not Authenticated.
Something wrong when query the payout.
curl \
-X GET https://nomad.samarkand-global.cn/broker/v1/profit/sharing/wechat.prod?profit_order_no=string&transaction_id=string&app-api-key=api_token_value{
"code": 200,
"message": "success",
"outOrderNo": "string",
"transactionId": "transaction_id_123",
"orderId": "string",
"status": "FINISHED",
"receivers": [
{
"type": "MERCHANT_ID",
"receiverAccount": "1900000109",
"amount": 12,
"description": "分帐1900000110",
"receiverMchid": "Orange",
"result": "SUCCESS",
"finishTime": "2015-05-20T13:29:35.120+08:00",
"failReason": "NO_RELATION",
"detailId": "3601111111111111111111"
}
],
"finishDescription": "string",
"finishAmount": 88
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Merchant name to payment company, e.g. wechat.prod
Merchant system order number
Payment company transaction number
Whether the account distribution is completed. If it is false, the remaining amount of this order will not be unfrozen and returned to the secondary merchants, and the order can be divided again.
Default value is false.
Description for finishing profit orders
Receivers of the profit sharing.
Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal. PERSONAL_OPENID is not available
Values are MERCHANT_ID or PERSONAL_OPENID.
The receiver account.
The amount of account allocation, in cent, cannot exceed the payment amount of the original order and the maximum proportion of account allocation
The description of profit sharing.
Payment method, must be wechatpay or alipay
Values are wechatpay or alipay.
Create a profit order successfully.
Response message
The profit sharing number of the merchant
Transaction ID of payment company
Payment system order number, the unique identifier returned by the payment system
Profit sharing order status
Values are PROCESSING or FINISHED.
Receivers of the profit sharing
Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal. PERSONAL_OPENID is not available
Values are MERCHANT_ID or PERSONAL_OPENID.
The receiver account.
The amount of account allocation, in cent, cannot exceed the payment amount of the original order and the maximum proportion of account allocation
The description of profit sharing.
Merchant ID of receiver.
Profit sharing order result
Values are PENDING, SUCCESS, REFUND, or CLOSED.
The finish time of profit sharing with the rfc3339 standard format.
The failed reason of profit sharing.
Values are ACCOUNT_ABNORMAL, NO_RELATION, or RECEIVER_HIGH_RISK.
Profit sharing detailed order number, which can be used for reconciliation with the fund bill.
Description of the end of the profit sharing
The amount of the end of the profit sharing, in cent
Request validation failure
Not Authenticated.
Something wrong when query the payout.
curl \
-X PUT https://nomad.samarkand-global.cn/broker/v1/profit/sharing/wechat.prod?app-api-key=api_token_value \
-H "Content-Type: application/json" \
-d '{"orderRef":"string","transactionId":"transaction_id_123","finish":false,"finishDesc":"分账完结","receivers":[{"type":"MERCHANT_ID","receiverAccount":"1900000109","amount":12,"description":"分帐1900000110"}],"paymentMethod":"wechatpay"}'{
"orderRef": "string",
"transactionId": "transaction_id_123",
"finish": false,
"finishDesc": "分账完结",
"receivers": [
{
"type": "MERCHANT_ID",
"receiverAccount": "1900000109",
"amount": 12,
"description": "分帐1900000110"
}
],
"paymentMethod": "wechatpay"
}{
"code": 200,
"message": "success",
"outOrderNo": "string",
"transactionId": "transaction_id_123",
"orderId": "string",
"status": "FINISHED",
"receivers": [
{
"type": "MERCHANT_ID",
"receiverAccount": "1900000109",
"amount": 12,
"description": "分帐1900000110",
"receiverMchid": "Orange",
"result": "SUCCESS",
"finishTime": "2015-05-20T13:29:35.120+08:00",
"failReason": "NO_RELATION",
"detailId": "3601111111111111111111"
}
],
"finishDescription": "string",
"finishAmount": 88
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Merchant name to payment company, e.g. wechat.prod
Merchant system order number
Payment company transaction number
Whether the account distribution is completed. If it is false, the remaining amount of this order will not be unfrozen and returned to the secondary merchants, and the order can be divided again.
Default value is false.
Description for finishing profit orders
Receivers of the profit sharing.
Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal. PERSONAL_OPENID is not available
Values are MERCHANT_ID or PERSONAL_OPENID.
The receiver account.
The amount of account allocation, in cent, cannot exceed the payment amount of the original order and the maximum proportion of account allocation
The description of profit sharing.
Payment method, must be wechatpay or alipay
Values are wechatpay or alipay.
Create a profit order successfully.
Response message
The profit sharing number of the merchant
Transaction ID of payment company
Payment system order number, the unique identifier returned by the payment system
Profit sharing order status
Values are PROCESSING or FINISHED.
Receivers of the profit sharing
Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal. PERSONAL_OPENID is not available
Values are MERCHANT_ID or PERSONAL_OPENID.
The receiver account.
The amount of account allocation, in cent, cannot exceed the payment amount of the original order and the maximum proportion of account allocation
The description of profit sharing.
Merchant ID of receiver.
Profit sharing order result
Values are PENDING, SUCCESS, REFUND, or CLOSED.
The finish time of profit sharing with the rfc3339 standard format.
The failed reason of profit sharing.
Values are ACCOUNT_ABNORMAL, NO_RELATION, or RECEIVER_HIGH_RISK.
Profit sharing detailed order number, which can be used for reconciliation with the fund bill.
Description of the end of the profit sharing
The amount of the end of the profit sharing, in cent
Request validation failure
Not Authenticated.
Something wrong when query the payout.
curl \
-X POST https://nomad.samarkand-global.cn/broker/v1/profit/sharing/wechat.prod?app-api-key=api_token_value \
-H "Content-Type: application/json" \
-d '{"orderRef":"string","transactionId":"transaction_id_123","finish":false,"finishDesc":"分账完结","receivers":[{"type":"MERCHANT_ID","receiverAccount":"1900000109","amount":12,"description":"分帐1900000110"}],"paymentMethod":"wechatpay"}'{
"orderRef": "string",
"transactionId": "transaction_id_123",
"finish": false,
"finishDesc": "分账完结",
"receivers": [
{
"type": "MERCHANT_ID",
"receiverAccount": "1900000109",
"amount": 12,
"description": "分帐1900000110"
}
],
"paymentMethod": "wechatpay"
}{
"code": 200,
"message": "success",
"outOrderNo": "string",
"transactionId": "transaction_id_123",
"orderId": "string",
"status": "FINISHED",
"receivers": [
{
"type": "MERCHANT_ID",
"receiverAccount": "1900000109",
"amount": 12,
"description": "分帐1900000110",
"receiverMchid": "Orange",
"result": "SUCCESS",
"finishTime": "2015-05-20T13:29:35.120+08:00",
"failReason": "NO_RELATION",
"detailId": "3601111111111111111111"
}
],
"finishDescription": "string",
"finishAmount": 88
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Merchant name to payment company, e.g. wechat.prod
Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal. PERSONAL_OPENID is not available
Values are MERCHANT_ID or PERSONAL_OPENID.
The receiver account.
The receiver name.
Relationship between sub-merchant and recipient.
Values are SUPPLIER, DISTRIBUTOR, SERVICE_PROVIDER, PLATFORM, or OTHERS.
Ciphertext of individual name(verify if value is passed)
Payment method, must be wechatpay or alipay
Values are wechatpay or alipay.
curl \
-X POST https://nomad.samarkand-global.cn/broker/v1/profit/receiver/wechat.prod?app-api-key=api_token_value \
-H "Content-Type: application/json" \
-d '{"type":"MERCHANT_ID","account":"1900000109","name":"张三网络公司","relationType":"OTHERS","encryptedName":"hu89ohu89ohu89o","paymentMethod":"wechatpay"}'{
"type": "MERCHANT_ID",
"account": "1900000109",
"name": "张三网络公司",
"relationType": "OTHERS",
"encryptedName": "hu89ohu89ohu89o",
"paymentMethod": "wechatpay"
}{
"code": 200,
"message": "success",
"type": "MERCHANT_ID",
"account": "1900000109"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Merchant name to payment company, e.g. wechat.prod
Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal. PERSONAL_OPENID is not available
Values are MERCHANT_ID or PERSONAL_OPENID.
The receiver account.
Must be wechatpay or alipay
Values are wechatpay or alipay.
curl \
-X DELETE https://nomad.samarkand-global.cn/broker/v1/profit/receiver/wechat.prod?type=MERCHANT_ID&app-api-key=api_token_value{
"code": 200,
"message": "success",
"type": "MERCHANT_ID",
"account": "1900000109"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success"
}{
"code": 200,
"message": "success",
"errors": "Something wrong when making the service."
}Merchant name to payment company, e.g. weixinpay.test
Payment company refund no.
Merchant payment order refund no.
Must be wechatpay or alipay
Values are wechatpay or alipay.
Query refund payment successfully.
Response message
Refund ID of payment company
Merchant system order number
Merchant refund order no
Transaction ID
Transaction ID
Bank card no
Refund create time
Refund success time
Refund state, SUCCESS: The refund is successful, CLOSE: The refund is closed, PROCESSING: The refund is being processed, ABNORMAL: The refund is abnormal.
Refund amount of current refund order, unit is fen
Total amount of current order, unit is fen
The refund amount of payer, unit is fen
The total amount of payer paid, unit is fen
The refund amount of settlement, unit is fen
The total amount of settlement, unit is fen