Ca key (http_api_key)
Send an authentication token in the
x-ca-key
header
to authenticate with the API.
This is the API descriptor for the Nomad Checkout API. Read the documentation online at Nomad API Suite.
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.
https://nomad.samarkand-global.cn/checkout
Send an authentication token in the
x-ca-key
header
to authenticate with the API.
Handle user shopping baskets
Source platform
Values are shopify
, commerce
, woocommerce
, magento
, bigcommerce
, or squarespace
.
Globally unique id for merchant
Create new cart details
Full url to merchant store
Whether merchant site url is a platform subdomain
Default value is true
.
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}'
{
"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
}
{
"code": 42,
"message": "Status of operation",
"data": {
"cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
"exchangeRate": 9.1
}
}
{
"code": 42,
"message": "Status of operation",
"data": {
"cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
"exchangeRate": 9.1
}
}
{
"code": 42,
"message": "Status of operation",
"data": {
"cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
"exchangeRate": 9.1
}
}
New enterprise cart
Globally unique id for merchant
Issued unique enterprised ID
Create new cart details
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}}'
{
"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
}
}
{
"code": 42,
"message": "Status of operation",
"data": {
"cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
"exchangeRate": 9.1
}
}
{
"code": 42,
"message": "Status of operation",
"data": {
"cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
"exchangeRate": 9.1
}
}
{
"code": 42,
"message": "Status of operation",
"data": {
"cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
"exchangeRate": 9.1
}
}
Globally unique id for cart
Issued unique enterprised ID
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"}'
{
"paymentUrl": "https://pay.globepay.co/api/v1.0/h5_payment/partners/123/orders/1OE456"
}
{
"code": 42,
"message": "Status of operation",
"data": {
"cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
"exchangeRate": 9.1
}
}
{
"code": 42,
"message": "Status of operation",
"data": {
"cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
"exchangeRate": 9.1
}
}
{
"code": 42,
"message": "Status of operation",
"data": {
"cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
"exchangeRate": 9.1
}
}
Receive payment status
Called when cart is ready for payment
Issued unique enterprised ID
curl \
-X GET https://nomad.samarkand-global.cn/checkout/carts/DJTHX555202105071817lMEIYK9610GZ/enterprise/REC890/pay \
-H "x-ca-key: $API_KEY"
Issued unique enterprised ID
Payment Status
Globally unique cart id
THG internal order ID
Initial request url to Alipay/WechatPay, for customs's reference
Initial response url from Alipay/WechatPay, for customs's reference
WechatPay/Alipay order ID
Payment time in ISO_8601 format
Status of payment operation
Values are success
or failed
.
Reason for failure
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"}'
{
"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"
}
{
"code": 42,
"message": "Status of operation",
"data": {
"cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
"exchangeRate": 9.1
}
}
{
"code": 42,
"message": "Status of operation",
"data": {
"cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
"exchangeRate": 9.1
}
}
{
"code": 42,
"message": "Status of operation",
"data": {
"cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
"exchangeRate": 9.1
}
}
Declare to the customs after payment declaration
Issued unique enterprised ID
Payment customs info
SMK cart ID
Status of the declaration from the response from the customs
Payment transaction serial number (pay_transaction_id from Alipay customs declaration response, verify_department_trade_id from WechatPay customs declaration response)
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"}'
{
"cartId": "DJPRO8732021031600441234567899610GZ",
"status": "SUBMITTED",
"payTransactionId": "2018112288340107038204310100000"
}
{
"code": 42,
"message": "Status of operation",
"data": {
"cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
"exchangeRate": 9.1
}
}
{
"code": 42,
"message": "Status of operation",
"data": {
"cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
"exchangeRate": 9.1
}
}
{
"code": 42,
"message": "Status of operation",
"data": {
"cartId": "SMK474-1Vzff80HMU0FqdotSN8T0mGjK",
"exchangeRate": 9.1
}
}