Nomad Broker

Make payments, and customs declaration for orders.

This is the documentation for version 1.3.5 of the API. Last update on Nov 16, 2021.

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

Authentication

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

PostCustoms

Declare an order to the customs

Body
  • reportId Required / string

    ID used for refund

  • paymentMethod Required / string

    Payment method of the order - wechatpay or alipay

  • trxId Required / string

    Order transection ID from payment

  • subOrder array[object]
    • subOrderRef string

      Sub order reference

    • product array[object]

      Products in this sub order

      • name string

        Product name

      • url string

        Product url

    • totalFee integer

      In CNY. Total amount of this sub order excluding logistics fee, which uses the base unit of the currency.

    • logsiticsFee integer

      In CNY. Logistics fee of this sub order, which uses the base unit of the currency.

Responses
  • • 200 object

    Redirect url for payment.

    • status string

      PROCCESSING, SUBMITTED, FAILED, SUCCESS

  • • 401 object

    Not Authenticated.

  • • 422 object

    Request validation failure

  • • 500 object

    Something wrong when declaring the payment.

POST /declare 
curl \
 -X POST https://nomad.samarkand-global.cn/broker/declare?app-api-key=api_token_value \
 -H "Content-Type: application/json" \
 -d '{"reportId":"A0987654321","paymentMethod":"wechatpay","trxId":"TX1234567890","subOrder":[{"subOrderRef":"O123456789S1","product":[{"name":"Everyday Hair Conditioner","url":"https://myshop.com/everyday-hair-conditioner"}],"totalFee":1050,"logsiticsFee":50}]}'
Request example 
{
  "reportId": "A0987654321",
  "paymentMethod": "wechatpay",
  "trxId": "TX1234567890",
  "subOrder": [
    {
      "subOrderRef": "O123456789S1",
      "product": [
        {
          "name": "Everyday Hair Conditioner",
          "url": "https://myshop.com/everyday-hair-conditioner"
        }
      ],
      "totalFee": 1050,
      "logsiticsFee": 50
    }
  ]
}
Response example (200)
{
  "status": "SUCCESS"
}
Response example (401)
{
  "field": "orderRef",
  "msg": "cannot be empty"
}
Response example (422)
{
  "field": "orderRef",
  "msg": "cannot be empty"
}
Response example (500)
{
  "errors": "Something wrong when making the service."
}

Declare an order after successful payment on youzan platform

Declare an order after successful payment on youzan platform

Headers
Body
  • amount Required / number

    In RMB fen. Total amount of order

  • orderId Required / string

    Order ID

  • subOrderId string

    Sub order ID (optional)

  • youzanTrxId Required / string

    Payment transaction number from youzan payment response

Responses
  • • 200 object

    Successfully submitted the customs declaration.

    • storeId Required / number

      Youzan store ID

    • subOrderId string

      Sub order ID (if subOrderId is included in request)

    • customsStatus Required / number

      Status code from customs (1. processing, 2. successful, 3. failed, 4. rejected by customs, 5. in customs warehouse, 6. something wrong, please try again)

    • paymentCustomsId Required / string

      Customs declaration ID of the payment

    • orderId Required / string

      Order ID

    • youzanTrxId Required / string

      Payment transaction number from youzan payment response

  • • 401 object

    Failure

  • • 422 object

    Request validation failure

  • • 500 object

    Failure

POST /declare-order/youzan 
curl \
 -X POST https://nomad.samarkand-global.cn/broker/declare-order/youzan?app-api-key=api_token_value \
 -H "Content-Type: application/json" \
 -H "X-Youzan-Token: string" \
 -d '{"amount":19300,"orderId":"E20200206101847089000001","subOrderId":"E202002061018470890000019610GZ","youzanTrxId":200206101849000130}'
Request example 
# Headers
X-Youzan-Token: string

# Payload
{
  "amount": 19300,
  "orderId": "E20200206101847089000001",
  "subOrderId": "E202002061018470890000019610GZ",
  "youzanTrxId": 200206101849000130
}
Response example (200)
{
  "storeId": 41261615,
  "subOrderId": "E202002061018470890000019610GZ",
  "customsStatus": 2,
  "paymentCustomsId": "200206101849000125961003",
  "orderId": "E20200206101847089000001",
  "youzanTrxId": "200206101849000125"
}
Response example (401)
{
  "field": "orderRef",
  "msg": "cannot be empty"
}
Response example (422)
{
  "field": "orderRef",
  "msg": "cannot be empty"
}
Response example (500)
{
  "errors": "Something wrong when making the service."
}

Pay

Create a payment

Create a payment

