This is the API descriptor for the Nomad Checkout API. Read the documentation online at Nomad API Suite.

  • Install for node with npm install nomad-checkout-cli - Install for python with pip install nomad-checkout-cli - Install for Maven users groupId, com.gitlab.samarkand-nomad; artifactId, nomad-checkout-cli

This is the documentation for version x.x.x of the API. Last update on Aug 12, 2021.

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

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


New cart

New cart

Path parameters
  • platform Required / string

    Source platform

    Values are shopify, commerce, woocommerce, magento, bigcommerce, and squarespace.

  • merchantId Required / string

    Globally unique id for merchant

Body
  • merchantSiteUrl Required / string

    Full url to merchant store

  • cart Required / object

    Cart data (platform specific)

  • subdomain boolean

    Whether merchant site url is a platform subdomain

    Default value is true.

Responses
  • 200 object

    Cart created successfully

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

      • exchangeRate number

        Exchange rate used for GBP to CNY conversion

  • 400 object

    Invalid message

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

      • exchangeRate number

        Exchange rate used for GBP to CNY conversion

  • 500 object

    Cart creation failed

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

      • exchangeRate number

        Exchange rate used for GBP to CNY conversion

POST /carts/{platform}/{merchantId}
curl \
 -X POST https://nomad.samarkand-global.cn/checkout/carts/{platform}/SMK474 \
 -H "x-ca-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"merchantSiteUrl":"https://smktestpartner.myshopify.com/cart","cart":{},"subdomain":false}'
Request example
{
  "merchantSiteUrl": "https://smktestpartner.myshopify.com/cart",
  "cart": {},
  "subdomain": false
}
Response example (200)
{
  "code": 42,
  "message": "Status of operation",
  "data": {
    "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
    "exchangeRate": 9.1
  }
}
Response example (400)
{
  "code": 42,
  "message": "Status of operation",
  "data": {
    "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
    "exchangeRate": 9.1
  }
}
Response example (500)
{
  "code": 42,
  "message": "Status of operation",
  "data": {
    "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
    "exchangeRate": 9.1
  }
}

New enterprise cart

New enterprise cart

Path parameters
  • merchantId Required / string

    Globally unique id for merchant

  • enterpriseId Required / string

    Issued unique enterprised ID

Body
Responses
  • 200 object

    Cart created successfully

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

      • exchangeRate number

        Exchange rate used for GBP to CNY conversion

  • 400 object

    Invalid message

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

      • exchangeRate number

        Exchange rate used for GBP to CNY conversion

  • 500 object

    Cart creation failed

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

      • exchangeRate number

        Exchange rate used for GBP to CNY conversion

POST /carts/enterprise/{enterpriseId}/merchants/{merchantId}
curl \
 -X POST https://nomad.samarkand-global.cn/checkout/carts/enterprise/REC890/merchants/SMK474 \
 -H "x-ca-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"cancelUrl":"https://smktestpartner.myshopify.com/cancel","cart":{"user":{"platformUserId":"12345","payer":{"nationalId":"120103198806018241","name":"王小明","phoneNumber":"13887342813"},"shippingAddress":{"receiver":{"name":"王小明","phoneNumber":"13887342813"},"streetAddress":"天钥桥路333号腾飞大厦3楼438室","district":"徐汇区","province":"上海市","city":"市辖区","country":"中国","postcode":"200030"}},"paymentType":"alipay","products":[{"productId":"123456","skuNumber":"SMK123","barcode":"1234567890","quantity":1,"pr...}'
