Nomad Checkout

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

Authentication

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


Carts

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 "Content-Type: application/json" \
 -d '{"merchantSiteUrl":"https://smktestpartner.myshopify.com/cart","cart":{},"subdomain":false}'
Request payload 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
  • cancelUrl Required / string

    URL to navigate to if user cancels checkout

  • cart Required / object

    Enterprise cart

    • user object
      • platformUserId string

        Source platform globally unique user Id

      • payer object
        • nationalId string

          Globally unique China National Id

        • name string

          name

        • phoneNumber string

          Phone number

      • shippingAddress object

        Shipping address

        • receiver object

          Receiver details

          • name string

            Fullname

          • phoneNumber string

            Phone number

        • streetAddress string

          Street Address

        • district string

          District

        • province string

          Province

        • city string

          City

        • country string

          Country

        • postcode string

          Postcode

    • paymentType string

      Values are alipay and wechatpay.

    • products array[object]

      Cart products

      • productId string

        Globally unique product Id

      • skuNumber string

        Globally unique stock keeping unit (sku) number

      • barcode string

        Globally unique barcode number

      • quantity number

        Quantity

      • priceBeforeTax number

        Price before tax

      • discount number

        Product discount

      • taxRate number

        China customs rate

      • imageUrl string

        Public image URL

    • totalPriceBeforeShippingTaxAndDiscount number

      Total price before shipping tax and discount. (Note: this is not allowed to be greater than 5,000 RMB by CBEC rules.)

    • currency string

      ISO-4217 code

      Values are CNY and GBP.

    • tax number

      China tax amount

    • shipping number

      Delivery charge

    • discount number

      Any non-product discounts

    • totalToPay number

      Total to pay

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 "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 payload 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 "Content-Type: application/json" \
 -d '{"paymentUrl":"https://pay.globepay.co/api/v1.0/h5_payment/partners/123/orders/1OE456"}'
Request payload 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
  • cartId Required / string
  • enterpriseId Required / string

    Issued unique enterprised ID

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

Declarations

POST /declarations/enterprise/{enterpriseId}

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 "Content-Type: application/json" \
 -d '{"cartId":"DJPRO8732021031600441234567899610GZ","status":"SUBMITTED","payTransactionId":"2018112288340107038204310100000"}'
Request payload 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
  }
}

Payment

POST /payment/complete/enterprise/{enterpriseId}

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