1. Thông tin tài khoản商户凭据

2. Ký HMAC-SHA256HMAC-SHA256 签名

payload = METHOD + "\n" +
          PATH   + "\n" +
          TIMESTAMP + "\n" +
          NONCE  + "\n" +
          BODY

Ví dụ ký (Python)签名示例（Python）

import time, secrets, hmac, hashlib, base64, json, requests

APP_SECRET = "8b4068e85b582fb3695c795dc37fad3d2b2c8dfc240d7a0fc7a028913d835131"
MERCHANT_ID = "5"

def sign_and_post(method, path, body):
    ts    = str(int(time.time() * 1000))
    nonce = secrets.token_hex(12)             # 24 chars
    raw   = json.dumps(body, separators=(',', ':'), ensure_ascii=False).encode()
    payload = "\n".join([method, path, ts, nonce]).encode() + b"\n" + raw
    sig = base64.b64encode(hmac.new(APP_SECRET.encode(), payload, hashlib.sha256).digest()).rstrip(b"=").decode()
    headers = {
        "Content-Type":  "application/json",
        "X-Merchant-Id": MERCHANT_ID,
        "X-Timestamp":   ts,
        "X-Nonce":       nonce,
        "X-Signature":   sig,
    }
    return requests.post("https://api.tscash.pro" + path, headers=headers, data=raw, timeout=15)

Ví dụ ký (Node.js)签名示例（Node.js）

const crypto = require('crypto');
const fetch = require('node-fetch');

const APP_SECRET  = '8b4068e85b582fb3695c795dc37fad3d2b2c8dfc240d7a0fc7a028913d835131';
const MERCHANT_ID = '5';

async function signAndPost(method, path, body) {
  const ts    = Date.now().toString();
  const nonce = crypto.randomBytes(12).toString('hex');  // 24 chars
  const raw   = JSON.stringify(body);
  const payload = [method, path, ts, nonce, raw].join('\n');
  const sig = crypto.createHmac('sha256', APP_SECRET)
                    .update(payload).digest('base64').replace(/=+$/, '');
  return fetch('https://api.tscash.pro' + path, {
    method,
    headers: {
      'Content-Type':  'application/json',
      'X-Merchant-Id': MERCHANT_ID,
      'X-Timestamp':   ts,
      'X-Nonce':       nonce,
      'X-Signature':   sig,
    },
    body: raw,
  });
}

3. Tạo đơn nạp / Create Order创建代收订单

POST https://api.tscash.pro/gateway/v1/payin/orders

Tham số request请求参数

Ví dụ示例

POST /gateway/v1/payin/orders
Content-Type:  application/json
X-Merchant-Id: 5
X-Timestamp:   1716415200000
X-Nonce:       a1b2c3d4e5f60718293a4b5c
X-Signature:   p9XzAbCdEfGhIjK…

{
  "merchantOrderId": "ORDER-20260523-001",
  "productId":       7,
  "amount":          500000,
  "outMemId":        "user-9527",
  "subject":         "Recharge 500K VND",
  "callbackUrl":     "https://merchant.com/api/cb",
  "redirectUrl":     "https://merchant.com/pay-done"
}

Response thành công成功响应

{
  "code": 200,
  "msg":  "OK",
  "data": {
    "orderCode":       "TDS2026052305594300000100000293",
    "merchantOrderId": "ORDER-20260523-001",
    "status":          "created",
    "amount":          500000,
    "currency":        "VND",
    "payUrl":          "https://h5.tscash.pro/#/pay/TDS2026052305594300000100000293"
  }
}

4. Truy vấn đơn查询订单

GET https://api.tscash.pro/gateway/v1/payin/orders/{orderCode}

GET /gateway/v1/payin/orders/TDS2026052305594300000100000293
X-Merchant-Id: 5
X-Timestamp:   1716415300000
X-Nonce:       7a8b9c0d1e2f3041526378…
X-Signature:   …

# Response:
{
  "code": 200,
  "data": {
    "orderCode":       "TDS2026052305594300000100000293",
    "merchantOrderId": "ORDER-20260523-001",
    "status":          "completed",
    "amount":          500000,
    "realAmount":      500000,
    "paidAmount":      500000,
    "currency":        "VND",
    "completedAt":     "2026-05-23T05:48:12Z"
  }
}

5. Callback (async)异步回调

Header callback回调 Header

Body回调 Body

{
  "orderCode":       "TDS2026052305594300000100000293",
  "merchantOrderId": "ORDER-20260523-001",
  "status":          "completed",
  "amount":          500000,
  "paidAmount":      500000,
  "currency":        "VND",
  "timestamp":       1716415692000,
  "completedAt":     "2026-05-23T05:48:12.345Z"
}

Ví dụ verify callback (Python)验回调示例（Python）

import hmac, hashlib, base64
from flask import request, abort

APP_SECRET = "8b4068e85b582fb3695c795dc37fad3d2b2c8dfc240d7a0fc7a028913d835131"

@app.route("/api/cb", methods=["POST"])
def cb():
    ts    = request.headers.get("X-Timestamp", "")
    nonce = request.headers.get("X-Nonce", "")
    sig   = request.headers.get("X-Signature", "")
    body  = request.get_data()   # raw bytes
    payload = b"POST\n/api/cb\n" + ts.encode() + b"\n" + nonce.encode() + b"\n" + body
    expect = base64.b64encode(hmac.new(APP_SECRET.encode(), payload, hashlib.sha256).digest()).rstrip(b"=").decode()
    if not hmac.compare_digest(sig, expect):
        abort(401)
    data = request.get_json()
    # idempotent update by orderCode + status
    ...
    return "ok", 200

6. Trạng thái đơn订单状态

7. Mã lỗi thường gặp常见错误码