DOCUMENTATION API v2

Orders

Retrieve an order directly with either its orderId or merchantReference. Use GET /v2/orders/{orderId} when you have the ID, or GET /v2/orders/by-reference/{merchantReference} when you only have the reference. Both lookups require orders_read and are scoped to your merchant and environment.

Create an order

POST/v2/orders

Create a USD order and its first checkout session in one request. amountMinor remains the merchant subtotal; the response includes the frozen customer fee and total. Redirect your customer to the returned checkoutUrl.

Required scope: orders_write

Authorization

API key · Send the complete secret in x-api-key.

Header parameters

x-api-keystringrequired: Your server-side merchant secret key.
Content-Typerequired: application/json
Idempotency-Keystringrequired: 16–128 letters, numbers, underscores or hyphens. Reuse the same key when retrying the same operation. Retry guidance.

Request body

merchantReferencestringrequired: Your stable order reference, 1–128 characters. Leading and trailing whitespace is trimmed; control characters are rejected. Unique within your merchant and mode.
currencystringrequired: Must be USD. Crypto selection in checkout does not change the order currency.
amountMinorintegerrequired: Positive merchant subtotal in US cents. 12900 means USD 129.00. All values and arithmetic must stay within the safe integer limit of 9,007,199,254,740,991.
itemsarrayoptional: Optional. Omit it or send an empty array when the order has no line items. If populated, supply 1–100 items; each needs name (1–200 characters), quantity (positive safe integer) and unitPriceMinor (nonnegative safe integer in cents). The sum of quantity × unitPriceMinor must equal amountMinor exactly.
expiresAtUTC timestampoptional: Defaults to 24 hours after creation. An explicit value must be in the future when first created. Use UTC ISO 8601, for example 2026-09-10T12:00:00.000Z; choose a future value for your request.
successUrlstringoptional: Optional HTTPS destination used only after the backend has persisted the order as paid. It must exactly match an approved URL or match an approved origin/path prefix configured in Merchant Settings. Prefix matches allow descendant paths and query strings. Maximum 2048 characters; no fragments, credentials or custom ports.
cancelUrlstringoptional: Optional HTTPS destination used when the customer leaves checkout. It is navigation only and never cancels the order or promises a refund. It must exactly match an approved URL or match an approved origin/path prefix configured in Merchant Settings. Prefix matches allow descendant paths and query strings. Maximum 2048 characters; no fragments, credentials or custom ports.

Behavior

Idempotency-Key is required. A new order returns 201; a matching retry returns 200 with the existing order and original session. The current status is recalculated on reads.
Every response includes X-Tyga-Request-Id. Save it with the orderId and environment so support can trace the request across the gateway and payment services.
merchantReference is unique within your merchant and mode. Reusing a legacy reference with the same order contents returns the existing order without creating another; changing the contents returns 409 idempotency_conflict.
Do not send tenantId, productId or other undocumented fields. Ownership is derived from your key; unknown fields and query parameters are rejected.
The response adds subtotalMinor, customerFeeMinor and customerTotalMinor. Missing fee configuration defaults to zero; explicitly configured fees are preserved. The fee is calculated and frozen at creation; later fee schedule changes do not change this order. tenantFeeMinor and settlement data are never public.
successUrl and cancelUrl are independent; the checkout never substitutes one for the other. A browser redirect is not payment proof: use the order/payment API or merchant webhook evidence after the backend confirms the payment. Sandbox USDC on Ethereum Sepolia requires explicit tenant enablement and Vault configuration.

Responses

201 Created · illustrative response. See errors and retry guidance.

Create an order — TypeScript

// Node.js 22+. Run on your server, never in the browser.
const apiKey = process.env.TYGA_SECRET_KEY;
if (!apiKey) throw new Error('Set TYGA_SECRET_KEY');

const apiBase = process.env.TYGA_API_BASE;
if (!apiBase) throw new Error('Set TYGA_API_BASE from the API keys page');
const response = await fetch(`${apiBase.replace(/\/+$/, "")}/v2/orders`, {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1042-create-001',
  },
  body: JSON.stringify({
  "merchantReference": "YOUR-ORDER-1042",
  "currency": "USD",
  "amountMinor": 12900,
  "successUrl": "https://merchant.example/checkout/success",
  "cancelUrl": "https://merchant.example/checkout/cancel",
  "items": [
    {
      "name": "Everyday Tote",
      "quantity": 1,
      "unitPriceMinor": 7900
    },
    {
      "name": "Field Notes Set",
      "quantity": 2,
      "unitPriceMinor": 2500
    }
  ]
}),
});
if (!response.ok) throw new Error(`Request failed: HTTP ${response.status}`);
const result = response.status === 204 ? null : await response.json();
// Use result in your server flow. Do not log checkout URLs or credentials.

