Postman — API Checkout

REPLACE EXAMPLE CREDENTIALS

Replace all placeholder values in the pre-request scripts:

• 'your-api-secret' → Your actual API Secret from the merchant portal
• Replace MCH_20240101_ABC123 in the URL with your actual Merchant ID

API Checkout does not use X-Api-Key. Only X-Timestamp and X-Signature are set.

PERMISSION REQUIRED

API Checkout must be explicitly enabled for your account. Contact support to activate it.

How Signatures Work

API Checkout uses the same signing algorithm as Hosted Payments but without X-Api-Key.

POST signature: Base64(HMAC-SHA256(timestamp\nPOST\npath\nBase64(SHA256(body)), apiSecret))

GET signature: Base64(HMAC-SHA256(timestamp\nGET\npath, apiSecret))

---

Get Payment Methods

Fetch this at runtime before showing the payment UI. Never hardcode currency/network combinations.

1. Configure the Request

Method: GETURL: https://api.paystablecoin.global/api/v1/merchants/MCH_20240101_ABC123/checkout/payment-methods

Replace MCH_20240101_ABC123 with your Merchant ID.

2. Add the Pre-request Script

// ── Configuration ──────────────────────────────────────────────────
const secretKey = 'your-api-secret';

// ── Timestamp ──────────────────────────────────────────────────────
const timestamp = Date.now().toString();

// ── Request details ────────────────────────────────────────────────
const method = pm.request.method;                 // "GET"
const urlObj = new URL(pm.request.url.toString());
const path   = urlObj.pathname;

// ── Build signature string (no body, no query string) ──────────────
const stringToSign = [timestamp, method, path].join('\n');

console.log('=== API Checkout — Get Payment Methods ===');
console.log('String to Sign:', stringToSign.replace(/\n/g, ' | '));

// ── HMAC-SHA256 → Base64 ───────────────────────────────────────────
const signature = CryptoJS.enc.Base64.stringify(
    CryptoJS.HmacSHA256(stringToSign, secretKey)
);

// ── Set headers (no X-Api-Key for API Checkout) ────────────────────
pm.request.headers.upsert({ key: 'X-Timestamp', value: timestamp });
pm.request.headers.upsert({ key: 'X-Signature', value: signature });

The response lists available payment methods. Sort by displayOrder (ascending) and render options to the user.

---

Create Checkout Order

After the customer selects a currency and network, create the order immediately.

1. Configure the Request

Method: POSTURL: https://api.paystablecoin.global/api/v1/merchants/MCH_20240101_ABC123/checkout/orders

2. Set the Request Body

Go to Body → raw → JSON:

{
  "merchantOrderId": "ORDER_{{$timestamp}}",
  "orderAmount": {
    "value": "100.50",
    "currency": "USDC"
  },
  "paymentMethodType": "ON_CHAIN_TRANSFER",
  "network": "tron",
  "expiresAt": "2026-12-31T23:59:59Z",
  "callbackUrl": "https://yoursite.com/webhook/checkout"
}

WARNING

orderAmount.currency must be a stablecoin: USDC, USDT, or USD1. Fiat currencies are not supported by API Checkout.

3. Add the Pre-request Script

// ── Configuration ──────────────────────────────────────────────────
const secretKey = 'your-api-secret';

// ── Timestamp ──────────────────────────────────────────────────────
const timestamp = Date.now().toString();

// ── Request details ────────────────────────────────────────────────
const method = pm.request.method;                 // "POST"
const urlObj = new URL(pm.request.url.toString());
const path   = urlObj.pathname;

// ── Body: replace Postman variables, then minify ───────────────────
let body = pm.request.body.raw;
body = body.replace(/\{\{\$timestamp\}\}/g, timestamp);
body = JSON.stringify(JSON.parse(body));          // minify
pm.request.body.raw = body;

// ── Body hash: SHA256 → Base64 ─────────────────────────────────────
const bodyHash = CryptoJS.SHA256(body).toString(CryptoJS.enc.Base64);

// ── Build signature string ─────────────────────────────────────────
const stringToSign = [timestamp, method, path, bodyHash].join('\n');

console.log('=== API Checkout — Create Order ===');
console.log('Timestamp:', timestamp);
console.log('Method:', method);
console.log('Path:', path);
console.log('Body Hash (Base64):', bodyHash);
console.log('String to Sign:', stringToSign.replace(/\n/g, ' | '));

// ── HMAC-SHA256 → Base64 ───────────────────────────────────────────
const signature = CryptoJS.enc.Base64.stringify(
    CryptoJS.HmacSHA256(stringToSign, secretKey)
);
console.log('Signature:', signature);

// ── Set headers (no X-Api-Key for API Checkout) ────────────────────
pm.request.headers.upsert({ key: 'Content-Type', value: 'application/json' });
pm.request.headers.upsert({ key: 'X-Timestamp',  value: timestamp });
pm.request.headers.upsert({ key: 'X-Signature',  value: signature });

4. Send and Verify

A successful response includes the deposit details to show the customer:

{
  "code": "00000",
  "data": {
    "depositAddress": "TXyz...1234",
    "cryptoPaymentAmount": { "value": "100.50", "currency": "USDC" },
    "networkDisplayName": "TRON Network",
    "expiresAt": "2026-12-31T23:59:59Z"
  }
}

WARNING

Display cryptoPaymentAmount to the customer, not orderAmount. They may differ due to fees.

---

Query Checkout Order

Use as a fallback if the webhook is not received.

1. Configure the Request

Method: GETURL: https://api.paystablecoin.global/api/v1/merchants/MCH_20240101_ABC123/checkout/orders/ORDER_1738112345000

Replace the order ID at the end with the actual merchantOrderId.

2. Add the Pre-request Script

// ── Configuration ──────────────────────────────────────────────────
const secretKey = 'your-api-secret';

// ── Timestamp ──────────────────────────────────────────────────────
const timestamp = Date.now().toString();

// ── Request details ────────────────────────────────────────────────
const method = pm.request.method;                 // "GET"
const urlObj = new URL(pm.request.url.toString());
const path   = urlObj.pathname;

// ── Build signature string ─────────────────────────────────────────
const stringToSign = [timestamp, method, path].join('\n');

// ── HMAC-SHA256 → Base64 ───────────────────────────────────────────
const signature = CryptoJS.enc.Base64.stringify(
    CryptoJS.HmacSHA256(stringToSign, secretKey)
);

// ── Set headers ────────────────────────────────────────────────────
pm.request.headers.upsert({ key: 'X-Timestamp', value: timestamp });
pm.request.headers.upsert({ key: 'X-Signature', value: signature });

Poll every 5–10 seconds until status reaches a terminal state: SUCCEEDED, FAILED, or CLOSED.

---

Troubleshooting

Error	Likely Cause	Fix
Invalid signature	Wrong secret or body mismatch	Check Console log for the body hash; verify secretKey
API_PERMISSION_DISABLED (50010)	Checkout not activated	Contact support to enable API Checkout
Invalid or expired timestamp	Clock out of sync	Sync system time; timestamp must be within ±5 minutes
Invalid stablecoin currency	Fiat currency used	Use USDC, USDT, or USD1 for orderAmount.currency

Related Documentation

• API Checkout Integration Guide — Step-by-step integration walkthrough
• API Checkout Reference — Full endpoint and field specification
• Signature Algorithm — Signature calculation details