Version deployed on Mar 23, 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 Mar 23, 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 string

    ID used for refund

  • paymentMethod string

    Payment method of the order - wechatpay or alipay

  • trxId string

    Order transection ID from 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
curl \
 -X POST https://nomad.samarkand-global.cn/broker/declare \
 -H "Content-Type: application/json" \
 -d '{"reportId":"A0987654321","paymentMethod":"wechatpay","trxId":"TX1234567890"}'
Request example
{
  "reportId": "A0987654321",
  "paymentMethod": "wechatpay",
  "trxId": "TX1234567890"
}
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."
}

Create a payment

POST /pay

Create a payment

Body
  • paymentMethod string

    Must be wechatpay or alipay

  • ref string

    Order reference

  • total integer

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

  • currency string

    Must be CNY or GBP

  • This url is notified when the payment succeeds

  • redirectUrl string

    This url is redirected to once the payment completes

  • products array[object]
    • 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","products":[{"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",
  "products": [
    {
      "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 string

    ID used for refund

  • trxId string

    Order transection ID from payment

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