DOCUMENTATION API v2

Orders & subscriptions

Create and manage orders, check whether a merchant reference is in use, and inspect payment history. Retrieve an order directly with either its orderId or merchantReference. Use GET /v2/orders/{orderId} or GET /v2/orders/by-reference/{merchantReference}; both lookups require orders_read and return orders accessible to your API key. To bill a customer on a schedule, add recurring to an order: see Subscriptions.

Create an order

POST/v2/orders

Create a USD order and its first checkout session in one request. amountMinor remains the merchant subtotal, including any tax and shipping and after any discount; 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 the merchant account tied to your key.
currencystringrequired
Must be USD. Crypto selection in checkout does not change the order currency.
amountMinorintegerrequired
Merchant subtotal in US cents, minimum 100 (USD 1.00). 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, plus taxMinor and shippingMinor, minus discountMinor, must equal amountMinor exactly.
taxMinorintegeroptional
Optional tax in US cents (nonnegative safe integer, default 0). Requires items. Send tax here rather than as a line item; checkout shows it on its own row.
shippingMinorintegeroptional
Optional shipping in US cents (nonnegative safe integer, default 0). Requires items. Shown on its own row at checkout.
discountMinorintegeroptional
Optional order-level discount in US cents (nonnegative safe integer, default 0), subtracted from the items, tax and shipping. Requires items. Shown as a negative row at checkout.
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.
customerobjectoptional
Optional payer contact details with fullName (1–200 characters) and/or email (up to 254 characters, stored lower-cased). With an email, Tyga Pay can email the customer a receipt and refund updates, depending on your Customer email settings. Without one, checkout offers the customer an optional email field. Used only for this order; never included in webhooks. Required with an email for a recurring order.
recurringobjectoptional
Optional. Turns this order into the first payment of a subscription (a recurring agreement). Fields: billing (automatic: Tyga Pay renews on the schedule; merchant: you charge through the API), amountMinor (automatic only: each renewal’s merchant subtotal in cents), interval (day, week, month or year; minute in sandbox only), intervalCount (defaults to 1; day 1–366, week 1–52, month 1–12, year 1, minute 5–1440), maxPerChargeMinor (largest single charge including customer fees; required for merchant billing; for automatic billing defaults to the larger of the first payment and the renewal total), maxPerPeriodMinor (most per billing period including customer fees, enforced on every charge; defaults to maxPerChargeMinor) and endsAt (required UTC timestamp, after the order expires and at most five years away). See Subscriptions below.

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 when requesting support.
  • Reusing a merchantReference with the same order contents returns the existing order without creating another; changing the contents returns 409 idempotency_conflict.
  • Send only documented fields. Your key identifies the merchant account; unknown fields and query parameters are rejected.
  • amountMinor is the order total the customer pays before customer fees: items + taxMinor + shippingMinor − discountMinor. Omitted breakdown fields count as 0, and nonzero values are returned on the order; zero values are left out.
  • 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.
  • successUrl and cancelUrl are independent; the checkout never substitutes one for the other. A browser redirect is not payment proof: check the current order and payment history before fulfilling it.
  • With recurring, the response includes mandateId, the agreement that the first payment activates. A recurring order needs customer.email, because renewal links and notices are emailed.
  • In production, renewals and merchant charges are collected by emailed pay link.

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",
  "customer": {
    "fullName": "Thandi Nkosi",
    "email": "thandi@example.com"
  },
  "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",
  "customer": {
    "fullName": "Thandi Nkosi",
    "email": "thandi@example.com"
  },
  "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://checkout.example/#checkout=<opaque-token>&environment=<api-environment>",
  "sessionId": "22222222-2222-4222-8222-222222222222"
}

Tax, shipping and discounts

Send tax, shipping and an order-level discount as their own fields instead of as line items. taxMinor, shippingMinor and discountMinor are optional, in US cents, and default to 0. They need items, and together they must reconcile to the order amount:

sum(quantity × unitPriceMinor) + taxMinor + shippingMinor − discountMinor = amountMinor

Checkout and the payer receipt email list the items, then a subtotal and a row for each nonzero field, then the order total. Orders without these fields behave exactly as before. Nonzero values are returned on the order and its checkout; zero values are left out, so sending 0 and omitting the field are the same order for idempotency.