Body
  • paymentMethod Required / string

    Must be wechatpay or alipay

  • orderRef Required / string

    Order reference

  • total Required / integer

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

  • currency Required / string

    Must be CNY or GBP

  • orderSuccessUrl Required / string

    This url is notified when the payment succeeds

  • product array[object]

    All products in this order

    • name string

      Product name

    • url string

      Product url

Responses
  • • 200 object

    Redirect url for payment.

    • payUrl string

      Url to the payment page

    • trxId string

      Url to the payment page

  • • 401 object

    Failure

  • • 422 object

    Request validation failure

  • • 500 object

    Failure

POST /pay 
curl \
 -X POST https://nomad.samarkand-global.cn/broker/pay?app-api-key=api_token_value \
 -H "Content-Type: application/json" \
 -d '{"paymentMethod":"wechatpay","orderRef":"O123456789","total":2200,"currency":"CNY","orderSuccessUrl":"https://notify.order.success","product":[{"name":"Everyday Hair Conditioner","url":"https://myshop.com/everyday-hair-conditioner"}]}'
Request example 
{
  "paymentMethod": "wechatpay",
  "orderRef": "O123456789",
  "total": 2200,
  "currency": "CNY",
  "orderSuccessUrl": "https://notify.order.success",
  "product": [
    {
      "name": "Everyday Hair Conditioner",
      "url": "https://myshop.com/everyday-hair-conditioner"
    }
  ]
}
Response example (200)
{
  "payUrl": "https://payment.page.for.the.order",
  "trxId": "TX1234567890"
}
Response example (401)
{
  "errors": "Not Authenticated."
}
Response example (422)
{
  "field": "orderRef",
  "msg": "cannot be empty"
}
Response example (500)
{
  "errors": "Something wrong when making the payment."
}

CreatePayment

Create 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 and alipay.

  • paymentType Required / string

    Payment companies have different payment types

    Values are NATIVE, H5, and JSAPI.

  • orderRef Required / string

    Order reference

  • total Required / integer

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

  • currency Required / string

    Must be CNY or GBP

  • orderSuccessUrl Required / string

    This url is notified when the payment succeeds

  • product array[object]

    All products in this order

    • name string

      Product name

    • url string

      Product url

  • description string

    Product description

Responses
  • • 200 object

    Redirect url for payment.

    • code integer(int32)
    • message string

      Response message

    • prePayUrl string

      Url to the payment page

    • payUrl string

      Url need to be accessd in mobile phone browser

    • payPage string

      Pay page html source code

  • • 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/payment/wechat.test?app-api-key=api_token_value \
 -H "Content-Type: application/json" \
 -d '{"paymentMethod":"wechatpay","paymentType":"H5","orderRef":"O123456789","total":2200,"currency":"CNY","orderSuccessUrl":"https://notify.order.success","product":[{"name":"Everyday Hair Conditioner","url":"https://myshop.com/everyday-hair-conditioner"}],"description":"面膜 mask"}'
Request example 
{
  "paymentMethod": "wechatpay",
  "paymentType": "H5",
  "orderRef": "O123456789",
  "total": 2200,
  "currency": "CNY",
  "orderSuccessUrl": "https://notify.order.success",
  "product": [
    {
      "name": "Everyday Hair Conditioner",
      "url": "https://myshop.com/everyday-hair-conditioner"
    }
  ],
  "description": "面膜 mask"
}
Response example (200)
{
  "code": 200,
  "message": "success",
  "prePayUrl": "https://payment.page.for.the.order",
  "payUrl": "weixin://wap/pay?prepayid%3Dwx27132822987960ddbf8532d86857e50000&package=1570653087&noncestr=1635312518&sign=356e4d9aec18f77f9084af1295bc255e",
  "payPage": "string"
}
Response example (401)
{
  "field": "orderRef",
  "msg": "cannot be empty"
}
Response example (422)
{
  "field": "orderRef",
  "msg": "cannot be empty"
}
Response example (500)
{
  "errors": "Something wrong when making the service."
}

QueryPayment

Query a payment

Path parameters
  • merchant Required / string

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

  • order_ref Required / string

    Merchant order no.

Responses
GET /payment/query/{merchant}/{order_ref} 
curl \
 -X GET https://nomad.samarkand-global.cn/broker/payment/query/wechat.test/test202101?app-api-key=api_token_value
Response example (200)
{
  "code": 200,
  "message": "success",
  "orderRef": "test202103",
  "payerCurrency": "CNY",
  "currency": "CNY",
  "payerTotal": 10,
  "total": 10,
  "bankType": "string",
  "Timing": "2021-11-02T17:03:38+08:00",
  "transactionId": "4200001148202111020556019250",
  "tradeState": "SUCCESS",
  "tradeStateDesc": "支付成功",
  "tradeType": "MWEB"
}
Response example (401)
{
  "field": "orderRef",
  "msg": "cannot be empty"
}
Response example (500)
{
  "errors": "Something wrong when making the service."
}

