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 Jun 3, 2021.

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

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

  • 400 object

    Invalid message

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

  • 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

Definition
POST https://nomad.samarkand-global.cn/checkout/carts/{platform}/{merchantId}
cURL example
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":true}'
Request payload example
{ "merchantSiteUrl": "https://smktestpartner.myshopify.com/cart", "cart": {}, "subdomain": true }
Response example (200)
{ "code": 42, "message": "Status of operation", "data": { "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK" } }
Response example (400)
{ "code": 42, "message": "Status of operation", "data": { "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK" } }
Response example (500)
{ "code": 42, "message": "Status of operation", "data": { "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK" } }

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

    • currency string

      ISO-4217 code

    • 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

  • 400 object

    Invalid message

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

  • 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

Definition
POST https://nomad.samarkand-global.cn/checkout/carts/enterprise/{enterpriseId}/merchants/{merchantId}
cURL example
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" } }
Response example (400)
{ "code": 42, "message": "Status of operation", "data": { "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK" } }
Response example (500)
{ "code": 42, "message": "Status of operation", "data": { "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK" } }

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

  • 400 object

    Invalid message

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

  • 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

Definition
PUT https://nomad.samarkand-global.cn/checkout/carts/{cartId}/enterprise/{enterpriseId}
cURL example
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" } }
Response example (400)
{ "code": 42, "message": "Status of operation", "data": { "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK" } }
Response example (500)
{ "code": 42, "message": "Status of operation", "data": { "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK" } }

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

Definition
GET https://nomad.samarkand-global.cn/checkout/carts/{cartId}/enterprise/{enterpriseId}/pay
cURL example
curl \ -X GET https://nomad.samarkand-global.cn/checkout/carts/DJTHX555202105071817lMEIYK9610GZ/enterprise/REC890/pay
Response example (301)
No content

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

  • 400 object

    Invalid message

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

  • 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

Definition
POST https://nomad.samarkand-global.cn/checkout/declarations/enterprise/{enterpriseId}
cURL example
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" } }
Response example (400)
{ "code": 42, "message": "Status of operation", "data": { "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK" } }
Response example (409)
No content
Response example (500)
{ "code": 42, "message": "Status of operation", "data": { "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK" } }

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

  • 400 object

    Invalid message

    • code integer(int32)

      HTTP status code

    • message string

      Message

    • data object

      API response data

      • cartId string

        Globally unique cart id

  • 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

Definition
POST https://nomad.samarkand-global.cn/checkout/payment/complete/enterprise/{enterpriseId}
cURL example
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" } }
Response example (400)
{ "code": 42, "message": "Status of operation", "data": { "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK" } }
Response example (409)
No content
Response example (500)
{ "code": 42, "message": "Status of operation", "data": { "cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK" } }