Tranzo API

Overview

The Tranzo API allows merchants to create cryptocurrency payment invoices and retrieve invoice status information.

All requests and responses use JSON encoding.

Base URL:

https://tranzo.me

Authentication

All API requests require an API key.

You can generate and manage API keys from the Developers page in your Tranzo merchant account.

Provide the API key using the Authorization header:

Authorization: Bearer tranzo_ABC_XYZ

Keep your API key secure. Do not expose it in browser-side code, mobile applications, or public repositories.

Request Format

Requests that include a body must be sent as JSON.

Required header:

Content-Type: application/json

Idempotency

The optional Idempotency-Key header allows invoice creation requests to be safely retried without creating duplicate invoices.

Example:

Idempotency-Key: 8affc41a-4085-42e9-9ba3-e1ead46d1e24

Recommendations:

Use a unique UUID for each invoice creation request.
Reuse the same key only when retrying the exact same request.
If the same idempotency key is reused with different request parameters, an error is returned.
Although order_ref and Idempotency-Key may contain the same value, they serve different purposes and should generally be treated as independent identifiers.

Response Format

All responses are returned as JSON.

Successful response:

{
    "ok": true,
    "result": {
        "key": "value"
    }
}

Error response:

{
    "ok": false,
    "error": "error message"
}

Response fields:

Field	Type	Description
ok	boolean	Indicates whether the request succeeded.
result	object	Present when `ok` is true.
error	string	Present when `ok` is false.

Payment Object

A payment object represents a blockchain payment received for an invoice.

Field	Type	Description
id	string	Unique payment identifier.
network	string	Blockchain network.
tx_hash	string	Blockchain transaction hash.
asset	string	Payment asset.
gross_amount	string	Amount received before fees.
fee_amount	string	Processing fee amount.
net_amount	string	Amount credited after fees.
mined_at	string	Timestamp when the payment was confirmed on-chain.
detected_at	string	Timestamp when Tranzo detected the payment.
settlement_id	string	Settlement identifier. Null when not yet settled.

Invoice Object

An invoice object is returned when an invoice is created or retrieved.

Field	Type	Description
id	string	Unique invoice identifier.
status	string	Current invoice status.
asset	string	Asset associated with the invoice.
amount	string	Requested payment amount.
amount_received	string	Amount received on the leading network — the network with the highest payment sum. Payments are never summed across networks.
amount_remaining	string	Remaining amount required to complete payment on the leading network.
amount_overpaid	string	Amount the leading network received above the requested amount.
order_ref	string	Merchant order reference. Empty string when not provided.
return_url	string	Merchant return URL. Empty string when not provided.
payment_url	string	Hosted payment page URL.
created_at	string	Invoice creation timestamp in UTC.
expires_at	string	Invoice expiration timestamp in UTC.
paid_at	string	Timestamp when the invoice became fully paid. Null when not yet paid.
payments	array	Array of Payment objects.

Invoice status values:

Status	Description
pending	No single network has yet received the full invoice amount.
paid	One network has received the full invoice amount.

Invoice Expiration

Invoice expiration controls whether payment instructions are displayed on the hosted payment page.

After an invoice reaches its expiration time, the hosted payment page no longer displays payment information. However, the invoice remains in the pending state and may still receive payments.

Late payments may still be accepted and processed, for example when funds are delayed by exchange processing or blockchain confirmation timing.

Fulfillment Guidelines

When accepting cryptocurrency payments, merchants are responsible for ensuring that goods or services are delivered only after a successful payment has been verified.

Verify Payment Status

Do not rely on customer redirects, browser callbacks, or other client-side events as proof of payment.

Before fulfilling an order, retrieve the invoice using the Get Invoice Status endpoint and verify that:

The invoice exists.
The invoice status is paid.
The invoice corresponds to the expected order in your system.

Ensure Idempotent Fulfillment

Merchants must ensure that invoice fulfillment is idempotent.

An invoice should only be fulfilled once, even if the same invoice is observed multiple times due to customer redirects, request retries, webhook deliveries, manual reconciliation processes, or application errors.

Use the invoice ID as the unique fulfillment identifier and record fulfilled invoices in your system. If the same invoice is encountered again, do not perform fulfillment a second time.

Use `order_ref` for Order Correlation

The optional order_ref field can be used to associate invoices with orders in your system.

Do not assume that order_ref values are unique unless your application enforces uniqueness.

Endpoints

Create Invoice

Creates a new invoice.

Request

POST /api/v1/invoices

Parameters

Parameter	Required	Description
asset	Yes	Invoice asset. Currently the only supported value is `USDT`.
amount	Yes	Invoice amount encoded as a string. Use a period (`.`) as the decimal separator and do not include thousands separators. Minimum value is `0.05`. Up to 6 decimal places are supported.
order_ref	No	Merchant order reference. Maximum length is 64 characters. Allowed characters are `A-Z`, `a-z`, `0-9`, `_`, and `-`.
return_url	No	Customer return URL. Must begin with `https://` and use a valid domain name. Maximum length is 128 characters.
expires_in	No	Invoice lifetime in seconds. Defaults to `86400` when omitted or set to `0`. Maximum value is 30 days.