ClosePayment

Close a payment

Path parameters
  • merchant Required / string

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

  • order_ref Required / string

    Merchant order no.

Responses
  • • 200 object

    Redirect url for payment.

  • • 401 object

    Not Authenticated.

  • • 422 object

    Request validation failure

  • • 500 object

    Something wrong when making the payment.

POST /payment/close/{merchant}/{order_ref} 
curl \
 -X POST https://nomad.samarkand-global.cn/broker/payment/close/wechat.test/wechat.test?app-api-key=api_token_value
Response example (200)
{
  "code": 200,
  "message": "success",
  "paymentMessage": "success"
}
Response example (401)
{
  "field": "orderRef",
  "msg": "cannot be empty"
}
Response example (422)
{
  "field": "orderRef",
  "msg": "cannot be empty"
}
Response example (500)
{
  "errors": "Something wrong when making the service."
}

InvokePayment

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 and alipay.

  • paymentType Required / string

    Payment companies have different payment types

    Values are NATIVE, H5, and JSAPI.

  • invocationUrl Required / string

    This url is notified when the payment succeeds

Responses
  • • 200 object

    Redirect url for payment.

    • code integer(int32)
    • message string

      Response message

    • prePayUrl string

      Url to the payment page

    • payUrl string

      Url need to be accessd in mobile phone browser

    • payPage string

      Pay page html source code

  • • 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/payment/invocation/wechat.test?app-api-key=api_token_value \
 -H "Content-Type: application/json" \
 -d '{"paymentMethod":"wechatpay","paymentType":"H5","invocationUrl":"https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx2711083228719406a31dfe004d2b0c0000\u0026package=3754039013"}'
Request example 
{
  "paymentMethod": "wechatpay",
  "paymentType": "H5",
  "invocationUrl": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx2711083228719406a31dfe004d2b0c0000&package=3754039013"
}
Response example (200)
{
  "code": 200,
  "message": "success",
  "prePayUrl": "https://payment.page.for.the.order",
  "payUrl": "weixin://wap/pay?prepayid%3Dwx27132822987960ddbf8532d86857e50000&package=1570653087&noncestr=1635312518&sign=356e4d9aec18f77f9084af1295bc255e",
  "payPage": "string"
}
Response example (401)
{
  "field": "orderRef",
  "msg": "cannot be empty"
}
Response example (422)
{
  "field": "orderRef",
  "msg": "cannot be empty"
}
Response example (500)
{
  "errors": "Something wrong when making the service."
}

Query an order after the customs declaration

Query an order after the customs declaration

Headers
Body
  • orderId Required / string

    Order ID

  • subOrderId string

    Sub order ID (optional)

  • youzanTrxId Required / string

    Payment transaction number from youzan payment response

Responses
  • • 200 object

    Successfully submitted the customs declaration.

    • subOrderId string

      Sub order ID (if subOrderId is included in request)

    • customsStatus Required / number

      Status code from customs (1. processing, 2. successful, 3. failed, 4. rejected by customs, 5. in customs warehouse, 6. something wrong, please try again)

    • customsMsg Required / string

      Message from customs in Chinese

    • customsUpdatedTime Required / number

      Time in ms. Last updated time from customs.

    • paymentCustomsId Required / string

      Customs declaration ID of the payment

    • orderId Required / string

      Order ID

    • youzanTrxId Required / string

      Payment transaction number from youzan payment response

  • • 401 object

    Failure

  • • 422 object

    Request validation failure

  • • 500 object

    Failure

POST /query-order/youzan 
curl \
 -X POST https://nomad.samarkand-global.cn/broker/query-order/youzan?app-api-key=api_token_value \
 -H "Content-Type: application/json" \
 -H "X-Youzan-Token: string" \
 -d '{"orderId":"E20200206101847089000001","subOrderId":"E202002061018470890000019610GZ","youzanTrxId":"200206101849000125"}'
Request example 
# Headers
X-Youzan-Token: string

# Payload
{
  "orderId": "E20200206101847089000001",
  "subOrderId": "E202002061018470890000019610GZ",
  "youzanTrxId": "200206101849000125"
}
Response example (200)
{
  "subOrderId": "E202002061018470890000019610GZ",
  "customsStatus": 2,
  "customsMsg": "发送海关成功",
  "customsUpdatedTime": 1596542760000,
  "paymentCustomsId": "200206101849000125961003",
  "orderId": "E20200206101847089000001",
  "youzanTrxId": "200206101849000125"
}
Response example (401)
{
  "field": "orderRef",
  "msg": "cannot be empty"
}
Response example (422)
{
  "field": "orderRef",
  "msg": "cannot be empty"
}
Response example (500)
{
  "errors": "Something wrong when making the service."
}