POST /v2/orders · items with shipping, tax and a discount (request body)
{
  "merchantReference": "YOUR-ORDER-1042",
  "currency": "USD",
  "amountMinor": 12999,
  "successUrl": "https://merchant.example/checkout/success",
  "cancelUrl": "https://merchant.example/checkout/cancel",
  "customer": {
    "fullName": "Thandi Nkosi",
    "email": "thandi@example.com"
  },
  "items": [
    {
      "name": "Everyday Tote",
      "quantity": 1,
      "unitPriceMinor": 7900
    },
    {
      "name": "Field Notes Set",
      "quantity": 2,
      "unitPriceMinor": 2500
    }
  ],
  "taxMinor": 1000,
  "shippingMinor": 599,
  "discountMinor": 1500
}

Check an order reference

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

Check whether a merchant reference is already used in the account tied to your API key before creating an order.

Required scope: orders_read

Authorization

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

Path parameters

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

Header parameters

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

Behavior

  • The response contains only exists; it never returns another order’s data.
  • References are checked within the account tied to your API key.
  • 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 accessible to your API key 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",
  "customer": {
    "fullName": "Thandi Nkosi",
    "email": "thandi@example.com"
  },
  "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 when you created it.

Required scope: orders_read

Authorization

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

Path parameters

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

Header parameters

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

Behavior

  • Unknown orders and references outside the account tied to your key 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",
  "customer": {
    "fullName": "Thandi Nkosi",
    "email": "thandi@example.com"
  },
  "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 payment transaction history

GET/v2/orders/{orderId}/payment-history

Read the merchant-safe payment summary and canonical on-chain transaction receipt records for an order.

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.
Payment-History-Cursorstringoptional
Optional 64-character hexadecimal nextCursor returned by the prior page. Use it to retrieve the next page; each page contains at most 50 receipts.

Behavior

  • If no payment has started, payment is null and receipts is empty. Otherwise each page contains at most 50 receipts; send the returned nextCursor as Payment-History-Cursor to read the next page.
  • Payment history remains readable after order cancellation, even though the normal order lookup then returns 404.
  • Receipt records identify transaction, received amount, credited amount and whether the transfer was late or revoked. Amounts are integer token base units.
  • This is transaction evidence, not a generated invoice or tax receipt.

Responses

200 OK · illustrative payment history. See errors and retry guidance.

