openapi: 3.0.0 info: title: Nomad Checkout description: This is the API descriptor for the Nomad Checkout API. Read the documentation online at [Nomad API Suite](https://api.samarkand.io/). - 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` contact: email: paul@samarkand.global version: 'x.x.x' servers: - url: https://nomad.samarkand-global.cn/checkout variables: {} tags: - name: 'carts' description: 'Handle user shopping baskets' - name: 'payment' description: 'Receive payment status' - name: 'declaration' description: 'Declare to the customs after payment declaration' externalDocs: url: 'https://api.samarkand.io/doc/nomad-checkout' description: 'Find more info here' paths: /carts/{platform}/{merchantId}: post: description: 'New cart' tags: - 'carts' parameters: - in: path name: platform schema: type: string enum: - 'shopify' - 'commerce' - 'woocommerce' - 'magento' - 'bigcommerce' - 'squarespace' required: true description: 'Source platform' - in: path name: merchantId schema: type: string required: true description: 'Globally unique id for merchant' example: 'SMK474' requestBody: description: Create new cart details content: application/json: schema: type: 'object' properties: merchantSiteUrl: type: 'string' description: 'Full url to merchant store' example: 'https://smktestpartner.myshopify.com/cart' cart: type: 'object' description: 'Cart data (platform specific)' oneOf: - $ref: '#/components/schemas/ShopifyCart' - $ref: '#/components/schemas/CommerceCart' subdomain: type: 'boolean' default: true description: 'Whether merchant site url is a platform subdomain' example: false required: - 'merchantSiteUrl' - 'cart' responses: 200: description: Cart created successfully content: application/json: schema: $ref: '#/components/schemas/ApiResponse' 400: description: Invalid message content: application/json: schema: $ref: '#/components/schemas/ApiResponse' 500: description: Cart creation failed content: application/json: schema: $ref: '#/components/schemas/ApiResponse' /carts/enterprise/{enterpriseId}/merchants/{merchantId}: post: description: 'New enterprise cart' tags: - 'carts' parameters: - in: path name: merchantId schema: type: string required: true description: 'Globally unique id for merchant' example: 'SMK474' - in: path name: enterpriseId schema: type: string required: true description: 'Issued unique enterprised ID' example: 'REC890' requestBody: description: Create new cart details content: application/json: schema: type: 'object' properties: cancelUrl: type: string description: 'URL to navigate to if user cancels checkout' example: 'https://smktestpartner.myshopify.com/cancel' cart: type: 'object' description: 'Cart data (platform specific)' $ref: '#/components/schemas/EnterpriseCart' required: - 'cart' - 'cancelUrl' responses: 200: description: Cart created successfully content: application/json: schema: $ref: '#/components/schemas/ApiResponse' 400: description: Invalid message content: application/json: schema: $ref: '#/components/schemas/ApiResponse' 500: description: Cart creation failed content: application/json: schema: $ref: '#/components/schemas/ApiResponse' /carts/{cartId}/enterprise/{enterpriseId}: put: description: 'Update enterprise cart' tags: - 'carts' parameters: - in: path name: cartId schema: type: string required: true description: 'Globally unique id for cart' example: 'DJTHX555202105071817lMEIYK9610GZ' - in: path name: enterpriseId schema: type: string required: true description: 'Issued unique enterprised ID' example: 'REC890' requestBody: description: Update cart details content: application/json: schema: type: 'object' properties: paymentUrl: type: 'string' description: 'URL for user to make payment' example: 'https://pay.globepay.co/api/v1.0/h5_payment/partners/123/orders/1OE456' required: - 'paymentUrl' responses: 200: description: Cart updated successfully content: application/json: schema: $ref: '#/components/schemas/ApiResponse' 400: description: Invalid message content: application/json: schema: $ref: '#/components/schemas/ApiResponse' 500: description: Cart update failed content: application/json: schema: $ref: '#/components/schemas/ApiResponse' /carts/{cartId}/enterprise/{enterpriseId}/pay: get: description: 'Called when cart is ready for payment' tags: - 'payment' parameters: - in: path name: cartId schema: type: string required: true example: DJTHX555202105071817lMEIYK9610GZ - in: path name: enterpriseId schema: type: string required: true description: 'Issued unique enterprised ID' example: 'REC890' responses: 301: description: 'Redirects to shipping form page' /payment/complete/enterprise/{enterpriseId}: post: tags: - 'payment' parameters: - in: path name: enterpriseId schema: type: string required: true description: 'Issued unique enterprised ID' example: 'REC890' requestBody: description: Payment Status content: application/json: schema: type: 'object' properties: cartId: type: 'string' description: 'Globally unique cart id' example: '' enterpriseOrderId: type: string description: THG internal order ID initialRequest: type: string description: Initial request url to Alipay/WechatPay, for customs's reference example: "https://pay.co/api/v1.0/wechat_jsapi_gateway/partners/F96FTB/orders/TEM1129354775085478274207817?time=1587033049529&nonce_str=TEM1129354775085478274207817&sign=cf78e7c81bd00717697c2b11577b48e66770504cb97d2a9b9621d1e99d8a9182" initialResponse: type: string description: Initial response url from Alipay/WechatPay, for customs's reference example: "https://pay.co/api/v1.0/wechat_jsapi_gateway/partners/F96FTB/response=1587033049529&nonce_str=TEM1129354775085478274207817&sign=cf78e7c81bd00717697c2b11577b48e66770504cb97d2a9b9621d1e99d8a9182" paymentPayId: type: string description: WechatPay/Alipay order ID paidAt: type: string description: Payment time in ISO_8601 format example: '2021-04-26T11:57:18Z' status: type: 'string' description: 'Status of payment operation' enum: - 'success' - 'failed' failReason: type: 'string' description: 'Reason for failure' example: 'Invalid payment detail provided' required: - 'cartId' - 'status' - 'enterpriseOrderId' - 'paymentPayId' - 'paidAt' - 'initialRequest' - 'initialResponse' responses: 200: description: Payment status received successfully content: application/json: schema: $ref: '#/components/schemas/ApiResponse' 400: description: Invalid message content: application/json: schema: $ref: '#/components/schemas/ApiResponse' 409: description: Payment status already updated for this cart 500: description: Payment status update failed content: application/json: schema: $ref: '#/components/schemas/ApiResponse' /declarations/enterprise/{enterpriseId}: post: tags: - 'declaration' parameters: - in: path name: enterpriseId schema: type: string required: true description: 'Issued unique enterprised ID' example: 'REC890' requestBody: description: Payment customs info content: application/json: schema: type: 'object' properties: cartId: type: 'string' description: 'SMK cart ID' example: 'DJPRO8732021031600441234567899610GZ' status: type: 'string' description: 'Status of the declaration from the response from the customs' example: SUBMITTED payTransactionId: type: 'string' description: 'Payment transaction serial number (pay_transaction_id from Alipay customs declaration response, verify_department_trade_id from WechatPay customs declaration response)' example: '2018112288340107038204310100000' required: - 'cartId' - 'status' - 'payTransactionId' responses: 200: description: Payment status received successfully content: application/json: schema: $ref: '#/components/schemas/ApiResponse' 400: description: Invalid message content: application/json: schema: $ref: '#/components/schemas/ApiResponse' 409: description: Payment status already updated for this cart 500: description: Payment status update failed content: application/json: schema: $ref: '#/components/schemas/ApiResponse' components: schemas: CommerceCart: title: CommerceCart description: 'Samarkand Commerce cart' type: object properties: userId: type: string description: 'Globally unique user id' products: type: array description: 'Shopping products' items: type: object properties: productId: type: string description: 'Globally unique product id' example: '5017978000265' quantity: type: number description: 'Quantity' example: 2 grossWeight: type: number description: 'Gross weight' example: 0.08 taxRate: type: number description: 'China import duty' example: 9.1 nameEn: type: string description: 'Product name in english' example: 'Probio7 PREGNAKALM - 30 Vegan Sachets' expressType: type: string description: 'Import route' example: 'BC' skuNumber: type: string description: 'Globally unique stock keeping unit (sku) number' example: 'PB7PRK301' barcode: type: string description: 'Globally unique barcode number' example: '5017978000265' price: type: number description: 'Price' example: 29.99 currency: type: string description: 'ISO-4217 code' example: 'RMB' images: type: object description: 'Images' properties: uploads: type: array description: 'List of public image URLs' items: type: string description: 'Public image URL' example: 'https://cdn.shopify.com/s/files/1/0024/2240/7213/products/PREG_plain.png?v=1596453270' urls: type: array description: 'List of public image URLs' items: type: string description: 'Public image URL' example: 'https://cdn.shopify.com/s/files/1/0024/2240/7213/products/PREG_plain.png?v=1596453270' ShopifyCart: title: ShopifyCart description: 'Shopify cart' type: object properties: currency: type: string description: 'ISO-4217 code' example: 'GBP' item_count: description: 'Number of products' type: number example: 5 items: type: array description: 'Products' items: type: object properties: id: type: number description: 'Globally unique product id' example: 36801771733142 quantity: type: number description: 'Quantity' example: 2 variant_id: type: number description: 'Globally unique product variant id' example: 14808998805549 key: type: string description: 'Globally unique product id' example: '14808998805549:7d7c76c0a1dd684c158ea58cf28a5062' title: type: string description: 'Name' example: 'Probio7 50 Plus' price: type: number description: 'Price in units' example: 2349 sku: type: string description: 'SKU number' example: 'PB50' grams: type: number description: 'Weight' example: 27 product_title: type: string description: 'Name' example: 'Probio7 50 Plus' properties: type: object description: 'Additional product details' properties: shipping_interval_unit_type: type: string description: 'Subscription payment type' example: 'Months' shipping_interval_frequency: type: string description: 'Subscription payment interval' example: '1' image: type: string description: 'Public image URL' example: 'https://cdn.shopify.com/s/files/1/0024/2240/7213/products/ORIG_plain_73cf94a5-7732-4457-a32a-449b537c4598.png?v=1587802551' vendor: type: string description: 'Globally unique id' example: 'Probio7' total_price: type: number description: 'Price in units' example: 6355 total_weight: type: number description: 'Weight in grams' example: 99.2155 EnterpriseCart: title: EnterpriseCart description: 'Enterprise cart' type: object properties: user: $ref: '#/components/schemas/User' paymentType: type: string example: alipay enum: - alipay - wechatpay products: type: array description: 'Cart products' items: type: object properties: productId: type: string description: 'Globally unique product Id' example: '123456' skuNumber: type: string description: 'Globally unique stock keeping unit (sku) number' example: 'SMK123' barcode: type: string description: 'Globally unique barcode number' example: '1234567890' quantity: type: number description: 'Quantity' example: 1 priceBeforeTax: type: number description: 'Price before tax' example: 10 discount: type: number description: 'Product discount' example: 0 taxRate: type: number description: 'China customs rate' example: 9.1, imageUrl: type: string description: 'Public image URL' example: 'https://mydomain.com/image.png' totalPriceBeforeShippingTaxAndDiscount: type: number description: 'Total price before shipping tax and discount. (Note: this is not allowed to be greater than 5,000 RMB by CBEC rules.)' example: 10 currency: type: string description: 'ISO-4217 code' enum: - 'CNY' - 'GBP' tax: type: number description: 'China tax amount' example: 0.91 shipping: type: number description: 'Delivery charge' example: 20.2 discount: type: number description: 'Any non-product discounts' example: 30.3 totalToPay: type: number description: 'Total to pay' example: 9 ApiResponse: title: ApiResponse description: 'API response info' type: object properties: code: type: integer description: 'HTTP status code' format: int32 message: type: string description: 'Message' example: 'Status of operation' data: $ref: '#/components/schemas/ApiResponseData' ApiResponseData: title: ApiResponseData description: 'API response data' type: object properties: cartId: type: string description: 'Globally unique cart id' example: 'SMK474-1Vzff80HMU0FqdotSN8T0mGjK' exchangeRate: type: number description: 'Exchange rate used for GBP to CNY conversion' example: 9.1 User: type: object properties: platformUserId: type: string description: 'Source platform globally unique user Id' example: '12345' payer: type: object properties: nationalId: type: string description: 'Globally unique China National Id' example: '120103198806018241' name: type: string pattern: ^[^\s][\u2E80-\u2FD5\u3190-\u319f\u3400-\u4DBF\u4E00-\u9FCC\uF900-\uFAAD ]*$ description: name example: 王小明 phoneNumber: type: string description: 'Phone number' example: '13887342813' shippingAddress: type: object description: 'Shipping address' properties: receiver: type: object description: 'Receiver details' properties: name: type: string pattern: ^[^\s][\u2E80-\u2FD5\u3190-\u319f\u3400-\u4DBF\u4E00-\u9FCC\uF900-\uFAAD ]*$ description: Fullname example: 王小明 phoneNumber: type: string description: 'Phone number' example: '13887342813' streetAddress: type: string pattern: ^[^\s][a-zA-Z0-9\u2E80-\u2FD5\u3190-\u319f\u3400-\u4DBF\u4E00-\u9FCC\uF900-\uFAAD ]*$ description: 'Street Address' example: '天钥桥路333号腾飞大厦3楼438室' district: type: string pattern: ^[^\s][\u2E80-\u2FD5\u3190-\u319f\u3400-\u4DBF\u4E00-\u9FCC\uF900-\uFAAD ]*$ description: 'District' example: '徐汇区' province: type: string pattern: ^[^\s][\u2E80-\u2FD5\u3190-\u319f\u3400-\u4DBF\u4E00-\u9FCC\uF900-\uFAAD ]*$ description: 'Province' example: '上海市' city: type: string pattern: ^[^\s][\u2E80-\u2FD5\u3190-\u319f\u3400-\u4DBF\u4E00-\u9FCC\uF900-\uFAAD ]*$ description: 'City' example: '市辖区' country: type: string pattern: ^[^\s][\u2E80-\u2FD5\u3190-\u319f\u3400-\u4DBF\u4E00-\u9FCC\uF900-\uFAAD ]*$ description: 'Country' example: '中国' postcode: type: string description: 'Postcode' example: '200030' securitySchemes: ca_key: type: apiKey description: '' name: x-ca-key in: header ca_stage: type: apiKey description: '' name: x-ca-stage in: header security: - ca_key: []