Skip to main content
This guide takes you from zero to a funded virtual card in six steps, in the sandbox: free, open to everyone, and isolated from live money and real cards. You’ll need:
  • A sandbox account. Sign up at sandbox.fyatu.com with your work email; it is free. Every request is reviewed by a person before the sandbox opens, usually within one business day, and you are emailed when it is approved.
  • A sandbox API key with the accounts:read, cardholders:read, cardholders:write, cards:read and cards:write scopes, created in the sandbox portal under Developers → API Keys.
The two are separate systems: a sandbox key works only on the sandbox host, and nothing created there ever reaches live. Every example below uses the sandbox host; going live means changing the base URL and the key, and nothing else in your code.
Already a CaaS customer with a SANDBOX key created on platform.fyatu.com? That key keeps working on https://api.fyatu.com/api/v3.20, against your account’s own sandbox data. The public sandbox above is a separate system with its own sign-up and keys.

Step 1 — Check your key

Every endpoint needs the key, sent as Authorization: Bearer <key> (or X-API-Key: <key>).
cURL
Response
A 401 means the key is missing, mistyped, or used on the wrong host.

Step 2 — Pick a BIN

A card is issued on a BIN, which decides its network and what it supports. List the BINs on your account:
cURL
The response is shortened here; List BINs shows every field. Pick one with issuable: true and keep its binId. This guide uses TESTVISAV.

Step 3 — Create a cardholder

Every cardholder is identity-verified before a card can be issued to them. Send the identity document with the cardholder to start that verification at once:
The cardholder is created with kycStatus: "PENDING". Keep the cardholderId. You can also create the cardholder first and send the document later with POST /cardholders/{id}/kyc.

Step 4 — Wait for verification

In the sandbox, a cardholder with a document on file is decided about two seconds later. The last name chooses the outcome, so every path can be tested: “Complete” is what card issuance needs, so an approved cardholder can always be issued a card: a document image (kycDocument.frontUrl), the document number, the issuing country, and a phone. When any of them is missing the cardholder is REJECTED with a reason naming them; add them with PATCH /cardholders/{id} and resubmit with POST /cardholders/{id}/kyc. Option A — webhook (recommended). Subscribe to CARDHOLDER_KYC_APPROVED and CARDHOLDER_KYC_REJECTED and verify each delivery’s signature, see Signature Verification. Option B — poll the cardholder until kycStatus is APPROVED or REJECTED:
cURL
A card cannot be issued until kycStatus is APPROVED. In live, verification is a real identity check and can take longer; build for the webhook rather than for a fixed wait.

Step 5 — Issue a card

Response (201, abridged)
Issuance is asynchronous. A card can come back as CREATING, with no number yet, and become ACTIVE once provisioning completes; CARD_ISSUED is sent then. If the request times out, retry it with the same Idempotency-Key: you get the original card, never a second one. A retry sent while the first is still running is answered 409 IDEMPOTENCY_IN_PROGRESS; wait a moment and retry again.

Step 6 — Fund the card

Load money onto the card from your balance. Every sandbox starts with $10,000 of test funds, so there is nothing to deposit first.
cURL
Response
Funding is confirmed by the issuer after the response: status: PENDING means accepted, and the CARD_FUNDED webhook arrives once the money is on the card (or CARD_FUND_FAILED if it was not). Done. Jane has an active card with $75 on it. When she spends, you receive a TRANSACTION_PROCESSED webhook with the merchant, the amount and the outcome.

Before you go live

Going live is done from the sandbox portal’s Go-Live page: your business verification, the setup invoice, and your production account, created when the invoice is paid. Your sandbox data (cardholders, cards, keys, webhooks) stays in the sandbox; in production you create a live key, add your servers’ IP addresses to it, and register an HTTPS webhook. Then point your code at https://api.fyatu.com/api/v3.20 with the live key.

Next steps

Set Up Webhooks

Verify signatures and react to events instead of polling.

Explore All Endpoints

Request and response schemas for every endpoint.

Errors and Retries

What each error code means, and which ones are safe to retry.

Read Transactions

Card transaction history, filterable by card, cardholder, date and status.