Nomad Broker

Make payments, do refunds, and customs declaration for orders.

This is the documentation for version 1.1.0 of the API. Last update on Oct 16, 2020.

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

Authentication

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

Declare

Declare an order to the customs

Authorization

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

    Succesful declaration application.

    • status string

      PROCCESSING, SUBMITTED, FAILED, SUCCESS

  • • 401 object

    Failure

    • errors string
  • • 422 object

    Request validation failure

    • field string
    • msg string
  • • 500 object

    Failure

    • errors string
POST /declare 
$ curl \
 -X POST https://nomad.samarkand-global.cn/broker/declare \
 -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 payload 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)
{
  "errors": "Not Authenticated."
}
Response example (422)
{
  "field": "reportId",
  "msg": "cannot be empty"
}
Response example (500)
{
  "errors": "Something wrong when making the payment."
}

Declare order

Declare an order after successful payment

Authorization

Declare an order after successful payment.

Body
  • initialRequest Required / string

    Initial request url to the payment provider

  • initialResponse Required / string

    Response got from the initial request

  • payCode Required / string

    Paycode of the payment provider

  • payTrxId Required / string

    Payment transaction ID from payment provider

  • totalAmount Required / number

    In RMB Yuan. Total amount of order.

  • tradingTime Required / string

    In YYYYMMDDHHMMSS format. Payment transaction time

  • orderNo Required / string

    Order ID used in payment customs declaration. This should be in the response of payment provider.

  • product array[object]

    Products of the order

    • id Required / string

      Product id

    • name Required / string

      Product name in Chinese

    • url Required / string

      Product url

  • recpAccount Required / string

    Bank account number for receiving the payment

  • recpName Required / string

    Bank account name for receiving the payment

Responses
  • • 200 object

    Succesful declaration application.

    • orderNo string

      Same orderNo as it in the request body

    • status string

      PROCCESSING, SUBMITTED, FAILED, SUCCESS

  • • 401 object

    Failure

    • errors string
  • • 422 object

    Request validation failure

    • field string
    • msg string
  • • 500 object

    Failure

    • errors string
POST /declare-order 
$ curl \
 -X POST https://nomad.samarkand-global.cn/broker/declare-order \
 -H "Content-Type: application/json" \
 -d '{"initialRequest":"https://pay.globepay.co/api/v1.0/wechat_jsapi_gateway/partners/F96FTB/orders/TEM1129354775085478274207817?time=1587033049529\u0026nonce_str=TEM1129354775085478274207817\u0026sign=cf78e7c81bd00717697c2b11577b48e66770504cb97d2a9b9621d1e99d8a9182","initialResponse":"{\"partner_order_id\":\"TEM1129354775085478274207817\",\"full_name\":\"Samarkand Global Limited\",\"partner_name\":\"SMK\",\"channel\":\"Wechat\",\"result_code\":\"SUCCESS\",\"partner_code\":\"F96FTB\",\"order_id\...}'
Request payload example 
{
  "initialRequest": "https://pay.globepay.co/api/v1.0/wechat_jsapi_gateway/partners/F96FTB/orders/TEM1129354775085478274207817?time=1587033049529&nonce_str=TEM1129354775085478274207817&sign=cf78e7c81bd00717697c2b11577b48e66770504cb97d2a9b9621d1e99d8a9182",
  "initialResponse": "{\"partner_order_id\":\"TEM1129354775085478274207817\",\"full_name\":\"Samarkand Global Limited\",\"partner_name\":\"SMK\",\"channel\":\"Wechat\",\"result_code\":\"SUCCESS\",\"partner_code\":\"F96FTB\",\"order_id\":\"0463920200416113050166181\",\"return_code\":\"SUCCESS\",\"pay_url\":\"https://pay.globepay.co/api/v1.0/wechat_jsapi_gateway/partners/F96FTB_order_TEM1129354775085478274207817\"}",
  "payCode": "4403169D3W",
  "payTrxId": 681765585945696378010,
  "totalAmount": 486.8,
  "tradingTime": 20200501112345,
  "orderNo": "0463920200416113050166181",
  "product": [
    {
      "id": "1",
      "name": "洗发水",
      "url": "https://myshop.com/everyday-hair-conditioner"
    }
  ],
  "recpAccount": 22210940,
  "recpName": "Samarkand Global Limited"
}
Response example (200)
{
  "orderNo": "0463920200416113050166181",
  "status": "SUCCESS"
}
Response example (401)
{
  "errors": "Not Authenticated."
}
Response example (422)
{
  "field": "initialRequest",
  "msg": "cannot be empty"
}
Response example (500)
{
  "errors": "Something wrong when making the declaration."
}

