- 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:readandcards:writescopes, 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 asAuthorization: Bearer <key> (or X-API-Key: <key>).
cURL
Response
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
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: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
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
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 athttps://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.

