Nomad Checkout
x.x.x

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

Ca key (http_api_key)

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

carts

Handle user shopping baskets

New cart

POST /carts/{platform}/{merchantId}

New cart

Path parameters

  • platform string Required

    Source platform

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

  • merchantId string Required

    Globally unique id for merchant

Body

Create new cart details

Responses

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":{"currency":"GBP","item_count":5,"items":[{"id":36801771733142,"quantity":2,"variant_id":14808998805549,"key":"14808998805549:7d7c76c0a1dd684c158ea58cf28a5062","title":"Probio7 50 Plus","price":2349,"sku":"PB50","grams":27,"product_title":"Probio7 50 Plus","properties":{"shipping_interval_unit_type":"Months","shipping_interval_frequency":"1"},"image":"https://cdn.shopify.com/s/files/1/0024/2240/7213/products/ORIG_plain_73cf94a5-7732-4457-a32a-449b537c4598.png?v=1587802551","vendor":"Probio7"}],"total_price":6355,"total_weight":99.2155},"subdomain":false}'
Request example 
{
  "merchantSiteUrl": "https://smktestpartner.myshopify.com/cart",
  "cart": {
    "currency": "GBP",
    "item_count": 5,
    "items": [
      {
        "id": 36801771733142,
        "quantity": 2,
        "variant_id": 14808998805549,
        "key": "14808998805549:7d7c76c0a1dd684c158ea58cf28a5062",
        "title": "Probio7 50 Plus",
        "price": 2349,
        "sku": "PB50",
        "grams": 27,
        "product_title": "Probio7 50 Plus",
        "properties": {
          "shipping_interval_unit_type": "Months",
          "shipping_interval_frequency": "1"
        },
        "image": "https://cdn.shopify.com/s/files/1/0024/2240/7213/products/ORIG_plain_73cf94a5-7732-4457-a32a-449b537c4598.png?v=1587802551",
        "vendor": "Probio7"
      }
    ],
    "total_price": 6355,
    "total_weight": 99.2155
  },
  "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

POST /carts/enterprise/{enterpriseId}/merchants/{merchantId}

New enterprise cart

Path parameters

Body

Create new cart details

  • cancelUrl string Required

    URL to navigate to if user cancels checkout

  • cart object Required

    Enterprise cart

    • user object
      • platformUserId string

        Source platform globally unique user Id

      • payer object
        • nationalId string

          Globally unique China National Id

        • name string

          name

          Format should match the following pattern: ^[^\s][\u2E80-\u2FD5\u3190-\u319f\u3400-\u4DBF\u4E00-\u9FCC\uF900-\uFAAD ]*$.

        • phoneNumber string

          Phone number

      • shippingAddress object

        Shipping address

        • receiver object

          Receiver details

          • name string

            Fullname

            Format should match the following pattern: ^[^\s][\u2E80-\u2FD5\u3190-\u319f\u3400-\u4DBF\u4E00-\u9FCC\uF900-\uFAAD ]*$.

          • phoneNumber string

            Phone number

        • streetAddress string

          Street Address

          Format should match the following pattern: ^[^\s][a-zA-Z0-9\u2E80-\u2FD5\u3190-\u319f\u3400-\u4DBF\u4E00-\u9FCC\uF900-\uFAAD ]*$.

        • district string

          District

          Format should match the following pattern: ^[^\s][\u2E80-\u2FD5\u3190-\u319f\u3400-\u4DBF\u4E00-\u9FCC\uF900-\uFAAD ]*$.

        • province string

          Province

          Format should match the following pattern: ^[^\s][\u2E80-\u2FD5\u3190-\u319f\u3400-\u4DBF\u4E00-\u9FCC\uF900-\uFAAD ]*$.

        • city string

          City

          Format should match the following pattern: ^[^\s][\u2E80-\u2FD5\u3190-\u319f\u3400-\u4DBF\u4E00-\u9FCC\uF900-\uFAAD ]*$.

        • country string

          Country

          Format should match the following pattern: ^[^\s][\u2E80-\u2FD5\u3190-\u319f\u3400-\u4DBF\u4E00-\u9FCC\uF900-\uFAAD ]*$.

        • postcode string

          Postcode

    • paymentType string

      Values are alipay or wechatpay.

    • products array[object]

      Cart products

    • 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 or GBP.

    • tax number

      China tax amount

    • shipping number

      Delivery charge

    • discount number

      Any non-product discounts

    • totalToPay number

      Total to pay

Responses

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,"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}}'
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

PUT /carts/{cartId}/enterprise/{enterpriseId}

Update enterprise cart

Path parameters

  • cartId string Required

    Globally unique id for cart

  • enterpriseId string Required

    Issued unique enterprised ID

Body

Update cart details

Responses

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

payment

Receive payment status

Called when cart is ready for payment

GET /carts/{cartId}/enterprise/{enterpriseId}/pay

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"

POST /payment/complete/enterprise/{enterpriseId}

POST /payment/complete/enterprise/{enterpriseId}

Path parameters

Body

Payment Status

  • cartId string Required

    Globally unique cart id

  • enterpriseOrderId string Required

    THG internal order ID

  • initialRequest string Required

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

  • initialResponse string Required

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

  • paymentPayId string Required

    WechatPay/Alipay order ID

  • paidAt string Required

    Payment time in ISO_8601 format

  • status string Required

    Status of payment operation

    Values are success or failed.

  • failReason string

    Reason for failure

Responses

  • • 200 object

    Payment status received successfully

  • • 400 object

    Invalid message

  • • 409

    Payment status already updated for this cart

  • • 500 object

    Payment status update failed

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=cf78e7c81bd00717697c2b11577b48e66770504cb97d2a9b9621d1e99d8a9182","paymentPayId":"string","paidAt":"2021-04-26T11:57:18Z","status":"success","failReason":"Invalid payment detail provided"}'
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
  }
}

declaration

Declare to the customs after payment declaration

POST /declarations/enterprise/{enterpriseId}

POST /declarations/enterprise/{enterpriseId}

Path parameters

Body

Payment customs info

  • cartId string Required

    SMK cart ID

  • status string Required

    Status of the declaration from the response from the customs

  • payTransactionId string Required

    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

  • • 400 object

    Invalid message

  • • 409

    Payment status already updated for this cart

  • • 500 object

    Payment status update failed

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