Request example
{
  "cancelUrl": "https://smktestpartner.myshopify.com/cancel",
  "cart": {
    "user": {
      "platformUserId": "12345",
      "payer": {
        "nationalId": "120103198806018241",
        "name": "王小明",
        "phoneNumber": "13887342813"
      },
      "shippingAddress": {
        "receiver": {
          "name": "王小明",
          "phoneNumber": "13887342813"
        },
        "streetAddress": "天钥桥路333号腾飞大厦3楼438室",
        "district": "徐汇区",
        "province": "上海市",
        "city": "市辖区",
        "country": "中国",
        "postcode": "200030"
      }
    },
    "paymentType": "alipay",
    "products": [
      {
        "productId": "123456",
        "skuNumber": "SMK123",
        "barcode": "1234567890",
        "quantity": 1,
        "priceBeforeTax": 10,
        "discount": 0,
        "taxRate": "9.1,",
        "imageUrl": "https://mydomain.com/image.png"
      }
    ],
    "totalPriceBeforeShippingTaxAndDiscount": 10,
    "currency": "CNY",
    "tax": 0.91,
    "shipping": 20.2,
    "discount": 30.3,
    "totalToPay": 9
  }
}
Response example (200)
{
  "code": 42,
  "message": "Status of operation",
  "data": {
    "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
    "exchangeRate": 9.1
  }
}
Response example (400)
{
  "code": 42,
  "message": "Status of operation",
  "data": {
    "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
    "exchangeRate": 9.1
  }
}
Response example (500)
{
  "code": 42,
  "message": "Status of operation",
  "data": {
    "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
    "exchangeRate": 9.1
  }
}

Update enterprise cart

Update enterprise cart

Path parameters
  • cartId Required / string

    Globally unique id for cart

  • enterpriseId Required / string

    Issued unique enterprised ID

Body
  • paymentUrl Required / string

    URL for user to make payment

Responses
  • 200 object

    Cart updated successfully

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

      • exchangeRate number

        Exchange rate used for GBP to CNY conversion

  • 400 object

    Invalid message

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

      • exchangeRate number

        Exchange rate used for GBP to CNY conversion

  • 500 object

    Cart update failed

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

      • exchangeRate number

        Exchange rate used for GBP to CNY conversion

PUT /carts/{cartId}/enterprise/{enterpriseId}
curl \
 -X PUT https://nomad.samarkand-global.cn/checkout/carts/DJTHX555202105071817lMEIYK9610GZ/enterprise/REC890 \
 -H "x-ca-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"paymentUrl":"https://pay.globepay.co/api/v1.0/h5_payment/partners/123/orders/1OE456"}'
Request example
{
  "paymentUrl": "https://pay.globepay.co/api/v1.0/h5_payment/partners/123/orders/1OE456"
}
Response example (200)
{
  "code": 42,
  "message": "Status of operation",
  "data": {
    "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
    "exchangeRate": 9.1
  }
}
Response example (400)
{
  "code": 42,
  "message": "Status of operation",
  "data": {
    "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
    "exchangeRate": 9.1
  }
}
Response example (500)
{
  "code": 42,
  "message": "Status of operation",
  "data": {
    "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
    "exchangeRate": 9.1
  }
}

Called when cart is ready for payment

Called when cart is ready for payment

Path parameters
Responses
  • 301

    Redirects to shipping form page

GET /carts/{cartId}/enterprise/{enterpriseId}/pay
curl \
 -X GET https://nomad.samarkand-global.cn/checkout/carts/DJTHX555202105071817lMEIYK9610GZ/enterprise/REC890/pay \
 -H "x-ca-key: $API_KEY"

Path parameters
  • enterpriseId Required / string

    Issued unique enterprised ID

Body
  • cartId Required / string

    SMK cart ID

  • status Required / string

    Status of the declaration from the response from the customs

  • payTransactionId Required / string

    Payment transaction serial number (pay_transaction_id from Alipay customs declaration response, verify_department_trade_id from WechatPay customs declaration response)

Responses
  • 200 object

    Payment status received successfully

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

      • exchangeRate number

        Exchange rate used for GBP to CNY conversion

  • 400 object

    Invalid message

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

      • exchangeRate number

        Exchange rate used for GBP to CNY conversion

  • 409

    Payment status already updated for this cart

  • 500 object

    Payment status update failed

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

      • exchangeRate number

        Exchange rate used for GBP to CNY conversion

