API version: Aug 01, 2022 04:42 am Back to last version

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.

Customs

GetCustomsPayment

GET /customs/payment/{merchant}

Merchant queries customs clearance information by order number

Path parameters
  • merchant Required / string

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

Query parameters
  • customs Required / string

    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

    • code integer(int32)
    • message string | null

      Response message

  • • 401 object

    Not Authenticated.

    • code integer(int32)
    • message string | null

      Response message

  • • 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 Required / string

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

Body
  • customs Required / string

    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 Required / string

    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

    • code integer(int32)
    • message string | null

      Response message

  • • 401 object

    Not Authenticated.

    • code integer(int32)
    • message string | null

      Response message

  • • 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 Required / string

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

Body
  • orderNo Required / 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 Required / string

    Transaction ID returned by Payment company

  • customs Required / string

    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

    • code integer(int32)
    • message string | null

      Response message

  • • 401 object

    Not Authenticated.

    • code integer(int32)
    • message string | null

      Response message

  • • 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 Required / string

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

Body
  • orderNo Required / 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 Required / string

    Transaction ID returned by Payment company

  • subOrderNo string

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

  • customs Required / string

    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 Required / string

    Only mainland ID cards are supported temporarily.

    Default value is IDCARD.

  • certId Required / string

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

  • certName Required / string

    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

    • code integer(int32)
    • message string | null

      Response message

  • • 401 object

    Not Authenticated.

    • code integer(int32)
    • message string | null

      Response message

  • • 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."
}

Payment

QueryPayment

GET /payment/{merchant}

Query a payment

Path parameters
  • merchant Required / string

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

Query parameters
  • order_ref Required / string

    Merchant order no.

  • payment_method string

    Must be wechatpay or alipay

    Values are wechatpay or alipay.

Responses
  • • 200 object

    Query a payment successfully.

    • code integer(int32)
    • message string | null

      Response message

    • orderRef string | null

      Merchant system order number

    • payerCurrency string | null

      Paymer amount currency

    • currency string | null

      Amount currency

    • payerTotal number | null

      Payer total amount, unit is fen

    • actualAmount integer | null

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

    • total number | null

      Total amount, unit is fen

    • bankType string | null

      Bank type

    • Timing string | null

      Payment time

    • transactionId string | null

      Transaction ID

    • tradeState string | null

      Trade state

    • tradeStateDesc string | null

      Trade state description

    • tradeType string | null

      Trade type

    • tradeMessage string | null

      Trade message of third payment providers.

  • • 401 object

    Not Authenticated.

    • code integer(int32)
    • message string | null

      Response message

  • • 500 object

    Something wrong when making the payment.

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 Required / string

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

Body
  • paymentMethod Required / string

    Payment method, must be wechatpay or alipay

    Values are wechatpay or alipay.

  • paymentType Required / string

    Payment companies have different payment types

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

  • orderRef Required / string

    Merchant system order number

  • actualAmount Required / integer

    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 Required / string

    Must be CNY or GBP

  • profitSharing boolean

    Whether the order is going to share profit

    Default value is true.

  • products array[object] | null

    All products data for current order, used when the order includes discounts

  • 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.

    • code integer(int32)
    • message string | null

      Response message

  • • 422 object

    Request validation failure

    • code integer(int32)
    • message string | null

      Response message

  • • 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 Required / string

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

  • order_ref Required / string

    Merchant order no.

Query parameters
  • payment_method string

    Must be wechatpay or alipay

    Values are wechatpay or alipay.

Responses
  • • 200 object

    Close a payment successfully.

  • • 401 object

    Not Authenticated.

    • code integer(int32)
    • message string | null

      Response message

  • • 422 object

    Request validation failure

    • code integer(int32)
    • message string | null

      Response message

  • • 500 object

    Something wrong when making the payment.

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 Required / string

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

Body
  • paymentMethod Required / string

    Payment method, must be wechatpay or alipay

    Values are wechatpay or alipay.

  • paymentType Required / string

    Payment companies have different payment types

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

  • payMessage Required / string

    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.

    • code integer(int32)
    • message string | null

      Response message

  • • 422 object

    Request validation failure

    • code integer(int32)
    • message string | null

      Response message

  • • 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."
}