Retrieve payment transaction history — 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)}/payment-history`, {
  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 payment history
{
  "orderId": "11111111-1111-4111-8111-111111111111",
  "payment": {
    "status": "paid",
    "assetId": "USDC",
    "networkId": "ethereum-sepolia",
    "amountBaseUnits": "1000000",
    "receivedBaseUnits": "1000000"
  },
  "receipts": [
    {
      "transactionId": "0x…",
      "amountBaseUnits": "1000000",
      "creditedBaseUnits": "1000000",
      "type": "deposit.eligible",
      "late": false
    }
  ]
}

Update order customer details

PATCH/v2/orders/{orderId}/customer

Correct the optional customer fullName or email saved on an order.

Required scope: orders_write

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.

Request body

fullNamestring | nulloptional
New full name, or null to remove it. Omit to leave unchanged.
emailstring | nulloptional
New email, or null to remove it. Omit to leave unchanged.

Behavior

  • Send at least one field. No Idempotency-Key is needed; the update is a replacement of the supplied fields.
  • Changes are refused with 409 customer_locked once the customer has confirmed a refund, so refund updates keep reaching that customer.
  • Use DELETE /v2/orders/{orderId}/customer to erase both fields, for example for a data-subject request.

Responses

200 OK · illustrative customer update. See errors and retry guidance.

Update order customer details — 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)}/customer`, {
  method: 'PATCH',
  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 customer update
{
  "orderId": "11111111-1111-4111-8111-111111111111",
  "customer": {
    "fullName": "Thandi Nkosi",
    "email": "thandi.nkosi@example.com"
  }
}

Remove order customer details

DELETE/v2/orders/{orderId}/customer

Erase the customer fullName and email saved on an order.

Required scope: orders_write

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 body is needed. Tyga Pay stops emailing this customer about the order.
  • Customer details are also cleared automatically 24 months after the order deadline once any refunds are final.

Responses

200 OK. See errors and retry guidance.

Remove order customer details — 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)}/customer`, {
  method: 'DELETE',
  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
{
  "cleared": true
}

Cancel an order

POST/v2/orders/{orderId}/cancel

Cancel an active order that has not been fully paid. Repeating cancellation is safe.

Required scope: orders_write

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

  • Send no request fields or Idempotency-Key. Repeating a successful cancellation returns the same result.
  • Paid, expired, or otherwise inactive orders cannot be cancelled. A cancellation never sends a refund or reverses a transfer.
  • If funds have already been received, the order is cancelled and the payment is marked review_required for manual reconciliation. Checkout links stop working after cancellation.

Responses

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

Cancel 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)}/cancel`, {
  method: 'POST',
  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 cancellation
{
  "cancelled": true,
  "paymentReviewRequired": false
}

Subscriptions

A subscription (in the API, a recurring agreement or mandate) lets you charge a customer again after their first payment, within limits they agreed to at checkout. You start one by creating a normal order with a recurring object. That order is the first payment; its response includes the mandateId.

Production renewals are collected by pay link

In production every renewal and charge is collected by pay link: the customer is emailed a checkout link and pays it like a normal order. Production renewals run twice a day, at 02:00 and 14:00 UTC.

  1. Create the first order with recurring and a customer.email, which is required for subscriptions because renewal links and notices are emailed. Send the customer to its checkoutUrl.
  2. At checkout the customer sees the agreement terms: the first payment, the most each renewal can be, how often, and when it ends. On networks that support wallet auto-charge they approve once in their wallet (a browser wallet, or a mobile wallet through WalletConnect); otherwise they pay the first order like any other.
  3. The first payment activates the agreement (mandate.active). From then on each renewal or charge is its own order, with its own checkout, payment, receipt, refunds and webhooks. Its chargeId is that order’s orderId. Scheduled renewals use the first order’s reference plus -R1, -R2 and so on; merchant charges use the reference you send.
  4. The subscription ends on its endsAt date, when you cancel it, when the customer revokes it from their wallet, or when a renewal cannot be collected after every attempt.
POST /v2/orders · a monthly subscription (request body)
{
  "merchantReference": "YOUR-SUB-1042",
  "currency": "USD",
  "amountMinor": 1500,
  "successUrl": "https://merchant.example/checkout/success",
  "cancelUrl": "https://merchant.example/checkout/cancel",
  "customer": {
    "fullName": "Thandi Nkosi",
    "email": "thandi@example.com"
  },
  "items": [
    {
      "name": "Monthly plan",
      "quantity": 1,
      "unitPriceMinor": 1500
    }
  ],
  "recurring": {
    "billing": "automatic",
    "amountMinor": 1500,
    "interval": "month",
    "intervalCount": 1,
    "endsAt": "2027-09-09T00:00:00.000Z"
  }
}

In the developer portal, recurring orders carry a Recurring or Renewal chip, the Agreements card lists one row per subscription, and each order’s Subscription tab shows its terms and a timeline of every payment, expected and paid.

Billing and collection

billing: automatic
Tyga Pay renews on the schedule for recurring.amountMinor each time. You do not call any API to renew. API charges are refused with 409 mandate_automatic.
billing: merchant
There is no schedule: you charge when you choose with POST /v2/mandates/{mandateId}/charges, for any amount within the limits. maxPerChargeMinor is required.

How renewals are collected is decided by the first payment and shown as collection:

auto_charge
Wallet auto-charge. The customer signed the agreement and a token spending limit for Tyga Pay’s collector contract, so each renewal is taken from their wallet automatically. The customer pays no gas and does not need to be online. Available on networks where the collector is deployed.
pay_link
Each renewal is a new order whose checkout link is emailed to the customer, who pays it like a normal order. Used on other networks, or when the customer did not approve a wallet.

Two limits protect the customer and are fixed for the life of the agreement. maxPerChargeMinor is the largest single charge, including customer fees; for automatic billing it defaults to the larger of the first payment and the renewal total. maxPerPeriodMinor is the most that can be charged in one billing period and defaults to maxPerChargeMinor. An API charge is refused with 409 mandate_limit_exceeded when it is above the per-charge limit, or when it would take the current period over the period limit. The period counts the first payment and any pending or successful charges; failed charges don’t count. Both limits are also part of the customer’s wallet approval, so a wallet auto-charge above either one fails with limit_exceeded.

Renewal schedule

interval and intervalCount set the period: day (1–366), week (1–52), month (1–12) or year (1). In sandbox you can also use minute (5–1440) for testing. The schedule is anchored to the moment of the first payment, in UTC: a monthly subscription paid on the 26th renews on the 26th of each month. Months and years keep that day of the month, or use the month’s last day when it is shorter, so one started on the 31st renews on 30 April and 28 or 29 February.

nextChargeAt is when the next renewal falls due. Renewals are collected by a scheduled run every hour in sandbox. A renewal is created at the first run after it falls due, so it can be up to an hour later than nextChargeAt.

endsAt is required. It must be after the first order expires and at most five years away. No charge is taken after it, and the agreement then becomes expired (mandate.expired). In the portal’s Create order form, the end date is required too.

Renewal attempts

Each scheduled renewal gets up to three attempts, one hour apart in sandbox. The renewal’s order stays open for every attempt left.

  1. Pay link. The customer is emailed the renewal link, then a reminder with a fresh link at each attempt. Each unpaid attempt sends mandate.charge.failed with failureReason: payment_not_received and the attempt number.
  2. Wallet auto-charge. The wallet is charged straight away. If it is refused for insufficient_balance or network_error, the customer is emailed to top up and the wallet is tried again at the next attempt. If the customer used up or removed the spending limit (allowance_exhausted), the agreement becomes reauthorization_required; if they revoked it in their wallet (mandate_revoked), it becomes revoked.
  3. Last attempt. If the third attempt is not paid, the agreement stops: it becomes cancelled with cancellationReason: renewal_failed, you receive mandate.cancelled and the customer is emailed that the subscription stopped.

While a renewal is still open, the next one waits, so a customer never holds two renewal links at once. Missed periods are not charged later; the schedule continues from the next due date.

Statuses and failure reasons

pending_authorization
Created; the first payment (and wallet approval, where offered) has not happened yet.
active
The first payment was made. Renewals or charges can be collected until endsAt.
reauthorization_required
The wallet spending limit is used up or was removed, so no further charge can be collected. Cancel it and ask the customer to subscribe again with a new order.
cancelled
Stopped by you (merchant_request), or by the schedule (renewal_failed) after the last renewal attempt was not paid or when a renewal, including customer fees, is above maxPerChargeMinor.
revoked
The customer revoked the agreement on chain from their wallet. Tyga Pay notices at the next charge attempt.
expired
The endsAt date passed.

A charge is pending, succeeded or failed. A failed charge has a failureReason: insufficient_balance, allowance_exhausted, limit_exceeded, mandate_revoked, mandate_cancelled (the subscription ended while the charge was open), mandate_expired, network_error, payment_not_received (a pay link was not paid in time) or order_cancelled (you cancelled the charge’s order). Treat unknown values as a failure; more may be added.

Cancelling a subscription

  1. From your system: POST /v2/mandates/{mandateId}/cancel. Renewals stop at once, any open renewal and its pay link are closed, and you receive mandate.cancelled. It is safe to repeat. Payments already made are not refunded; use refunds if you want to return one.
  2. From the developer portal: a workspace administrator opens the order’s Subscription tab, selects Cancel subscription and confirms with their passkey. It has the same effect as the API.
  3. Cancelling one order instead: cancelling a renewal’s order skips only that renewal (its charge fails with order_cancelled); the subscription carries on with the next one. Cancelling the unpaid first order means the subscription can never start, so it is cancelled as well.

Tyga Pay does not email the customer when you cancel, so tell them in your own product. Customers can ask you to cancel, revoke the agreement on chain from their wallet, or remove the token spending limit; you are told by mandate.revoked or mandate.reauthorization_required at the next charge attempt. Offer a clear cancel option in your product so customers do not need to do this themselves.

Emails and webhooks

With a customer email on the order, Tyga Pay emails renewal pay links and reminders, a notice when a wallet charge is refused, and a notice when the subscription stops, under the Subscription emails setting in Settings → Customers. Every paid charge sends the normal receipt under Payment receipts. Turn either off and you must send those messages yourself; with Subscription emails off, create a checkout session for the renewal’s order and send its checkoutUrl to the customer.

mandate.active
The first payment activated the agreement.
mandate.charge.succeeded
A renewal or charge was paid. Includes chargeId and, for wallet charges, transactionHash.
mandate.charge.failed
An attempt failed. Includes chargeId, failureReason and the attempt number. Scheduled renewals may follow with more attempts; an API charge has one attempt.
mandate.reauthorization_required
The wallet spending limit is used up or was removed.
mandate.revoked
The customer revoked the agreement in their wallet.
mandate.cancelled
The subscription was cancelled by you, from the portal, or after the last renewal attempt.
mandate.expired
The end date passed.

Subscription events carry the usual order fields of the order they relate to, plus mandateId and status (the agreement status, or the charge status for mandate.charge.*). Each charge’s order also sends the normal order events, such as order.paid. Select the events on your webhook endpoint, and read the agreement with GET /v2/mandates/{mandateId} before acting, since deliveries can repeat or arrive out of order.

Example mandate.charge.succeeded event · JSON (placeholder IDs)
{
  "id": "evt_…",
  "type": "mandate.charge.succeeded",
  "apiVersion": "v2",
  "createdAt": "2026-10-09T14:01:00.000Z",
  "data": {
    "orderId": "44444444-4444-4444-8444-444444444444",
    "merchantReference": "YOUR-SUB-1042-R1",
    "amountMinor": 1500,
    "currency": "USD",
    "mandateId": "33333333-3333-4333-8333-333333333333",
    "chargeId": "44444444-4444-4444-8444-444444444444",
    "status": "succeeded",
    "transactionHash": "0x…"
  }
}

Testing in sandbox

Sandbox renews every hour and allows minute intervals, and the portal’s Create order form offers an hourly option. A shorter period is still charged at most once per hourly run. On an order’s Subscription tab, Run next renewal takes the next step straight away: it ends the open pay-link attempt or creates the next renewal. Wallet auto-charge in sandbox uses test networks such as Ethereum Sepolia; in MetaMask, turn on Show test networks and select the network before approving. Each charge spends real test tokens, so give test subscriptions a short end date.

Retrieve a subscription

GET/v2/mandates/{mandateId}

Read a recurring agreement (subscription): its status, schedule, limits, next renewal and, once the customer approved a wallet, the payer address, asset and network.

Required scope: orders_read

Authorization

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

Path parameters

mandateIdstringrequired
The agreement ID returned as mandateId when you created the first order.

Header parameters

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

Behavior

  • status is one of pending_authorization, active, reauthorization_required, cancelled, revoked or expired. cancellationReason is merchant_request or renewal_failed.
  • nextChargeAt is when the next scheduled renewal falls due; it is collected at the first renewal run after that time. collection appears after the first payment: auto_charge or pay_link.
  • Unknown agreements and agreements of another merchant return 404.

Responses

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

Retrieve a subscription — 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.MANDATE_ID;
if (!resourceId) throw new Error('Set MANDATE_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/mandates/${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 subscription
{
  "mandateId": "33333333-3333-4333-8333-333333333333",
  "status": "active",
  "billing": "automatic",
  "collection": "auto_charge",
  "firstOrderId": "11111111-1111-4111-8111-111111111111",
  "currency": "USD",
  "amountMinor": 1500,
  "maxPerChargeMinor": 1500,
  "maxPerPeriodMinor": 1500,
  "interval": "month",
  "intervalCount": 1,
  "nextChargeAt": "2026-10-09T12:05:00.000Z",
  "expiresAt": "2027-09-09T12:00:00.000Z",
  "createdAt": "2026-09-09T12:00:00.000Z",
  "activatedAt": "2026-09-09T12:05:00.000Z",
  "payerAddress": "0x…",
  "assetId": "USDC",
  "networkId": "ethereum-sepolia"
}

Cancel a subscription

POST/v2/mandates/{mandateId}/cancel

Stop a subscription. No further renewals are charged, and any open renewal is closed with its pay link. Payments already made are not refunded.

Required scope: orders_write

Authorization

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

Path parameters

mandateIdstringrequired
The agreement to cancel.

Header parameters

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

Behavior

  • Send no request fields or Idempotency-Key. Cancelling an already cancelled subscription returns it unchanged; one that already ended for another reason returns 409 mandate_not_active.
  • Sends mandate.cancelled. Tyga Pay does not email the customer about a merchant cancellation, so let them know yourself.
  • Workspace administrators can also cancel from the order’s Subscription tab in the developer portal.

Responses

200 OK · illustrative cancelled subscription. See errors and retry guidance.

Cancel a subscription — 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.MANDATE_ID;
if (!resourceId) throw new Error('Set MANDATE_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/mandates/${encodeURIComponent(resourceId)}/cancel`, {
  method: 'POST',
  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 cancelled subscription
{
  "mandateId": "33333333-3333-4333-8333-333333333333",
  "status": "cancelled",
  "billing": "automatic",
  "collection": "auto_charge",
  "firstOrderId": "11111111-1111-4111-8111-111111111111",
  "currency": "USD",
  "amountMinor": 1500,
  "maxPerChargeMinor": 1500,
  "maxPerPeriodMinor": 1500,
  "interval": "month",
  "intervalCount": 1,
  "expiresAt": "2027-09-09T12:00:00.000Z",
  "createdAt": "2026-09-09T12:00:00.000Z",
  "activatedAt": "2026-09-09T12:05:00.000Z",
  "payerAddress": "0x…",
  "assetId": "USDC",
  "networkId": "ethereum-sepolia",
  "cancellationReason": "merchant_request",
  "endedAt": "2026-11-02T08:00:00.000Z"
}

Charge a subscription

POST/v2/mandates/{mandateId}/charges

Merchant billing only: charge an active subscription. Each charge is a normal order with its own payment, refunds and webhooks; its chargeId is that order’s orderId.

Required scope: orders_write

Authorization

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

Path parameters

mandateIdstringrequired
The merchant-billing agreement to charge.

Header parameters

x-api-keystringrequired
Your server-side merchant secret key.
Idempotency-Keystringrequired
Required. A retry with the same key returns the existing charge.

Request body

amountMinorintegerrequired
This charge’s merchant subtotal in cents. The customer total, including fees, must stay within maxPerChargeMinor, and together with this period’s pending and successful charges within maxPerPeriodMinor, or the request returns 409 mandate_limit_exceeded. Failed charges don’t count towards the period.
merchantReferencestringrequired
Your reference for this charge’s order, unique like any order reference.
itemsarrayoptional
Optional. What this charge is for, for example each subscription in a bundled bill: name, quantity and unitPriceMinor, as on an order. The pay link and receipt list them.
taxMinorintegeroptional
Optional tax in US cents. Requires items. Items plus taxMinor and shippingMinor, less discountMinor, must equal amountMinor, as on an order.
shippingMinorintegeroptional
Optional shipping in US cents. Requires items.
discountMinorintegeroptional
Optional discount in US cents, subtracted from the total. Requires items.

Behavior

  • Automatic-billing subscriptions refuse API charges with 409 mandate_automatic; Tyga Pay charges them on their schedule.
  • With wallet auto-charge, the approved wallet is charged straight away. With pay links, the customer is emailed a pay link (when Subscription emails are on) and the charge fails if it is not paid before its order expires.
  • Read the charge with GET /v2/mandates/{mandateId}/charges/{chargeId}, or follow mandate.charge.succeeded and mandate.charge.failed.

Responses

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

Charge a subscription — 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.MANDATE_ID;
if (!resourceId) throw new Error('Set MANDATE_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/mandates/${encodeURIComponent(resourceId)}/charges`, {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'sub-1042-charge-003',
  },
  body: JSON.stringify({
  "amountMinor": 1500,
  "merchantReference": "YOUR-ORDER-1042-C3"
}),
});
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 charge
{
  "chargeId": "44444444-4444-4444-8444-444444444444",
  "mandateId": "33333333-3333-4333-8333-333333333333",
  "orderId": "44444444-4444-4444-8444-444444444444",
  "merchantReference": "YOUR-ORDER-1042-C3",
  "amountMinor": 1500,
  "status": "pending",
  "createdAt": "2026-10-09T14:00:00.000Z"
}

Retrieve a subscription charge

GET/v2/mandates/{mandateId}/charges/{chargeId}

Read one charge of a subscription: a scheduled renewal or a merchant-billing charge.

Required scope: orders_read

Authorization

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

Path parameters

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

Header parameters

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

Request body

chargeIdstringrequired
The charge ID, which is also the charge’s orderId.

Behavior

  • status is pending, succeeded or failed. Renewals carry sequence (1 for the first renewal). attempt, maxAttempts and attemptEndsAt describe the current collection attempt while pending.
  • failureReason is one of insufficient_balance, allowance_exhausted, limit_exceeded, mandate_revoked, mandate_cancelled, mandate_expired, network_error, payment_not_received or order_cancelled.

Responses

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

Retrieve a subscription charge — 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 mandateId = process.env.MANDATE_ID;
if (!mandateId) throw new Error('Set MANDATE_ID');
const chargeId = process.env.CHARGE_ID;
if (!chargeId) throw new Error('Set CHARGE_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/mandates/${encodeURIComponent(mandateId)}/charges/${encodeURIComponent(chargeId)}`, {
  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 charge
{
  "chargeId": "44444444-4444-4444-8444-444444444444",
  "mandateId": "33333333-3333-4333-8333-333333333333",
  "orderId": "44444444-4444-4444-8444-444444444444",
  "merchantReference": "YOUR-ORDER-1042-R1",
  "amountMinor": 1500,
  "status": "succeeded",
  "sequence": 1,
  "createdAt": "2026-10-09T14:00:00.000Z",
  "transactionHash": "0x…",
  "completedAt": "2026-10-09T14:01:00.000Z"
}