Version deployed on May 20, 2020. Back to the latest version

Nomad Broker

1.0.0

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

This is the documentation for version 1.0.0 of the API. Last update on May 20, 2020.

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

Send an authentication token in the x-ca-key header to authenticate with the API.


Declare an order to the customs

POST /declare

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, SUBMITED, FAILED, SUCCESS

  • 401 object

    Failure

  • 422 object

    Request validation failure

  • 500 object

    Failure

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 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 an order after successful payment

POST /declare-order

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 Required / array[object]

    Products of the order

    • name string

      Product name

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

    • status string

      PROCCESSING, SUBMITED, FAILED, SUCCESS

  • 401 object

    Failure

  • 422 object

    Request validation failure

  • 500 object

    Failure

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 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": [
    {
      "name": "Everyday Hair Conditioner",
      "url": "https://myshop.com/everyday-hair-conditioner"
    }
  ],
  "recpAccount": 22210940,
  "recpName": "Samarkand Global Limited"
}
Response example (200)
{
  "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."
}

Create a payment

POST /pay

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 Required / 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 \
 -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 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."
}

Refund a payment

POST /refund

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

  • 422 object

    Request validation failure

  • 500 object

    Failure

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