Payout

GetAbroadPayout

GET /payout/abroad/{merchant}

Merchant query payout order infomation

Path parameters
  • merchant Required / string

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

Query parameters
  • out_order_id Required / string

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

  • transaction_id Required / string

    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

    • code integer(int32)
    • message string | null

      Response message

  • • 401 object

    Not Authenticated.

    • code integer(int32)
    • message string | null

      Response message

  • • 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 Required / string

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

Body
  • outOrderId string

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

  • transactionId string

    Payment company transaction number

  • paymentMethod string

    Payment method, must be wechatpay or alipay

    Values are wechatpay or alipay.

  • amount integer

    Amount of RMB to be payout, unit is cent

  • foreignCurrency string

    Currency of overseas payment. Note: The currency field is related to Payment company payee ID

  • goodsInfo array[object]

    Goods information, the number cannot exceed 10

    • goodsName Required / string

      Goods name.

    • goodsCategory string | null

      The merchant's own classification， for example, with/interval.

    • goodsUnitPrice Required / integer(int32)

      Goods unit price, unit is cent

    • goodsQuantity Required / integer(int32)

      Goods quantity

  • sellerInfo object
  • expressInfo object
  • payeeInfo object
    • payeeId string

      The payee ID assigned by Payment company when accessing the outbound service of Pay.

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

    • code integer(int32)
    • message string | null

      Response message

  • • 401 object

    Not Authenticated.

    • code integer(int32)
    • message string | null

      Response message

  • • 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 Required / string

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

Query parameters
  • bill_date Required / string

    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

    • code integer(int32)
    • message string | null

      Response message

  • • 401 object

    Not Authenticated.

    • code integer(int32)
    • message string | null

      Response message

  • • 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 Required / string

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

Body
  • operation Required / string

    Abroad payout bill operations, available: GetAvailableAbroadAmounts

  • transactionId Required / string

    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

    • code integer(int32)
    • message string | null

      Response message

  • • 401 object

    Not Authenticated.

    • code integer(int32)
    • message string | null

      Response message

  • • 500 object

    Something wrong when download the payout bill.

    • code integer(int32)
    • message string | null

      Response message

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"
}

Refund

QueryRefund

GET /refund/{merchant}

Query a refund

Path parameters
  • merchant Required / string

    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.

    • code integer(int32)
    • message string | null

      Response message

  • • 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 Required / string

    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 Required / string

    Merchant system order number

  • refundOrderRef Required / string

    Merchant refund order no

  • reason string

    Refund message to customer

  • refundAmount Required / number

    Refund amount, unit is fen

  • totalAmount Required / number

    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.

    • code integer(int32)
    • message string | null

      Response message

  • • 422 object

    Request validation failure

    • code integer(int32)
    • message string | null

      Response message

  • • 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

GetSettlement

GET /settlement/{merchant}

Merchant query settlement data.

Path parameters
  • merchant Required / string

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

Query parameters
  • profit_order_no Required / string

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

  • transaction_id Required / string

    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

    • code integer(int32)
    • message string | null

      Response message

  • • 401 object

    Not Authenticated.

    • code integer(int32)
    • message string | null

      Response message

  • • 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 Required / string

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

Body
  • orderRef Required / string

    Merchant system settlemnt order number

  • transactionId Required / string

    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

    • code integer(int32)
    • message string | null

      Response message

  • • 401 object

    Not Authenticated.

    • code integer(int32)
    • message string | null

      Response message

  • • 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 Required / string

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

Body
  • orderRef Required / string

    Merchant system settlemnt order number

  • transactionId Required / string

    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

    • code integer(int32)
    • message string | null

      Response message

  • • 401 object

    Not Authenticated.

    • code integer(int32)
    • message string | null

      Response message

  • • 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 Required / string

    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 Required / string

    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

    • code integer(int32)
    • message string | null

      Response message

  • • 401 object

    Not Authenticated.

    • code integer(int32)
    • message string | null

      Response message

  • • 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 Required / string

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

Query parameters
  • type Required / string

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

    Values are MERCHANT_ID or PERSONAL_OPENID.

  • account string

    The receiver account.