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

Authentication

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

Declare

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

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

Pay

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

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