Nomad Broker
1.8.0

Nomad payment provider aggregation, including make payments, and customs declaration for orders and etc.

This is the documentation for version 1.8.0 of the API. Last update on Aug 1, 2022.

Base URL 
https://nomad.samarkand-global.cn/broker/v1

Authentication

Authorization (http_api_key)

Send an authentication token in the app-api-key header to authenticate with the API.

payment

Transaction services.

QueryPayment

GET /payment/{merchant}

Query a payment

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. weixinpay.test

Query parameters

Responses

GET /payment/{merchant} 
curl \
 -X GET https://nomad.samarkand-global.cn/broker/v1/payment/wechat.sh_smk?order_ref=test202101 \
 -H "app-api-key: $API_KEY"
Response example (200) 
{
  "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",
  "tradeMessage": "string"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

CreatePayment

POST /payment/{merchant}

Create a payment

Headers

  • X-Real-Ip string

    The real IP address of client, e.g. 127.0.0.1

  • Client-Id string

    Client ID, that can be customer ID

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. weixinpay.test

Body

  • paymentMethod string Required

    Payment method, must be wechatpay or alipay

    Values are wechatpay or alipay.

  • paymentType string Required

    Payment companies have different payment types

    Values are NATIVE, H5, JSAPI, MINIPRO, or APP.

  • orderRef string Required

    Merchant system order number

  • actualAmount integer Required

    Order actual amount, which uses the base unit of current currency

  • total integer

    Order total amount, which uses the base unit of current currency

  • subsidyAmount integer

    Subsidy amount, only works when profitSharing is True

  • costPrice integer

    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.

  • invoiceId string

    Merchant invoice ID, need to use with products data

  • currency string Required

    Must be CNY or GBP

  • profitSharing boolean

    Whether the order is going to share profit

    Default value is true.

  • products array[object] | null

    Payment product

  • description string

    Order product description

  • attach string

    Payment attach data, which could be used by payment notifies

  • timeExpire string

    Payment due time

  • goodsTag string

    Coupon goods tag

  • payerId string

    Payer ID of customer in service provider side.

  • merchantPayerId string

    Payer ID of customer in merchant side.

  • notifyUrl string

    Notify url, that is used by payment company.

  • successUrl string

    Success url, that is used by alipay company.

  • cancelUrl string

    Cancel url, that is used by alipay company.

  • spAppId string

    App ID of payment company.

Responses

  • • 200 object

    Create a payment successfully.

    • code integer(int32)
    • message string | null

      Response message

    • payMessage string | null

      Payment message responsed from payment company

    • payInvokeMessage string | null

      Payment invoked message responsed from payment company

    • timeStamp string | null

      Timestamp, used to sign

    • nonceStr string | null

      Random string up to 32 characters, used to sign

  • • 401 object

    Not Authenticated.

  • • 422 object

    Request validation failure

  • • 500 object

    Something wrong when making the payment.

POST /payment/{merchant} 
curl \
 -X POST https://nomad.samarkand-global.cn/broker/v1/payment/wechat.sh_smk \
 -H "app-api-key: $API_KEY" \
 -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","spAppId":"string"}'
Request example 
# 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",
  "spAppId": "string"
}
Response example (200) 
{
  "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"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (422) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

ClosePayment

POST /payment/close/{merchant}/{order_ref}

Close a payment

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. weixinpay.test

  • order_ref string Required

    Merchant order no.

Query parameters

  • payment_method string

    Must be wechatpay or alipay

    Values are wechatpay or alipay.

Responses

POST /payment/close/{merchant}/{order_ref} 
curl \
 -X POST https://nomad.samarkand-global.cn/broker/v1/payment/close/wechat.sh_smk/orderno2022030300011 \
 -H "app-api-key: $API_KEY"
Response example (200) 
{
  "code": 200,
  "message": "success",
  "paymentMessage": "success"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (422) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

InvokePayment

POST /payment/invocation/{merchant}

Invoke a payment

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. weixinpay.test

Body

  • paymentMethod string Required

    Payment method, must be wechatpay or alipay

    Values are wechatpay or alipay.

  • paymentType string Required

    Payment companies have different payment types

    Values are NATIVE, H5, JSAPI, MINIPRO, or APP.

  • payMessage string Required

    Pay message responsed from payment company

  • timeStamp string

    This url is notified when the payment succeeds

  • nonceStr string

    A random string of up to 32 characters

Responses

  • • 200 object

    Invoke a payment order successfully.

    • code integer(int32)
    • message string | null

      Response message

    • payMessage string | null

      Payment message responsed from payment company

    • payInvokeMessage string | null

      Payment invoked message responsed from payment company

    • timeStamp string | null

      Timestamp, used to sign

    • nonceStr string | null

      Random string up to 32 characters, used to sign

  • • 401 object

    Not Authenticated.

  • • 422 object

    Request validation failure

  • • 500 object

    Something wrong when making the payment.

POST /payment/invocation/{merchant} 
curl \
 -X POST https://nomad.samarkand-global.cn/broker/v1/payment/invocation/wechat.sh_smk \
 -H "app-api-key: $API_KEY" \
 -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"}'
Request example 
{
  "paymentMethod": "wechatpay",
  "paymentType": "H5",
  "payMessage": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx2711083",
  "timeStamp": 1414561699,
  "nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS"
}
Response example (200) 
{
  "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"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (422) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

customs

The payment customs declarance.

GetCustomsPayment

GET /customs/payment/{merchant}

Merchant queries customs clearance information by order number

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. wechat.sh_smk

Query parameters

  • customs string Required

    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.

  • order_no string

    The internal order number of the merchant system

  • transaction_id string

    Payment system internal order number

  • sub_order_no string

    The internal sub-order number of the merchant system

  • sub_order_id string

    The internal sub-order number of the payment company system

  • payment_method string

    Must be wechatpay or alipay

    Values are wechatpay or alipay.

Responses

  • • 200 object

    Get a payment declaration result to customs successfully.

    • code integer(int32)
    • message string | null

      Response message

    • customsMessage string | null

      Original customs return message from payment company

    • resultCode string | null

      The third party response code

    • transactionId string | null

      Transaction ID returned by payment company

    • orders array[object]

      Contents of payment order

      • state string | null

        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

      • subOrderNo string | null

        The internal order number of the merchant system

      • subOrderId string | null

        Transaction ID returned by payment company

      • mchCustomsNo string | null

        The merchant’s record number registered in the customs

      • explanation string | null

        The declaration result indicates that if the status is failed or abnormal, the failure reason is displayed

      • customs string | null

        Customs code

      • modifyTime string | null

        The last update time, time zone is GMT+8 beijing

      • duty integer | null

        Tariff, divided into units

      • feeType string | null

        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.

      • orderFee integer | null

        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.

      • transportFee integer | null

        The logistics cost is divided into units, and must be passed if there is a split order.

      • productFee integer | null

        Commodity costs, in units of cents, must be passed if there is a split order.

      • certType string | null

        Only mainland ID cards are supported temporarily.

        Default value is IDCARD.

      • certCheckResult string | null

        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

      • verifyDepartment string | null

        The verification agencies

      • verifyDepartmentTradeId string

        Transaction serial number, from the verification agency, such as the transaction serial number recorded by UnionPay, for merchants to report to the customs

  • • 400 object

    Request validation failure

  • • 401 object

    Not Authenticated.

  • • 500 object

    Something wrong when declaring the payment.

GET /customs/payment/{merchant} 
curl \
 -X GET https://nomad.samarkand-global.cn/broker/v1/customs/payment/wechat.sh_smk?customs=GUANGZHOU_ZS \
 -H "app-api-key: $API_KEY"
Response example (200) 
{
  "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"
    }
  ]
}
Response example (400) 
{
  "code": 200,
  "message": "success"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

PutCustomsPayment

PUT /customs/payment/{merchant}

Redeclare an payment order to the customs

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. wechat.sh_smk

Body

  • customs string Required

    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.

  • mchCustomsNo string Required

    The merchant’s record number registered in the customs

  • orderNo string

    The internal order number of the merchant system, only numbers, uppercase and lowercase letters, and it is unique under the same merchant number.

  • transactionId string

    Transaction ID returned by payment company

  • subOrderNo string

    Merchant's sub-order number, must be passed if there is a split order

  • subOrderId string

    Do not fill in the sub-order number. Order number returned by payment company

  • paymentMethod string

    Payment method, must be wechatpay or alipay

    Values are wechatpay or alipay.

Responses

  • • 200 object

    Payment response.

    • code integer(int32)
    • message string | null

      Response message

    • customsMessage string | null

      Original customs return message from payment company

    • resultCode string | null

      The third party response code

    • state string | null

      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

    • transactionId string | null

      Transaction ID returned by payment company

    • orderNo string | null

      The internal order number of the merchant system

    • subOrderNo string | null

      The internal order number of the merchant system

    • modifyTime string | null

      The last update time, time zone is GMT+8 beijing

    • certCheckResult string | null

      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

    • verifyDepartment string | null

      The verification agencies

    • verifyDepartmentTradeId string

      Transaction serial number, from the verification agency, such as the transaction serial number recorded by UnionPay, for merchants to report to the customs

  • • 400 object

    Request validation failure

  • • 401 object

    Not Authenticated.

  • • 500 object

    Something wrong when redeclare the payment.

PUT /customs/payment/{merchant} 
curl \
 -X PUT https://nomad.samarkand-global.cn/broker/v1/customs/payment/wechat.sh_smk \
 -H "app-api-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"customs":"GUANGZHOU_ZS","mchCustomsNo":"31123452K0","orderNo":"test2021101901","transactionId":"4200001306202110500000000000.0","subOrderNo":"1000320306201511078440737890","subOrderId":"4200001306202110500000000000.0","paymentMethod":"wechatpay"}'
Request example 
{
  "customs": "GUANGZHOU_ZS",
  "mchCustomsNo": "31123452K0",
  "orderNo": "test2021101901",
  "transactionId": "4200001306202110500000000000.0",
  "subOrderNo": "1000320306201511078440737890",
  "subOrderId": "4200001306202110500000000000.0",
  "paymentMethod": "wechatpay"
}
Response example (200) 
{
  "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"
}
Response example (400) 
{
  "code": 200,
  "message": "success"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

PostCustomsPayment

POST /customs/payment/{merchant}

Declare an payment order to the customs

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. wechat.sh_smk

Body

  • orderNo string Required

    The internal order number of the merchant system, only numbers, uppercase and lowercase letters, and it is unique under the same merchant number.

  • transactionId string Required

    Transaction ID returned by Payment company

  • customs string Required

    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.

  • paymentMethod string

    Payment method, must be wechatpay or alipay

    Values are wechatpay or alipay.

  • mchCustomsNo string

    The merchant’s record number registered in the customs

  • certType string

    Only mainland ID cards are supported temporarily.

    Default value is IDCARD.

  • certId string

    The user's mainland ID number, the ID number ending in the letter X, please capitalize the letter X.

  • name string

    User name.

  • duty integer

    Tariff, divided into units

  • actionType string

    ADD New customs declaration application, MODIFY modification. Default is ADD

    Values are ADD or MODIFY. Default value is ADD.

  • subOrderNo string

    Merchant's sub-order number, must be passed if there is a split order

  • feeType string

    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.

  • orderFee integer

    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.

  • transportFee integer

    The logistics cost is divided into units, and must be passed if there is a split order.

  • productFee integer

    Commodity costs, in units of cents, must be passed if there is a split order.

Responses

  • • 200 object

    Declare payment to customs successfully.

    • code integer(int32)
    • message string | null

      Response message

    • customsMessage string | null

      Original customs return message from payment company

    • resultCode string | null

      The third party response code

    • state string | null

      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

    • transactionId string | null

      Transaction ID returned by payment company

    • orderNo string | null

      The internal order number of the merchant system

    • subOrderNo string | null

      The internal order number of the merchant system

    • modifyTime string | null

      The last update time, time zone is GMT+8 beijing

    • certCheckResult string | null

      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

    • verifyDepartment string | null

      The verification agencies

    • verifyDepartmentTradeId string

      Transaction serial number, from the verification agency, such as the transaction serial number recorded by UnionPay, for merchants to report to the customs

  • • 400 object

    Request validation failure

  • • 401 object

    Not Authenticated.

  • • 500 object

    Something wrong when declaring the payment.

POST /customs/payment/{merchant} 
curl \
 -X POST https://nomad.samarkand-global.cn/broker/v1/customs/payment/wechat.sh_smk \
 -H "app-api-key: $API_KEY" \
 -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}'
Request example 
{
  "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
}
Response example (200) 
{
  "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"
}
Response example (400) 
{
  "code": 200,
  "message": "success"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

PostCustomsIdentification

POST /customs/identification/{merchant}

Upload the payer identity information which will be re-verified by payment provider, supported payment method: wechatpay

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. wechat.sh_smk

Body

  • orderNo string Required

    The internal order number of the merchant system, only numbers, uppercase and lowercase letters, and it is unique under the same merchant number.

  • transactionId string Required

    Transaction ID returned by Payment company

  • subOrderNo string

    Merchant's sub-order number, must be passed if there is a split order

  • customs string Required

    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.

  • paymentMethod string

    Payment method, must be wechatpay or alipay

    Values are wechatpay or alipay.

  • mchCustomsNo string

    The merchant’s record number registered in the customs

  • certType string Required

    Only mainland ID cards are supported temporarily.

    Default value is IDCARD.

  • certId string Required

    The user's mainland ID number, the ID number ending in the letter X, please capitalize the letter X.

  • certName string Required

    Payer name.

Responses

  • • 200 object

    Declare payment to customs successfully.

    • code integer(int32)
    • message string | null

      Response message

    • orderNo string | null

      The internal order number of the merchant system.

    • transactionId string | null

      Transaction ID returned by Payment company

    • subOrderNo string | null

      Merchant's sub-order number, must be passed if there is a split order

    • customs string | null

      Customs code

    • mchCustomsNo string | null

      The merchant’s record number registered in the customs

    • certType string | null

      Only mainland ID cards are supported temporarily.

      Default value is IDCARD.

    • certId string | null

      The user's mainland ID number, the ID number ending in the letter X, please capitalize the letter X.

    • certName string | null

      Payer name.

  • • 400 object

    Request validation failure

  • • 401 object

    Not Authenticated.

  • • 500 object

    Something wrong when declaring the payment.

POST /customs/identification/{merchant} 
curl \
 -X POST https://nomad.samarkand-global.cn/broker/v1/customs/identification/wechat.sh_smk \
 -H "app-api-key: $API_KEY" \
 -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"}'
Request example 
{
  "orderNo": "test2021101901",
  "transactionId": "4200001306202110500000000000.0",
  "subOrderNo": 20150806125346,
  "customs": "GUANGZHOU_ZS",
  "paymentMethod": "wechatpay",
  "mchCustomsNo": "31123452K0",
  "certType": "IDCARD",
  "certId": 330821198809085200,
  "certName": "Zhangsan"
}
Response example (200) 
{
  "code": 200,
  "message": "success",
  "orderNo": "test2021101901",
  "transactionId": "4200001306202110500000000000.0",
  "subOrderNo": 20150806125346,
  "customs": "string",
  "mchCustomsNo": "31123452K0",
  "certType": "IDCARD",
  "certId": 330821198809085200,
  "certName": "Zhangsan"
}
Response example (400) 
{
  "code": 200,
  "message": "success"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

refund

The refund services.

QueryRefund

GET /refund/{merchant}

Query a refund

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. weixinpay.test

Query parameters

Responses

  • • 200 object

    Query refund payment successfully.

    • code integer(int32)
    • message string | null

      Response message

    • refundId string | null

      Refund ID of payment company

    • orderRef string | null

      Merchant system order number

    • refundOrderRef string | null

      Merchant refund order no

    • transactionId string | null

      Transaction ID

    • channel string | null

      Transaction ID

    • userReceivedAccount string | null

      Bank card no

    • createTime string | null

      Refund create time

    • successTime string | null

      Refund success time

    • status string | null

      Refund state, SUCCESS: The refund is successful, CLOSE: The refund is closed, PROCESSING: The refund is being processed, ABNORMAL: The refund is abnormal.

    • refundAmount number | null

      Refund amount of current refund order, unit is fen

    • totalAmount number | null

      Total amount of current order, unit is fen

    • payerRefund number | null

      The refund amount of payer, unit is fen

    • payerTotal number | null

      The total amount of payer paid, unit is fen

    • settlementAmount number | null

      The refund amount of settlement, unit is fen

    • settlementTotal number | null

      The total amount of settlement, unit is fen

    • discountRefundAmount number | null

      Coupons refund amount, unit is fen

    • currency string | null

      Amount currency, ISO 4217 three - letter code

    • refundAccount string

      Special parameters for refund of advance funds on e-commerce platform, REFUND_SOURCE_PARTNER_ADVANCE: advance payment is made by e-commerce platforms, which requires wechat Pay to apply for opening REFUND_SOURCE_SUB_MERCHANT: sub merchant, default value

      Values are REFUND_SOURCE_PARTNER_ADVANCE or REFUND_SOURCE_SUB_MERCHANT.

    • fundsAccount string | null

      If the order is profiting, this parameter is used

  • • 401 object

    Not Authenticated.

  • • 500 object

    Something wrong when making the payment.

GET /refund/{merchant} 
curl \
 -X GET https://nomad.samarkand-global.cn/broker/v1/refund/wechat.sh_smk?refund_order_ref=r001test20220125001 \
 -H "app-api-key: $API_KEY"
Response example (200) 
{
  "code": 200,
  "message": "success",
  "refundId": "refund_id_payment_company",
  "orderRef": "test20220125001",
  "refundOrderRef": "r001test20220125001",
  "transactionId": "4200001148202111020556019250",
  "channel": "ORIGINAL",
  "userReceivedAccount": "0403**",
  "createTime": "2021-11-02T17:03:38+08:00",
  "successTime": "2021-11-02T17:03:38+08:00",
  "status": "SUCCESS",
  "refundAmount": 10,
  "totalAmount": 10,
  "payerRefund": 10,
  "payerTotal": 10,
  "settlementAmount": 10,
  "settlementTotal": 10,
  "discountRefundAmount": 10,
  "currency": "CNY",
  "refundAccount": "REFUND_SOURCE_SUB_MERCHANT",
  "fundsAccount": "string"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

CreateRefund

POST /refund/{merchant}

Create a refund

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. weixinpay.test

Body

  • paymentMethod string

    Payment method, must be wechatpay or alipay

    Values are wechatpay or alipay.

  • transactionId string

    Transaction ID

  • orderRef string Required

    Merchant system order number

  • refundOrderRef string Required

    Merchant refund order no

  • reason string

    Refund message to customer

  • refundAmount number Required

    Refund amount, unit is fen

  • totalAmount number Required

    The total order amount of the original payment, unit is fen

  • currency string

    Amount currency, available options: CNY

  • notifyUrl string

    Notify url, receive notification of refund result of wechat Pay.

  • refundAccount string

    Special parameters for refund of advance funds on e-commerce platform, REFUND_SOURCE_PARTNER_ADVANCE: advance payment is made by e-commerce platforms, which requires wechat Pay to apply for opening REFUND_SOURCE_SUB_MERCHANT: sub merchant, default value

    Values are REFUND_SOURCE_PARTNER_ADVANCE or REFUND_SOURCE_SUB_MERCHANT.

  • fundsAccount string

    If the order is profiting, this parameter is used

Responses

  • • 200 object

    Create a refund successfully.

    • code integer(int32)
    • message string | null

      Response message

    • refundId string | null

      Refund ID of payment company

    • orderRef string | null

      Merchant system order number

    • refundOrderRef string | null

      Merchant refund order no

    • transactionId string | null

      Transaction ID

    • channel string | null

      Transaction ID

    • userReceivedAccount string | null

      Bank card no

    • createTime string | null

      Refund create time

    • successTime string | null

      Refund success time

    • status string | null

      Refund state, SUCCESS: The refund is successful, CLOSE: The refund is closed, PROCESSING: The refund is being processed, ABNORMAL: The refund is abnormal.

    • refundAmount number | null

      Refund amount of current refund order, unit is fen

    • totalAmount number | null

      Total amount of current order, unit is fen

    • payerRefund number | null

      The refund amount of payer, unit is fen

    • payerTotal number | null

      The total amount of payer paid, unit is fen

    • settlementAmount number | null

      The refund amount of settlement, unit is fen

    • settlementTotal number | null

      The total amount of settlement, unit is fen

    • discountRefundAmount number | null

      Coupons refund amount, unit is fen

    • currency string | null

      Amount currency, ISO 4217 three - letter code

    • refundAccount string

      Special parameters for refund of advance funds on e-commerce platform, REFUND_SOURCE_PARTNER_ADVANCE: advance payment is made by e-commerce platforms, which requires wechat Pay to apply for opening REFUND_SOURCE_SUB_MERCHANT: sub merchant, default value

      Values are REFUND_SOURCE_PARTNER_ADVANCE or REFUND_SOURCE_SUB_MERCHANT.

    • fundsAccount string | null

      If the order is profiting, this parameter is used

  • • 401 object

    Not Authenticated.

  • • 422 object

    Request validation failure

  • • 500 object

    Something wrong when making the payment.

POST /refund/{merchant} 
curl \
 -X POST https://nomad.samarkand-global.cn/broker/v1/refund/wechat.sh_smk \
 -H "app-api-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"paymentMethod":"wechatpay","transactionId":"4200001148202111020556019250","orderRef":"test20220125001","refundOrderRef":"r001test20220125001","reason":"商品已售完","refundAmount":10,"totalAmount":10,"currency":"CNY","notifyUrl":"https://www.weixin.qq.com","refundAccount":"REFUND_SOURCE_SUB_MERCHANT","fundsAccount":"string"}'
Request example 
{
  "paymentMethod": "wechatpay",
  "transactionId": "4200001148202111020556019250",
  "orderRef": "test20220125001",
  "refundOrderRef": "r001test20220125001",
  "reason": "商品已售完",
  "refundAmount": 10,
  "totalAmount": 10,
  "currency": "CNY",
  "notifyUrl": "https://www.weixin.qq.com",
  "refundAccount": "REFUND_SOURCE_SUB_MERCHANT",
  "fundsAccount": "string"
}
Response example (200) 
{
  "code": 200,
  "message": "success",
  "refundId": "refund_id_payment_company",
  "orderRef": "test20220125001",
  "refundOrderRef": "r001test20220125001",
  "transactionId": "4200001148202111020556019250",
  "channel": "ORIGINAL",
  "userReceivedAccount": "0403**",
  "createTime": "2021-11-02T17:03:38+08:00",
  "successTime": "2021-11-02T17:03:38+08:00",
  "status": "SUCCESS",
  "refundAmount": 10,
  "totalAmount": 10,
  "payerRefund": 10,
  "payerTotal": 10,
  "settlementAmount": 10,
  "settlementTotal": 10,
  "discountRefundAmount": 10,
  "currency": "CNY",
  "refundAccount": "REFUND_SOURCE_SUB_MERCHANT",
  "fundsAccount": "string"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (422) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

settlement

The settlement services.

GetSettlement

GET /settlement/{merchant}

Merchant query settlement data.

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. wechat.sh_smk

Query parameters

  • profit_order_no string Required

    The settlement order no of the merchant, shall be unique within merchant system

  • transaction_id string Required

    Payment system internal order number

  • payment_method string

    Must be wechatpay or alipay

    Values are wechatpay or alipay.

Responses

  • • 200 object

    Query a settlement order successfully.

    • code integer(int32)
    • message string | null

      Response message

    • outOrderNo string | null

      The profit sharing number of the merchant

    • transactionId string | null

      Transaction ID of payment company

    • orderId string | null

      Payment system order number, the unique identifier returned by the payment system

    • status string | null

      Profit sharing order status

      Values are PROCESSING or FINISHED.

    • receivers array[object] | null

      Receivers of the profit sharing

      • type string

        Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal. PERSONAL_OPENID is not available

        Values are MERCHANT_ID or PERSONAL_OPENID.

      • receiverAccount string

        The receiver account.

      • name string

        The receiver account.

      • amount integer(int32)

        The amount of account allocation, in cent, cannot exceed the payment amount of the original order and the maximum proportion of account allocation

      • paymentMethod string

        Payment method, must be wechatpay or alipay

        Values are wechatpay or alipay.

      • description string

        The description of profit sharing.

      • receiverMchid string

        Merchant ID of receiver.

      • result string | null

        Profit sharing order result

        Values are PENDING, SUCCESS, REFUND, or CLOSED.

      • finishTime string

        The finish time of profit sharing with the rfc3339 standard format.

      • failReason string

        The failed reason of profit sharing.

        Values are ACCOUNT_ABNORMAL, NO_RELATION, or RECEIVER_HIGH_RISK.

      • detailId string

        Profit sharing detailed order number, which can be used for reconciliation with the fund bill.

    • finishDescription string | null

      Description of the end of the profit sharing

    • finishAmount integer | null

      The amount of the end of the profit sharing, in cent

  • • 400 object

    Request validation failure

  • • 401 object

    Not Authenticated.

  • • 500 object

    Something wrong when query the payout.

GET /settlement/{merchant} 
curl \
 -X GET https://nomad.samarkand-global.cn/broker/v1/settlement/wechat.sh_smk?profit_order_no=string&transaction_id=string \
 -H "app-api-key: $API_KEY"
Response example (200) 
{
  "code": 200,
  "message": "success",
  "outOrderNo": "string",
  "transactionId": "transaction_id_123",
  "orderId": "string",
  "status": "FINISHED",
  "receivers": [
    {
      "type": "MERCHANT_ID",
      "receiverAccount": "1900000109",
      "name": "1900000109",
      "amount": 12,
      "paymentMethod": "wechatpay",
      "description": "分帐1900000110",
      "receiverMchid": "Orange",
      "result": "SUCCESS",
      "finishTime": "2015-05-20T13:29:35.120+08:00",
      "failReason": "NO_RELATION",
      "detailId": "3601111111111111111111"
    }
  ],
  "finishDescription": "string",
  "finishAmount": 88
}
Response example (400) 
{
  "code": 200,
  "message": "success"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

FinishSettlement

PUT /settlement/{merchant}

Finish a settlement order.

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. wechat.sh_smk

Body

  • orderRef string Required

    Merchant system settlemnt order number

  • transactionId string Required

    Payment company transaction number

  • finish boolean | null

    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.

  • finishDesc string | null

    Description for finishing profit orders

  • receivers array[object] | null

    Receivers of the profit sharing.

    • type string

      Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal. PERSONAL_OPENID is not available

      Values are MERCHANT_ID or PERSONAL_OPENID.

    • receiverAccount string

      The receiver account.

    • name string

      The receiver account.

    • amount integer(int32)

      The amount of account allocation, in cent, cannot exceed the payment amount of the original order and the maximum proportion of account allocation

    • paymentMethod string

      Payment method, must be wechatpay or alipay

      Values are wechatpay or alipay.

    • description string

      The description of profit sharing.

    • receiverMchid string

      Merchant ID of receiver.

    • result string | null

      Profit sharing order result

      Values are PENDING, SUCCESS, REFUND, or CLOSED.

    • finishTime string

      The finish time of profit sharing with the rfc3339 standard format.

    • failReason string

      The failed reason of profit sharing.

      Values are ACCOUNT_ABNORMAL, NO_RELATION, or RECEIVER_HIGH_RISK.

    • detailId string

      Profit sharing detailed order number, which can be used for reconciliation with the fund bill.

  • paymentMethod string

    Payment method, must be wechatpay or alipay

    Values are wechatpay or alipay.

Responses

  • • 200 object

    Finish a settlement order successfully.

    • code integer(int32)
    • message string | null

      Response message

    • outOrderNo string | null

      The profit sharing number of the merchant

    • transactionId string | null

      Transaction ID of payment company

    • orderId string | null

      Payment system order number, the unique identifier returned by the payment system

    • status string | null

      Profit sharing order status

      Values are PROCESSING or FINISHED.

    • receivers array[object] | null

      Receivers of the profit sharing

      • type string

        Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal. PERSONAL_OPENID is not available

        Values are MERCHANT_ID or PERSONAL_OPENID.

      • receiverAccount string

        The receiver account.

      • name string

        The receiver account.

      • amount integer(int32)

        The amount of account allocation, in cent, cannot exceed the payment amount of the original order and the maximum proportion of account allocation

      • paymentMethod string

        Payment method, must be wechatpay or alipay

        Values are wechatpay or alipay.

      • description string

        The description of profit sharing.

      • receiverMchid string

        Merchant ID of receiver.

      • result string | null

        Profit sharing order result

        Values are PENDING, SUCCESS, REFUND, or CLOSED.

      • finishTime string

        The finish time of profit sharing with the rfc3339 standard format.

      • failReason string

        The failed reason of profit sharing.

        Values are ACCOUNT_ABNORMAL, NO_RELATION, or RECEIVER_HIGH_RISK.

      • detailId string

        Profit sharing detailed order number, which can be used for reconciliation with the fund bill.

    • finishDescription string | null

      Description of the end of the profit sharing

    • finishAmount integer | null

      The amount of the end of the profit sharing, in cent

  • • 400 object

    Request validation failure

  • • 401 object

    Not Authenticated.

  • • 500 object

    Something wrong when query the payout.

PUT /settlement/{merchant} 
curl \
 -X PUT https://nomad.samarkand-global.cn/broker/v1/settlement/wechat.sh_smk \
 -H "app-api-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"orderRef":"string","transactionId":"transaction_id_123","finish":false,"finishDesc":"分账完结","receivers":[{"type":"MERCHANT_ID","receiverAccount":"1900000109","name":"1900000109","amount":12,"paymentMethod":"wechatpay","description":"分帐1900000110","receiverMchid":"Orange","result":"SUCCESS","finishTime":"2015-05-20T13:29:35.120+08:00","failReason":"NO_RELATION","detailId":"3601111111111111111111"}],"paymentMethod":"wechatpay"}'
Request example 
{
  "orderRef": "string",
  "transactionId": "transaction_id_123",
  "finish": false,
  "finishDesc": "分账完结",
  "receivers": [
    {
      "type": "MERCHANT_ID",
      "receiverAccount": "1900000109",
      "name": "1900000109",
      "amount": 12,
      "paymentMethod": "wechatpay",
      "description": "分帐1900000110",
      "receiverMchid": "Orange",
      "result": "SUCCESS",
      "finishTime": "2015-05-20T13:29:35.120+08:00",
      "failReason": "NO_RELATION",
      "detailId": "3601111111111111111111"
    }
  ],
  "paymentMethod": "wechatpay"
}
Response example (200) 
{
  "code": 200,
  "message": "success",
  "outOrderNo": "string",
  "transactionId": "transaction_id_123",
  "orderId": "string",
  "status": "FINISHED",
  "receivers": [
    {
      "type": "MERCHANT_ID",
      "receiverAccount": "1900000109",
      "name": "1900000109",
      "amount": 12,
      "paymentMethod": "wechatpay",
      "description": "分帐1900000110",
      "receiverMchid": "Orange",
      "result": "SUCCESS",
      "finishTime": "2015-05-20T13:29:35.120+08:00",
      "failReason": "NO_RELATION",
      "detailId": "3601111111111111111111"
    }
  ],
  "finishDescription": "string",
  "finishAmount": 88
}
Response example (400) 
{
  "code": 200,
  "message": "success"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

PostSettlement

POST /settlement/{merchant}

Create a settlement order.

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. wechat.sh_smk

Body

  • orderRef string Required

    Merchant system settlemnt order number

  • transactionId string Required

    Payment company transaction number

  • finish boolean | null

    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.

  • finishDesc string | null

    Description for finishing profit orders

  • receivers array[object] | null

    Receivers of the profit sharing.

    • type string

      Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal. PERSONAL_OPENID is not available

      Values are MERCHANT_ID or PERSONAL_OPENID.

    • receiverAccount string

      The receiver account.

    • name string

      The receiver account.

    • amount integer(int32)

      The amount of account allocation, in cent, cannot exceed the payment amount of the original order and the maximum proportion of account allocation

    • paymentMethod string

      Payment method, must be wechatpay or alipay

      Values are wechatpay or alipay.

    • description string

      The description of profit sharing.

    • receiverMchid string

      Merchant ID of receiver.

    • result string | null

      Profit sharing order result

      Values are PENDING, SUCCESS, REFUND, or CLOSED.

    • finishTime string

      The finish time of profit sharing with the rfc3339 standard format.

    • failReason string

      The failed reason of profit sharing.

      Values are ACCOUNT_ABNORMAL, NO_RELATION, or RECEIVER_HIGH_RISK.

    • detailId string

      Profit sharing detailed order number, which can be used for reconciliation with the fund bill.

  • paymentMethod string

    Payment method, must be wechatpay or alipay

    Values are wechatpay or alipay.

Responses

  • • 200 object

    Create a settlement order successfully.

    • code integer(int32)
    • message string | null

      Response message

    • outOrderNo string | null

      The profit sharing number of the merchant

    • transactionId string | null

      Transaction ID of payment company

    • orderId string | null

      Payment system order number, the unique identifier returned by the payment system

    • status string | null

      Profit sharing order status

      Values are PROCESSING or FINISHED.

    • receivers array[object] | null

      Receivers of the profit sharing

      • type string

        Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal. PERSONAL_OPENID is not available

        Values are MERCHANT_ID or PERSONAL_OPENID.

      • receiverAccount string

        The receiver account.

      • name string

        The receiver account.

      • amount integer(int32)

        The amount of account allocation, in cent, cannot exceed the payment amount of the original order and the maximum proportion of account allocation

      • paymentMethod string

        Payment method, must be wechatpay or alipay

        Values are wechatpay or alipay.

      • description string

        The description of profit sharing.

      • receiverMchid string

        Merchant ID of receiver.

      • result string | null

        Profit sharing order result

        Values are PENDING, SUCCESS, REFUND, or CLOSED.

      • finishTime string

        The finish time of profit sharing with the rfc3339 standard format.

      • failReason string

        The failed reason of profit sharing.

        Values are ACCOUNT_ABNORMAL, NO_RELATION, or RECEIVER_HIGH_RISK.

      • detailId string

        Profit sharing detailed order number, which can be used for reconciliation with the fund bill.

    • finishDescription string | null

      Description of the end of the profit sharing

    • finishAmount integer | null

      The amount of the end of the profit sharing, in cent

  • • 400 object

    Request validation failure

  • • 401 object

    Not Authenticated.

  • • 500 object

    Something wrong when query the payout.

POST /settlement/{merchant} 
curl \
 -X POST https://nomad.samarkand-global.cn/broker/v1/settlement/wechat.sh_smk \
 -H "app-api-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"orderRef":"string","transactionId":"transaction_id_123","finish":false,"finishDesc":"分账完结","receivers":[{"type":"MERCHANT_ID","receiverAccount":"1900000109","name":"1900000109","amount":12,"paymentMethod":"wechatpay","description":"分帐1900000110","receiverMchid":"Orange","result":"SUCCESS","finishTime":"2015-05-20T13:29:35.120+08:00","failReason":"NO_RELATION","detailId":"3601111111111111111111"}],"paymentMethod":"wechatpay"}'
Request example 
{
  "orderRef": "string",
  "transactionId": "transaction_id_123",
  "finish": false,
  "finishDesc": "分账完结",
  "receivers": [
    {
      "type": "MERCHANT_ID",
      "receiverAccount": "1900000109",
      "name": "1900000109",
      "amount": 12,
      "paymentMethod": "wechatpay",
      "description": "分帐1900000110",
      "receiverMchid": "Orange",
      "result": "SUCCESS",
      "finishTime": "2015-05-20T13:29:35.120+08:00",
      "failReason": "NO_RELATION",
      "detailId": "3601111111111111111111"
    }
  ],
  "paymentMethod": "wechatpay"
}
Response example (200) 
{
  "code": 200,
  "message": "success",
  "outOrderNo": "string",
  "transactionId": "transaction_id_123",
  "orderId": "string",
  "status": "FINISHED",
  "receivers": [
    {
      "type": "MERCHANT_ID",
      "receiverAccount": "1900000109",
      "name": "1900000109",
      "amount": 12,
      "paymentMethod": "wechatpay",
      "description": "分帐1900000110",
      "receiverMchid": "Orange",
      "result": "SUCCESS",
      "finishTime": "2015-05-20T13:29:35.120+08:00",
      "failReason": "NO_RELATION",
      "detailId": "3601111111111111111111"
    }
  ],
  "finishDescription": "string",
  "finishAmount": 88
}
Response example (400) 
{
  "code": 200,
  "message": "success"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

GetSettlementReceiver

GET /settlement/receiver/{merchant}

Merchant query settlement data.

Path parameters

  • merchant string Required

    Merchant name, e.g. wechat.sh_smk

Query parameters

  • payment_method string

    Must be wechatpay or alipay

    Values are wechatpay or alipay.

Responses

  • • 200 object

    Query settlement receivers successfully.

    • code integer(int32)
    • message string | null

      Response message

    • type string | null

      Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal.

      Values are MERCHANT_ID or PERSONAL_OPENID.

    • account string | null

      The receiver account.

    • receivers array[object]
      • type string

        Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal. PERSONAL_OPENID is not available

        Values are MERCHANT_ID or PERSONAL_OPENID.

      • receiverAccount string

        The receiver account.

      • name string

        The receiver account.

      • amount integer(int32)

        The amount of account allocation, in cent, cannot exceed the payment amount of the original order and the maximum proportion of account allocation

      • paymentMethod string

        Payment method, must be wechatpay or alipay

        Values are wechatpay or alipay.

      • description string

        The description of profit sharing.

      • receiverMchid string

        Merchant ID of receiver.

      • result string | null

        Profit sharing order result

        Values are PENDING, SUCCESS, REFUND, or CLOSED.

      • finishTime string

        The finish time of profit sharing with the rfc3339 standard format.

      • failReason string

        The failed reason of profit sharing.

        Values are ACCOUNT_ABNORMAL, NO_RELATION, or RECEIVER_HIGH_RISK.

      • detailId string

        Profit sharing detailed order number, which can be used for reconciliation with the fund bill.

  • • 400

    Request validation failure

GET /settlement/receiver/{merchant} 
curl \
 -X GET https://nomad.samarkand-global.cn/broker/v1/settlement/receiver/wechat.sh_smk \
 -H "app-api-key: $API_KEY"
Response example (200) 
{
  "code": 200,
  "message": "success",
  "type": "MERCHANT_ID",
  "account": "1900000109",
  "receivers": [
    {
      "type": "MERCHANT_ID",
      "receiverAccount": "1900000109",
      "name": "1900000109",
      "amount": 12,
      "paymentMethod": "wechatpay",
      "description": "分帐1900000110",
      "receiverMchid": "Orange",
      "result": "SUCCESS",
      "finishTime": "2015-05-20T13:29:35.120+08:00",
      "failReason": "NO_RELATION",
      "detailId": "3601111111111111111111"
    }
  ]
}

PostSettlementReceiver

POST /settlement/receiver/{merchant}

Create a settlement receiver

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. wechat.sh_smk

Body

  • type string

    Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal. PERSONAL_OPENID is not available

    Values are MERCHANT_ID or PERSONAL_OPENID.

  • account string

    The receiver account.

  • name string

    The receiver name.

  • relationType string

    Relationship between sub-merchant and recipient.

    Values are SUPPLIER, DISTRIBUTOR, SERVICE_PROVIDER, PLATFORM, or OTHERS.

  • encryptedName string

    Ciphertext of individual name(verify if value is passed)

  • description string

    The Settlement receiver description.

  • paymentMethod string

    Payment method, must be wechatpay or alipay

    Values are wechatpay or alipay.

Responses

  • • 200 object

    Create a profit receiver successfully.

    • code integer(int32)
    • message string | null

      Response message

    • type string | null

      Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal.

      Values are MERCHANT_ID or PERSONAL_OPENID.

    • account string | null

      The receiver account.

    • receivers array[object]
      • type string

        Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal. PERSONAL_OPENID is not available

        Values are MERCHANT_ID or PERSONAL_OPENID.

      • receiverAccount string

        The receiver account.

      • name string

        The receiver account.

      • amount integer(int32)

        The amount of account allocation, in cent, cannot exceed the payment amount of the original order and the maximum proportion of account allocation

      • paymentMethod string

        Payment method, must be wechatpay or alipay

        Values are wechatpay or alipay.

      • description string

        The description of profit sharing.

      • receiverMchid string

        Merchant ID of receiver.

      • result string | null

        Profit sharing order result

        Values are PENDING, SUCCESS, REFUND, or CLOSED.

      • finishTime string

        The finish time of profit sharing with the rfc3339 standard format.

      • failReason string

        The failed reason of profit sharing.

        Values are ACCOUNT_ABNORMAL, NO_RELATION, or RECEIVER_HIGH_RISK.

      • detailId string

        Profit sharing detailed order number, which can be used for reconciliation with the fund bill.

  • • 400 object

    Request validation failure

  • • 401 object

    Not Authenticated.

  • • 500 object

    Something wrong when query the payout.

POST /settlement/receiver/{merchant} 
curl \
 -X POST https://nomad.samarkand-global.cn/broker/v1/settlement/receiver/wechat.sh_smk \
 -H "app-api-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"type":"MERCHANT_ID","account":"1900000109","name":"张三","relationType":"OTHERS","encryptedName":"hu89ohu89ohu89o","description":"网络公司","paymentMethod":"wechatpay"}'
Request example 
{
  "type": "MERCHANT_ID",
  "account": "1900000109",
  "name": "张三",
  "relationType": "OTHERS",
  "encryptedName": "hu89ohu89ohu89o",
  "description": "网络公司",
  "paymentMethod": "wechatpay"
}
Response example (200) 
{
  "code": 200,
  "message": "success",
  "type": "MERCHANT_ID",
  "account": "1900000109",
  "receivers": [
    {
      "type": "MERCHANT_ID",
      "receiverAccount": "1900000109",
      "name": "1900000109",
      "amount": 12,
      "paymentMethod": "wechatpay",
      "description": "分帐1900000110",
      "receiverMchid": "Orange",
      "result": "SUCCESS",
      "finishTime": "2015-05-20T13:29:35.120+08:00",
      "failReason": "NO_RELATION",
      "detailId": "3601111111111111111111"
    }
  ]
}
Response example (400) 
{
  "code": 200,
  "message": "success"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

DeleteSettlementReceiver

DELETE /settlement/receiver/{merchant}

Delete a settlement receiver

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. wechat.sh_smk

Query parameters

  • type string Required

    Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal.

    Values are MERCHANT_ID or PERSONAL_OPENID.

  • account string

    The receiver account.

  • payment_method string

    Must be wechatpay or alipay

    Values are wechatpay or alipay.

Responses

  • • 200 object

    Delete a profit receiver successfully.

    • code integer(int32)
    • message string | null

      Response message

    • type string | null

      Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal.

      Values are MERCHANT_ID or PERSONAL_OPENID.

    • account string | null

      The receiver account.

    • receivers array[object]
      • type string

        Receiver type of profit sharing. MERCHANT_ID: merchants, PERSONAL_OPENID: personal. PERSONAL_OPENID is not available

        Values are MERCHANT_ID or PERSONAL_OPENID.

      • receiverAccount string

        The receiver account.

      • name string

        The receiver account.

      • amount integer(int32)

        The amount of account allocation, in cent, cannot exceed the payment amount of the original order and the maximum proportion of account allocation

      • paymentMethod string

        Payment method, must be wechatpay or alipay

        Values are wechatpay or alipay.

      • description string

        The description of profit sharing.

      • receiverMchid string

        Merchant ID of receiver.

      • result string | null

        Profit sharing order result

        Values are PENDING, SUCCESS, REFUND, or CLOSED.

      • finishTime string

        The finish time of profit sharing with the rfc3339 standard format.

      • failReason string

        The failed reason of profit sharing.

        Values are ACCOUNT_ABNORMAL, NO_RELATION, or RECEIVER_HIGH_RISK.

      • detailId string

        Profit sharing detailed order number, which can be used for reconciliation with the fund bill.

  • • 400 object

    Request validation failure

  • • 401 object

    Not Authenticated.

  • • 500 object

    Something wrong when query the payout.

DELETE /settlement/receiver/{merchant} 
curl \
 -X DELETE https://nomad.samarkand-global.cn/broker/v1/settlement/receiver/wechat.sh_smk?type=MERCHANT_ID \
 -H "app-api-key: $API_KEY"
Response example (200) 
{
  "code": 200,
  "message": "success",
  "type": "MERCHANT_ID",
  "account": "1900000109",
  "receivers": [
    {
      "type": "MERCHANT_ID",
      "receiverAccount": "1900000109",
      "name": "1900000109",
      "amount": 12,
      "paymentMethod": "wechatpay",
      "description": "分帐1900000110",
      "receiverMchid": "Orange",
      "result": "SUCCESS",
      "finishTime": "2015-05-20T13:29:35.120+08:00",
      "failReason": "NO_RELATION",
      "detailId": "3601111111111111111111"
    }
  ]
}
Response example (400) 
{
  "code": 200,
  "message": "success"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

payout

Funds of merchant to oversea.

GetAbroadPayout

GET /payout/abroad/{merchant}

Merchant query payout order infomation

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. wechat.sh_smk

Query parameters

  • out_order_id string Required

    The payout number of the merchant, shall be generated by the merchant when initiating the payout request

  • transaction_id string Required

    Payment system internal order number

  • payment_method string

    Must be wechatpay or alipay

    Values are wechatpay or alipay.

Responses

  • • 200 object

    Query funds to abroad order successfully.

    • code integer(int32)
    • message string | null

      Response message

    • outOrderId string | null

      The payout number of the merchant, shall be generated by the merchant when initiating the payout request

    • transactionId string | null

      Payment company payout number

    • payoutOrderId string | null

      The payout number of the merchant, shall be generated by the merchant when initiating the payout request

    • result string | null

      Payout order result state

      Values are ACCEPT, SUCCESS, or FAIL.

    • failReason string | null

      Payout order failed reason. Request status that can be retried: BALANCE_NOT_ENOUGH

    • amount integer | null

      Amount of RMB to be payout, unit is cent

    • foreignAmount integer | null

      Foreign amount to be payout, minimum unit of money

    • foreignCurrency string | null

      Foreign currency of amount

    • rate integer | null

      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

    • exchangeRateTime string | null

      Exchange rate time，east 8 regional time

    • estimateExchangeRateTime string | null

      Estimate exchange rate time，east 8 regional time

    • availableAbroadAmount integer | null

      Available abroad amounts, unit is cent

  • • 400 object

    Request validation failure

  • • 401 object

    Not Authenticated.

  • • 500 object

    Something wrong when query the payout.

GET /payout/abroad/{merchant} 
curl \
 -X GET https://nomad.samarkand-global.cn/broker/v1/payout/abroad/wechat.sh_smk?out_order_id=string&transaction_id=string \
 -H "app-api-key: $API_KEY"
Response example (200) 
{
  "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
}
Response example (400) 
{
  "code": 200,
  "message": "success"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

PostAbroadPayout

POST /payout/abroad/{merchant}

Create a payout order

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. wechat.sh_smk

Body

Responses

  • • 200 object

    Create funds to abroad order successfully.

    • code integer(int32)
    • message string | null

      Response message

    • outOrderId string | null

      The payout number of the merchant, shall be generated by the merchant when initiating the payout request

    • transactionId string | null

      Payment company payout number

    • payoutOrderId string | null

      The payout number of the merchant, shall be generated by the merchant when initiating the payout request

    • result string | null

      Payout order result state

      Values are ACCEPT, SUCCESS, or FAIL.

    • failReason string | null

      Payout order failed reason. Request status that can be retried: BALANCE_NOT_ENOUGH

    • amount integer | null

      Amount of RMB to be payout, unit is cent

    • foreignAmount integer | null

      Foreign amount to be payout, minimum unit of money

    • foreignCurrency string | null

      Foreign currency of amount

    • rate integer | null

      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

    • exchangeRateTime string | null

      Exchange rate time，east 8 regional time

    • estimateExchangeRateTime string | null

      Estimate exchange rate time，east 8 regional time

    • availableAbroadAmount integer | null

      Available abroad amounts, unit is cent

  • • 400 object

    Request validation failure

  • • 401 object

    Not Authenticated.

  • • 500 object

    Something wrong when query the payout.

POST /payout/abroad/{merchant} 
curl \
 -X POST https://nomad.samarkand-global.cn/broker/v1/payout/abroad/wechat.sh_smk \
 -H "app-api-key: $API_KEY" \
 -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"}}'
Request example 
{
  "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"
  }
}
Response example (200) 
{
  "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
}
Response example (400) 
{
  "code": 200,
  "message": "success"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

GetAbroadPayoutBill

GET /payout/bill/abroad/{merchant}

Download the payout bill

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. wechat.sh_smk

Query parameters

  • bill_date string Required

    Bill date. Query format YYYY-MM-DD, for example, 2021-01-01

  • merchant_id string

    Merchant ID of merchant.

  • payment_method string

    Must be wechatpay or alipay

    Values are wechatpay or alipay.

Responses

  • • 200 string(binary)

    Download the payout bill successfully.

  • • 400 object

    Request validation failure

  • • 401 object

    Not Authenticated.

  • • 500 object

    Something wrong when download the payout bill.

GET /payout/bill/abroad/{merchant} 
curl \
 -X GET https://nomad.samarkand-global.cn/broker/v1/payout/bill/abroad/{merchant}?bill_date=string \
 -H "app-api-key: $API_KEY"
Response example (200) 
"@file"
Response example (400) 
{
  "code": 200,
  "message": "success"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success",
  "errors": "Something wrong when making the service."
}

PostAbroadPayoutBill

POST /payout/bill/abroad/{merchant}

Payout funds transactions operation

Path parameters

  • merchant string Required

    Merchant name to payment company, e.g. wechat.sh_smk

Body

  • operation string Required

    Abroad payout bill operations, available: GetAvailableAbroadAmounts

  • transactionId string Required

    Payment company transaction number

  • paymentMethod string

    Payment method, must be wechatpay or alipay

    Values are wechatpay or alipay.

Responses

  • • 200 object

    Payout funds transactions operation execute successfully.

    • code integer(int32)
    • message string | null

      Response message

    • outOrderId string | null

      The payout number of the merchant, shall be generated by the merchant when initiating the payout request

    • transactionId string | null

      Payment company payout number

    • payoutOrderId string | null

      The payout number of the merchant, shall be generated by the merchant when initiating the payout request

    • result string | null

      Payout order result state

      Values are ACCEPT, SUCCESS, or FAIL.

    • failReason string | null

      Payout order failed reason. Request status that can be retried: BALANCE_NOT_ENOUGH

    • amount integer | null

      Amount of RMB to be payout, unit is cent

    • foreignAmount integer | null

      Foreign amount to be payout, minimum unit of money

    • foreignCurrency string | null

      Foreign currency of amount

    • rate integer | null

      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

    • exchangeRateTime string | null

      Exchange rate time，east 8 regional time

    • estimateExchangeRateTime string | null

      Estimate exchange rate time，east 8 regional time

    • availableAbroadAmount integer | null

      Available abroad amounts, unit is cent

  • • 400 object

    Request validation failure

  • • 401 object

    Not Authenticated.

  • • 500 object

    Something wrong when download the payout bill.

POST /payout/bill/abroad/{merchant} 
curl \
 -X POST https://nomad.samarkand-global.cn/broker/v1/payout/bill/abroad/{merchant} \
 -H "app-api-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"operation":"GetAvailableAbroadAmounts","transactionId":"transaction_id_123","paymentMethod":"wechatpay"}'
Request example 
{
  "operation": "GetAvailableAbroadAmounts",
  "transactionId": "transaction_id_123",
  "paymentMethod": "wechatpay"
}
Response example (200) 
{
  "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
}
Response example (400) 
{
  "code": 200,
  "message": "success"
}
Response example (401) 
{
  "code": 200,
  "message": "success"
}
Response example (500) 
{
  "code": 200,
  "message": "success"
}