Declare an order after successful payment on youzan platform

Authorization

Declare an order after successful payment on youzan platform

Headers
  • X-Youzan-Token string
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

    • errors string
  • • 422 object

    Request validation failure

    • field string
    • msg string
  • • 500 object

    Failure

    • errors string
POST /declare-order/youzan 
$ curl \
 -X POST https://nomad.samarkand-global.cn/broker/declare-order/youzan \
 -H "Content-Type: application/json" \
 -H "X-Youzan-Token: string" \
 -d '{"amount":19300,"orderId":"E20200206101847089000001","subOrderId":"E202002061018470890000019610GZ","youzanTrxId":200206101849000125}'
Request payload example 
# Headers
X-Youzan-Token: string

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

Pay

Create a payment

Authorization

Create a payment

Body
  • paymentMethod Required / string

    Must be wechatpay or alipay

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

  • redirectUrl Required / string

    This url is redirected to once the payment completes

  • 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

    • errors string
  • • 422 object

    Request validation failure

    • field string
    • msg string
  • • 500 object

    Failure

    • errors string
POST /pay 
$ curl \
 -X POST https://nomad.samarkand-global.cn/broker/pay \
 -H "Content-Type: application/json" \
 -d '{"paymentMethod":"wechatpay","ref":"O123456789","total":2200,"currency":"CNY","orderSuccessUrl":"https://notify.order.success","redirectUrl":"https://show.order.success.page","product":[{"name":"Everyday Hair Conditioner","url":"https://myshop.com/everyday-hair-conditioner"}]}'
Request payload example 
{
  "paymentMethod": "wechatpay",
  "ref": "O123456789",
  "total": 2200,
  "currency": "CNY",
  "orderSuccessUrl": "https://notify.order.success",
  "redirectUrl": "https://show.order.success.page",
  "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": "ref",
  "msg": "cannot be empty"
}
Response example (500)
{
  "errors": "Something wrong when making the payment."
}

Query order

Query an order after the customs declaration

Authorization

Query an order after the customs declaration

Headers
  • X-Youzan-Token string
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

    • errors string
  • • 422 object

    Request validation failure

    • field string
    • msg string
  • • 500 object

    Failure

    • errors string
POST /query-order/youzan 
$ curl \
 -X POST https://nomad.samarkand-global.cn/broker/query-order/youzan \
 -H "Content-Type: application/json" \
 -H "X-Youzan-Token: string" \
 -d '{"orderId":"E20200206101847089000001","subOrderId":"E202002061018470890000019610GZ","youzanTrxId":"200206101849000125"}'
Request payload 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)
{
  "errors": "Not Authenticated."
}
Response example (422)
{
  "field": "orderId",
  "msg": "cannot be empty"
}
Response example (500)
{
  "errors": "Something wrong when making the declaration."
}

Refund

Refund a payment

Authorization

Refund a payment

Body
  • refundId Required / string

    ID used for refund

  • trxId Required / string

    Order transection ID from payment

  • amount Required / integer

    Refund amount, which uses the base unit of the currency and in the same currency as payment, and must be less than or equal to the actual paid amount

Responses
  • • 200 object

    Succesful refund application.

    • status string

      WAITING, SUCCESS, FAILED, FINISHED, MANUAL(refund cannot return to user's account, manual refund required)

  • • 401 object

    Failure

    • errors string
  • • 422 object

    Request validation failure

    • field string
    • msg string
  • • 500 object

    Failure

    • errors string
POST /refund 
$ curl \
 -X POST https://nomad.samarkand-global.cn/broker/refund \
 -H "Content-Type: application/json" \
 -d '{"refundId":"R0987654321","trxId":"TX1234567890","amount":2200}'
Request payload example 
{
  "refundId": "R0987654321",
  "trxId": "TX1234567890",
  "amount": 2200
}
Response example (200)
{
  "status": "SUCCESS"
}
Response example (401)
{
  "errors": "Not Authenticated."
}
Response example (422)
{
  "field": "refundId",
  "msg": "cannot be empty"
}
Response example (500)
{
  "errors": "Something wrong when making the payment."
}