201 Created · illustrative response

{
  "merchant": {
    "name": "Your merchant name"
  },
  "merchantReference": "YOUR-ORDER-1042",
  "currency": "USD",
  "amountMinor": 12900,
  "successUrl": "https://merchant.example/checkout/success",
  "cancelUrl": "https://merchant.example/checkout/cancel",
  "items": [
    {
      "name": "Everyday Tote",
      "quantity": 1,
      "unitPriceMinor": 7900
    },
    {
      "name": "Field Notes Set",
      "quantity": 2,
      "unitPriceMinor": 2500
    }
  ],
  "expiresAt": "2026-09-10T12:00:00.000Z",
  "status": "open",
  "subtotalMinor": 12900,
  "customerFeeMinor": 0,
  "customerTotalMinor": 12900,
  "orderId": "11111111-1111-4111-8111-111111111111",
  "createdAt": "2026-09-09T12:00:00.000Z",
  "checkoutUrl": "https://tyga-pay-checkout-dev.web.app/#checkout=<sessionId>.<secret>",
  "sessionId": "22222222-2222-4222-8222-222222222222"
}

Check an order reference

GET/v2/orders/reference-check/{merchantReference}

Check whether a merchant reference is already used by your merchant in the current mode before creating an order.

Required scope: orders_read

Authorization

API key · Send the complete secret in x-api-key.

Path parameters

merchantReferencestringrequired: The merchant reference to check. URL-encode it when constructing the path.

Header parameters

x-api-keystringrequired: Your server-side merchant secret key.

Request body

merchantReferencestringrequired: The reference to check, 1–128 characters. URL-encode the value when constructing the path.

Behavior

The response contains only exists; it never returns another order or tenant’s data.
References are checked within your merchant and the current mode. Sandbox and production references are independent.
This is a read-only preflight check. Keep the final create request idempotent because another request may use the reference after this check.

Responses

200 OK · illustrative response. See errors and retry guidance.

Check an order reference — TypeScript

// Node.js 22+. Run on your server, never in the browser.
const apiKey = process.env.TYGA_SECRET_KEY;
if (!apiKey) throw new Error('Set TYGA_SECRET_KEY');
const resourceId = process.env.MERCHANT_REFERENCE;
if (!resourceId) throw new Error('Set MERCHANT_REFERENCE');

const apiBase = process.env.TYGA_API_BASE;
if (!apiBase) throw new Error('Set TYGA_API_BASE from the API keys page');
const response = await fetch(`${apiBase.replace(/\/+$/, "")}/v2/orders/reference-check/${encodeURIComponent(resourceId)}`, {
  method: 'GET',
  headers: {
    'x-api-key': apiKey,
  },
});
if (!response.ok) throw new Error(`Request failed: HTTP ${response.status}`);
const result = response.status === 204 ? null : await response.json();
// Use result in your server flow. Do not log checkout URLs or credentials.

200 OK · illustrative response

{
  "exists": false
}

Retrieve an order

GET/v2/orders/{orderId}

Retrieve an order owned by your merchant in the current mode using its orderId.

Required scope: orders_read

Authorization

API key · Send the complete secret in x-api-key.

Path parameters

orderIdstringrequired: The identifier returned by the creation request. Must belong to your merchant.

Header parameters

x-api-keystringrequired: Your server-side merchant secret key.

Behavior

No request body, query parameters or Idempotency-Key are needed.
Returns open or expired using the server clock. Unknown orders and orders belonging to another merchant return 404.
If you only have a merchantReference, use /v2/orders/by-reference/{merchantReference}. This response does not include a checkout URL.

Responses

200 OK · illustrative order. See errors and retry guidance.

Retrieve an order — TypeScript

// Node.js 22+. Run on your server, never in the browser.
const apiKey = process.env.TYGA_SECRET_KEY;
if (!apiKey) throw new Error('Set TYGA_SECRET_KEY');
const resourceId = process.env.ORDER_ID;
if (!resourceId) throw new Error('Set ORDER_ID');