The invoice is payable on every blockchain network enabled for your merchant whose limits the amount satisfies. Networks with a higher minimum (for example Tron, minimum 20 USDT, reflecting its higher network fees, or BNB Smart Chain, minimum 2 USDT) are simply left off invoices below that amount — the invoice is still created and payable on the remaining networks. If none of your merchant's enabled networks accepts the amount (for example 0.05 on a Tron-only merchant), invoice creation fails with an amount error. Customers pick the network on the payment page. An invoice must be fully paid on a single network — payments are never summed across networks — and once a payment lands, the payment page only offers the network(s) the customer already paid on, each showing its own remaining amount.

Optional Headers

Header	Description
Idempotency-Key	Optional idempotency key used to prevent duplicate invoice creation. Maximum length is 64 characters.

Example Request

curl -X POST https://tranzo.me/api/v1/invoices \
  -H "Authorization: Bearer tranzo_TKkpDR9KQwz9bTMNCBWG9c_5moy4vvqhWoKKRs9BHVVzoSgbDqHXMMXheAocCLKTr4o" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8affc41a-4085-42e9-9ba3-e1ead46d1e24" \
  -d '{
    "asset": "USDT",
    "amount": "19.95",
    "order_ref": "ORDER-12345",
    "return_url": "https://example.com/check"
  }'

Example Response

{
    "ok": true,
    "result": {
        "id": "Dz3DuMDb7Xx9EM89Eeay2M",
        "status": "pending",
        "asset": "USDT",
        "amount": "19.95",
        "amount_received": "0",
        "amount_remaining": "19.95",
        "amount_overpaid": "0",
        "order_ref": "ORDER-12345",
        "return_url": "https://example.com/check",
        "payment_url": "https://tranzo.me/Dz3DuMDb7Xx9EM89Eeay2M",
        "created_at": "2026-06-17T08:24:51.385418Z",
        "expires_at": "2026-06-18T08:24:51.385418Z",
        "paid_at": null,
        "payments": []
    }
}

Notes

After creating an invoice, redirect the customer to the returned payment_url.

If a return_url was provided, the customer is redirected back after a successful payment.

The following query parameters are appended:

invoice_id
order_ref

Do not treat the redirect as proof of payment.

Always query the invoice status endpoint and verify that the invoice status is paid before delivering goods or services.

For payment verification and order fulfillment recommendations, see Fulfillment Guidelines.

Get Invoice Status

Retrieves an invoice and its associated payments.

Request

GET /api/v1/invoices/{invoice_id}

Path Parameters

Parameter	Description
invoice_id	Invoice identifier returned when the invoice was created.

Example Request

curl https://tranzo.me/api/v1/invoices/Dz3DuMDb7Xx9EM89Eeay2M \
  -H "Authorization: Bearer tranzo_TKkpDR9KQwz9bTMNCBWG9c_5moy4vvqhWoKKRs9BHVVzoSgbDqHXMMXheAocCLKTr4o"

Example Response

{
    "ok": true,
    "result": {
        "id": "Dz3DuMDb7Xx9EM89Eeay2M",
        "status": "paid",
        "asset": "USDT",
        "amount": "19.95",
        "amount_received": "19.95",
        "amount_remaining": "0",
        "amount_overpaid": "0",
        "order_ref": "ORDER-12345",
        "return_url": "https://example.com/check",
        "payment_url": "https://tranzo.me/Dz3DuMDb7Xx9EM89Eeay2M",
        "created_at": "2026-06-17T08:24:51.385418Z",
        "expires_at": "2026-06-18T08:24:51.385418Z",
        "paid_at": "2026-06-17T08:25:36.931885Z",
        "payments": [
            {
                "id": "7vSk8CcQ7rkzKuDTA1YhnH",
                "network": "TON",
                "tx_hash": "62263f1b20f09717e521e1fa14765ca3244f465e4b96aef8d9623cf9efbc2c44",
                "asset": "USDT",
                "gross_amount": "19.95",
                "fee_amount": "0.1995",
                "net_amount": "19.7505",
                "mined_at": "2026-06-17T08:25:36.453792Z",
                "detected_at": "2026-06-17T08:25:36.931885Z",
                "settlement_id": null
            }
        ]
    }
}

Notes

An invoice becomes paid when the total amount received is greater than or equal to the requested invoice amount.

Overpayments are included in settlement processing and are settled in the next settlement batch.

Underpayments may also be settled in a future batch unless they are below the minimum supported invoice amount, in which case they may be treated as dust to reduce network fees.

Use order_ref to associate invoices with orders in your own system.

For order fulfillment, always rely on the invoice status returned by this endpoint rather than customer redirects.

Tranzo API

Overview

Authentication

Request Format

Idempotency

Response Format

Payment Object

Invoice Object

Invoice Expiration

Fulfillment Guidelines

Verify Payment Status

Ensure Idempotent Fulfillment

Use order_ref for Order Correlation

Endpoints

Create Invoice

Request

Parameters

Optional Headers

Example Request

Example Response

Notes

Get Invoice Status

Request

Path Parameters

Example Request

Example Response

Notes

Use `order_ref` for Order Correlation