POST /declarations/enterprise/{enterpriseId}
curl \
 -X POST https://nomad.samarkand-global.cn/checkout/declarations/enterprise/REC890 \
 -H "x-ca-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"cartId":"DJPRO8732021031600441234567899610GZ","status":"SUBMITTED","payTransactionId":"2018112288340107038204310100000"}'
Request example
{
  "cartId": "DJPRO8732021031600441234567899610GZ",
  "status": "SUBMITTED",
  "payTransactionId": "2018112288340107038204310100000"
}
Response example (200)
{
  "code": 42,
  "message": "Status of operation",
  "data": {
    "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
    "exchangeRate": 9.1
  }
}
Response example (400)
{
  "code": 42,
  "message": "Status of operation",
  "data": {
    "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
    "exchangeRate": 9.1
  }
}
Response example (500)
{
  "code": 42,
  "message": "Status of operation",
  "data": {
    "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
    "exchangeRate": 9.1
  }
}

Path parameters
  • enterpriseId Required / string

    Issued unique enterprised ID

Body
  • cartId Required / string

    Globally unique cart id

  • enterpriseOrderId Required / string

    THG internal order ID

  • initialRequest Required / string

    Initial request url to Alipay/WechatPay, for customs's reference

  • initialResponse Required / string

    Initial response url from Alipay/WechatPay, for customs's reference

  • paymentPayId Required / string

    WechatPay/Alipay order ID

  • paidAt Required / string

    Payment time in ISO_8601 format

  • status Required / string

    Status of payment operation

    Values are success and failed.

  • failReason string

    Reason for failure

Responses
  • 200 object

    Payment status received successfully

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

      • exchangeRate number

        Exchange rate used for GBP to CNY conversion

  • 400 object

    Invalid message

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

      • exchangeRate number

        Exchange rate used for GBP to CNY conversion

  • 409

    Payment status already updated for this cart

  • 500 object

    Payment status update failed

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

      • exchangeRate number

        Exchange rate used for GBP to CNY conversion

POST /payment/complete/enterprise/{enterpriseId}
curl \
 -X POST https://nomad.samarkand-global.cn/checkout/payment/complete/enterprise/REC890 \
 -H "x-ca-key: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"cartId":"string","enterpriseOrderId":"string","initialRequest":"https://pay.co/api/v1.0/wechat_jsapi_gateway/partners/F96FTB/orders/TEM1129354775085478274207817?time=1587033049529\u0026nonce_str=TEM1129354775085478274207817\u0026sign=cf78e7c81bd00717697c2b11577b48e66770504cb97d2a9b9621d1e99d8a9182","initialResponse":"https://pay.co/api/v1.0/wechat_jsapi_gateway/partners/F96FTB/response=1587033049529\u0026nonce_str=TEM1129354775085478274207817\u0026sign=cf78e7c81bd00717697c2b11577b48e667705...}'
Request example
{
  "cartId": "string",
  "enterpriseOrderId": "string",
  "initialRequest": "https://pay.co/api/v1.0/wechat_jsapi_gateway/partners/F96FTB/orders/TEM1129354775085478274207817?time=1587033049529&nonce_str=TEM1129354775085478274207817&sign=cf78e7c81bd00717697c2b11577b48e66770504cb97d2a9b9621d1e99d8a9182",
  "initialResponse": "https://pay.co/api/v1.0/wechat_jsapi_gateway/partners/F96FTB/response=1587033049529&nonce_str=TEM1129354775085478274207817&sign=cf78e7c81bd00717697c2b11577b48e66770504cb97d2a9b9621d1e99d8a9182",
  "paymentPayId": "string",
  "paidAt": "2021-04-26T11:57:18Z",
  "status": "success",
  "failReason": "Invalid payment detail provided"
}
Response example (200)
{
  "code": 42,
  "message": "Status of operation",
  "data": {
    "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
    "exchangeRate": 9.1
  }
}
Response example (400)
{
  "code": 42,
  "message": "Status of operation",
  "data": {
    "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
    "exchangeRate": 9.1
  }
}
Response example (500)
{
  "code": 42,
  "message": "Status of operation",
  "data": {
    "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
    "exchangeRate": 9.1
  }
}