const apiBase = process.env.TYGA_API_BASE;
if (!apiBase) throw new Error('Set TYGA_API_BASE from the API keys page');
const response = await fetch(`${apiBase.replace(/\/+$/, "")}/v2/orders/${encodeURIComponent(resourceId)}`, {
  method: 'GET',
  headers: {
    'x-api-key': apiKey,
  },
});
if (!response.ok) throw new Error(`Request failed: HTTP ${response.status}`);
const result = response.status === 204 ? null : await response.json();
// Use result in your server flow. Do not log checkout URLs or credentials.

200 OK · illustrative order

{
  "merchant": {
    "name": "Your merchant name"
  },
  "merchantReference": "YOUR-ORDER-1042",
  "currency": "USD",
  "amountMinor": 12900,
  "successUrl": "https://merchant.example/checkout/success",
  "cancelUrl": "https://merchant.example/checkout/cancel",
  "items": [
    {
      "name": "Everyday Tote",
      "quantity": 1,
      "unitPriceMinor": 7900
    },
    {
      "name": "Field Notes Set",
      "quantity": 2,
      "unitPriceMinor": 2500
    }
  ],
  "expiresAt": "2026-09-10T12:00:00.000Z",
  "status": "open",
  "subtotalMinor": 12900,
  "customerFeeMinor": 0,
  "customerTotalMinor": 12900,
  "orderId": "11111111-1111-4111-8111-111111111111",
  "createdAt": "2026-09-09T12:00:00.000Z"
}

Retrieve an order by merchant reference

GET/v2/orders/by-reference/{merchantReference}

Retrieve an order owned by your merchant using the merchantReference supplied by your customer.

Required scope: orders_read

Authorization

API key · Send the complete secret in x-api-key.

Path parameters

merchantReferencestringrequired: The exact merchant reference supplied when creating the order. URL-encode it when constructing the path.

Header parameters

x-api-keystringrequired: Your server-side merchant secret key.

Request body

merchantReferencestringrequired: The exact 1–128 character reference used when creating the order. URL-encode the value when constructing the path.

Behavior

The lookup is scoped to your merchant and current mode. Unknown orders and references belonging to another merchant return 404.
The response does not include a checkout URL or any bearer token.

Responses

200 OK · illustrative order. See errors and retry guidance.

Retrieve an order by merchant reference — TypeScript

// Node.js 22+. Run on your server, never in the browser.
const apiKey = process.env.TYGA_SECRET_KEY;
if (!apiKey) throw new Error('Set TYGA_SECRET_KEY');
const resourceId = process.env.MERCHANT_REFERENCE;
if (!resourceId) throw new Error('Set MERCHANT_REFERENCE');

const apiBase = process.env.TYGA_API_BASE;
if (!apiBase) throw new Error('Set TYGA_API_BASE from the API keys page');
const response = await fetch(`${apiBase.replace(/\/+$/, "")}/v2/orders/by-reference/${encodeURIComponent(resourceId)}`, {
  method: 'GET',
  headers: {
    'x-api-key': apiKey,
  },
});
if (!response.ok) throw new Error(`Request failed: HTTP ${response.status}`);
const result = response.status === 204 ? null : await response.json();
// Use result in your server flow. Do not log checkout URLs or credentials.

200 OK · illustrative order

{
  "merchant": {
    "name": "Your merchant name"
  },
  "merchantReference": "YOUR-ORDER-1042",
  "currency": "USD",
  "amountMinor": 12900,
  "successUrl": "https://merchant.example/checkout/success",
  "cancelUrl": "https://merchant.example/checkout/cancel",
  "items": [
    {
      "name": "Everyday Tote",
      "quantity": 1,
      "unitPriceMinor": 7900
    },
    {
      "name": "Field Notes Set",
      "quantity": 2,
      "unitPriceMinor": 2500
    }
  ],
  "expiresAt": "2026-09-10T12:00:00.000Z",
  "status": "open",
  "subtotalMinor": 12900,
  "customerFeeMinor": 0,
  "customerTotalMinor": 12900,
  "orderId": "11111111-1111-4111-8111-111111111111",
  "createdAt": "2026-09-09T12:00:00.000Z"
}