IZIPAY Business API

Issue virtual cards for your users programmatically, fund them with crypto, and track everything in real time. A single REST API with predictable JSON responses and webhook events.

The API speaks JSON over HTTPS. Every request must be authenticated with a Bearer token. All responses share a consistent envelope with a top-level success flag.

Authentication

Authenticate every request by sending your secret API key in the Authorization header as a Bearer token.

Requests without a valid key return 401 INVALID_AUTH.

Request signing (optional, recommended)

Each key has a secret (izps_…, shown once when the key is created). Sign requests with it so that a leaked API key alone is useless. Enable it per key in the cabinet (API keys → Signing): while optional, a signature is verified only when sent; when required, unsigned requests return 401.

Example string to sign for GET /api/v1/cards?limit=50: "1725465600\nGET\n/api/v1/cards?limit=50\n" (empty body). Every signature is accepted once (replay protection). Keys created before September 2026 cannot enable signing — create a new key.

Quickstart

The typical flow to put a funded card in your user's hands is four steps:

Sandbox (testing)

Build and test your entire integration with zero real crypto and zero real cards. Use a test API key (starts with izpk_test_) — every call is mocked and isolated from production. When you're ready, switch to your live key (izpk_live_) and nothing else changes.

Card types

You can issue three kinds of cards. Pick one per request with the card_type field on POST /cards/issue (defaults to visa).

Issue a card

Creates a new card for one of your end-users and returns a crypto deposit address. The card is provisioned automatically once the payment is received on-chain. To pay from your account balance instead of crypto, send "pay_currency": "balance" — the card is charged instantly with no on-chain step. See Card types to choose between card and Apple Pay Mastercard.

Body parameters

Headers

Example · Apple Pay Mastercard, paid from balance

Get card details

Retrieves the current state of a card, including its masked number, balance, and issuance status.

List cards

Returns all cards you have issued, most recent first, with pagination.

Query parameters

Top up a card

Requests a balance top-up for an existing card. Returns a payment invoice, the same way card issuance does.

Body parameters

Return card balance

Moves unspent funds from a card back to your account balance. Use it before retiring a card, or to reclaim liquidity. The returned amount lands on your account balance and can be reused to issue or top up other cards.

Body parameters

Transfer between cards

Moves funds directly from one of your cards to another of your cards. No fee — the money never leaves the system, so this is free (unlike a return followed by a top-up, where the top-up commission applies). Both cards must be issued and belong to your account. {card_id} in the path is the source card.

Body parameters

Get transactions

Returns the spending and top-up history for a card, most recent first.

Verification codes — Apple Pay / Google Pay & 3-D Secure

When a cardholder adds an Apple Pay Mastercard to their wallet, the issuer sends a one-time verification code by email. This endpoint captures that code and returns it to you. Only Mastercard (Apple Pay / Google Pay) cards use codes — Visa cards do not.

Two steps. First POST to arm the card (tell us a code is expected), then add the card to the wallet, and finally receive the code by webhook or by polling GET.

1 · Arm — POST

2 · Retrieve — GET (poll)

3-D Secure — online purchases

This is different from wallet activation. When your cardholder pays at an online merchant that requires 3-D Secure verification, the issuer generates a one-time code for that specific transaction. IZIPAY captures it and pushes it to you automatically on the card.otp webhook — no arming needed. The 3-D Secure code is tied to the exact card, so it is always matched correctly. Just handle the webhook and show the code to your cardholder to complete the payment.

Get account balance

Returns summary statistics for your account: cards issued, total volume, and your current prepaid balance.

Fund the prepaid pool

Pre-pays for a batch of card issuances at your account's card price. Funding the pool up front means later card issuance is drawn from the pool at no extra on-chain step. Pass either a number of cards or a USD amount.

Body parameters

Exchange · list assets

Your account balance and prepaid pool are spent in USDT on Tron, Polygon or Ethereum only. Anything else you deposit — Bitcoin, Solana, USDC — has to be moved into one of those first. This endpoint lists what you currently hold and where it can go.

Balances are read from the blockchain, so this call takes a few seconds. Cache it rather than polling.

Not exchangeable: native TRX, ETH, BNB and POL sitting on your addresses. Those are gas we top up ourselves so sweeps can run — they are not part of your balance.

Exchange · quote

Minimum for a direction and an estimate of what you would receive. Every direction has its own minimum, set by our exchange partner, and it is often higher than a small balance — minimum_usd is returned alongside so you can tell at a glance.

Cost varies sharply by destination. Payouts in Tron carry a much larger fixed fee than Polygon — on small amounts the difference can be a third of the sum. Always quote before exchanging.

Exchange · create

Moves an asset from your address into USDT on the network you pick. There is no destination address field — funds always land on your own deposit address in the target network, so an exchange can never send money anywhere else.

Your USD balance does not change: this moves money between networks, it does not add or remove it. Only the exchange fee is charged, after completion, as a separate swap_cost entry.

Sending runs in the background — it needs gas, and energy rental on Tron — so the response returns immediately with pending. Poll GET /exchange/{order_ref} for progress.

Use X-Idempotency-Key. An exchange cannot be undone. With the key, a retried request returns the original order instead of creating a second one — without it, a network timeout on your side can cost you a duplicate exchange.

Exchange · status and history

Status of one exchange, or your history (newest first, ?limit= up to 200).

amount_received is what actually arrived; amount_estimated was the quote at creation. The two differ slightly — the difference is the exchange fee and is charged from your balance once, on completion.

Payment gateway · create a payment

The payment gateway lets you accept crypto from your own customers. Create a payment, show the returned address and amount to your customer, and receive funds (converted to USD) into your gateway balance — from which you can pay out. A flat gateway_fee_pct applies; see Gateway balance.

Body parameters

Payment gateway · list payments

Lists gateway payments, most recent first.

Query parameters

Payment gateway · get a payment

Retrieves the current status of a single gateway payment.

Payment gateway · balance

Your gateway balance (customer payments received, net of fees) and lifetime totals. This balance is what you draw from when creating a payout.

Payment gateway · create a payout

Withdraws funds from your gateway balance to a crypto address you control. The payout is queued and sent on-chain.

Body parameters

Payment gateway · list payouts

Lists your payouts, most recent first. Supports limit (1–200, default 50) and offset.

Webhooks

Register an HTTPS endpoint to receive event notifications as they happen. Events are delivered as POST requests with a JSON body and are retried with backoff if your endpoint does not return 2xx.

Event types

Verifying signatures

Each delivery includes an X-IZIPAY-Signature header — an HMAC-SHA256 of the raw request body, signed with your webhook secret. Always verify it before trusting an event.

List webhooks

Returns the webhook endpoints registered on your account.

Error codes

Errors return a non-2xx status and a JSON body with success: false and a machine-readable code.

Rate limits

Each account has a per-minute request limit and a daily card-issuance cap. Limits depend on your plan and can be raised on request.

Exceeding a limit returns 429 RATE_LIMIT. Need more headroom? Contact us.