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
/v2/ordersCreate 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-Typerequiredapplication/jsonIdempotency-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.
// 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.{
"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.
{
"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
/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.
// 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.{
"exists": false
}Retrieve an order
/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.
// 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.{
"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
/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.
// 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.{
"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
/v2/orders/{orderId}/payment-historyRead 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.
// 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.{
"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
/v2/orders/{orderId}/customerCorrect 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.
// 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.{
"orderId": "11111111-1111-4111-8111-111111111111",
"customer": {
"fullName": "Thandi Nkosi",
"email": "thandi.nkosi@example.com"
}
}Remove order customer details
/v2/orders/{orderId}/customerErase 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.
// 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.{
"cleared": true
}Cancel an order
/v2/orders/{orderId}/cancelCancel 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.
// 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.{
"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.
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.
- Create the first order with
recurringand acustomer.email, which is required for subscriptions because renewal links and notices are emailed. Send the customer to itscheckoutUrl. - 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.
- 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. ItschargeIdis that order’sorderId. Scheduled renewals use the first order’s reference plus-R1,-R2and so on; merchant charges use the reference you send. - The subscription ends on its
endsAtdate, when you cancel it, when the customer revokes it from their wallet, or when a renewal cannot be collected after every attempt.
{
"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.amountMinoreach time. You do not call any API to renew. API charges are refused with409 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.maxPerChargeMinoris 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.
- 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.failedwithfailureReason: payment_not_receivedand theattemptnumber. - Wallet auto-charge. The wallet is charged straight away. If it is refused for
insufficient_balanceornetwork_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 becomesreauthorization_required; if they revoked it in their wallet (mandate_revoked), it becomesrevoked. - Last attempt. If the third attempt is not paid, the agreement stops: it becomes
cancelledwithcancellationReason: renewal_failed, you receivemandate.cancelledand 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 abovemaxPerChargeMinor. revoked- The customer revoked the agreement on chain from their wallet. Tyga Pay notices at the next charge attempt.
expired- The
endsAtdate 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
- From your system:
POST /v2/mandates/{mandateId}/cancel. Renewals stop at once, any open renewal and its pay link are closed, and you receivemandate.cancelled. It is safe to repeat. Payments already made are not refunded; use refunds if you want to return one. - 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.
- 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
chargeIdand, for wallet charges,transactionHash. mandate.charge.failed- An attempt failed. Includes
chargeId,failureReasonand theattemptnumber. 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.
{
"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
/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.
// 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.{
"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
/v2/mandates/{mandateId}/cancelStop 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.
// 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.{
"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
/v2/mandates/{mandateId}/chargesMerchant 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.
// 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.{
"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
/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.
// 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.{
"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"
}