# FYATU API Docs

## Docs

- [Fyatu Developer Docs](https://docs.fyatu.com/home.md): API references, integration guides, and webhook documentation. Select the platform you're building on.
- [Introduction](https://docs.fyatu.com/v3/documentation/introduction.md): Fyatu API v3 — issue virtual prepaid cards, collect payments, and send payouts programmatically via REST.
- [Quick Start](https://docs.fyatu.com/v3/documentation/quickstart.md): Get started with Fyatu's card issuing API in under 5 minutes. Authenticate, create a cardholder, issue your first virtual Mastercard, and set up webhooks.
- [Authentication](https://docs.fyatu.com/v3/documentation/authentication.md): JWT-based authentication for Fyatu API v3. Generate access tokens with your appId and secretKey. Tokens valid for 24 hours with refresh and revoke support.
- [Error Handling](https://docs.fyatu.com/v3/documentation/errors.md): Fyatu API error codes and HTTP status codes. Handle validation errors, insufficient balance, invalid tokens, and provider failures in your card issuing integration.
- [Payments](https://docs.fyatu.com/v3/documentation/concepts/payments/overview.md): Accept payments via collections, send money via payouts, and issue refunds — Fyatu's payment system for businesses that need to move money programmatically.
- [Collections](https://docs.fyatu.com/v3/documentation/concepts/payments/collections.md): Accept payments from Fyatu users via a hosted checkout page. Create a session, redirect your customer, and receive webhook confirmation.
- [Payouts](https://docs.fyatu.com/v3/documentation/concepts/payments/payouts.md): Send money from your business wallet to any Fyatu account holder. Verify the recipient, create a payout, and funds transfer instantly.
- [Refunds](https://docs.fyatu.com/v3/documentation/concepts/payments/refunds.md): Return money from a completed collection back to the original payer. Choose full or partial — each collection can only be refunded once.
- [Cardholders](https://docs.fyatu.com/v3/documentation/concepts/cardholders/overview.md): Create cardholders, complete KYC verification, and issue virtual cards. A cardholder must be KYC-verified before cards can be issued.
- [KYC Verification](https://docs.fyatu.com/v3/documentation/concepts/cardholders/kyc.md): How cardholder identity verification works. Behaviour depends on your business's KYC mode: Managed (default), Shared, or Minimal (No-KYC).
- [Cards Overview](https://docs.fyatu.com/v3/documentation/concepts/cards/overview.md): Virtual Mastercard and Visa prepaid cards — types, lifecycle, statuses, and how decline count and auto-suspension work.
- [Card Products](https://docs.fyatu.com/v3/documentation/concepts/cards/products.md): Each card is issued from a product that determines its brand, currency, spending limits, and features. Learn how to discover and select the right product.
- [Card Operations](https://docs.fyatu.com/v3/documentation/concepts/cards/operations.md): Create, fund, freeze, terminate, and replace cards. Retrieve card transactions and handle webhook events for the full card lifecycle.
- [Card Fees](https://docs.fyatu.com/v3/documentation/concepts/cards/fees.md): Fee structure for card issuing — issuance, maintenance, funding, unloading, and per-transaction fees. Retrieve your current rates via the pricing endpoint.
- [API Reference](https://docs.fyatu.com/v3/api-reference/overview.md): Complete REST API reference for Fyatu v3 — card issuing, payment collections, payouts, refunds, and webhook configuration endpoints.
- [Generate Token](https://docs.fyatu.com/v3/api-reference/auth/token.md): Generate a JWT access token for Fyatu API v3 using client credentials. POST /auth/token with appId and secretKey.
- [Refresh Token](https://docs.fyatu.com/v3/api-reference/auth/refresh.md): Refresh an expiring Fyatu API access token without re-authenticating. POST /auth/refresh.
- [Revoke Token](https://docs.fyatu.com/v3/api-reference/auth/revoke.md): Revoke an active Fyatu API access token to invalidate a session. POST /auth/revoke.
- [Get Pricing](https://docs.fyatu.com/v3/api-reference/account/pricing.md): Retrieve current Fyatu API pricing and fee schedule — card issuance fees, funding fees, and transaction costs. GET /account/pricing.
- [Get Wallet](https://docs.fyatu.com/v3/api-reference/account/wallet.md): Get your Fyatu business wallet balance and currency details. GET /account/wallet.
- [Get Transactions](https://docs.fyatu.com/v3/api-reference/account/transactions.md): List all business wallet transactions with category, status, and fee data. GET /account/transactions.
- [Get Transaction](https://docs.fyatu.com/v3/api-reference/account/transaction.md): Get details of a specific business wallet transaction by ID — category, amount, fee, status, and description. GET /account/transactions/{id}.
- [Get Statement](https://docs.fyatu.com/v3/api-reference/account/statement.md): Get the last 100 ledger entries for your business account with running balance snapshots. GET /account/statement.
- [Get Invoices](https://docs.fyatu.com/v3/api-reference/account/invoices.md): List your business billing invoices — subscription charges, outstanding amounts, and payment status. GET /account/invoices.
- [Request Withdrawal](https://docs.fyatu.com/v3/api-reference/account/withdraw.md): Request a withdrawal from your Fyatu business wallet to a registered address. POST /account/withdraw.
- [Generate Deposit Address](https://docs.fyatu.com/v3/api-reference/account/deposit-address.md): Generate a USDT deposit address to fund your Fyatu business wallet. POST /account/deposit-address.
- [Register Withdrawal Address](https://docs.fyatu.com/v3/api-reference/account/withdrawal-address.md): Register a withdrawal destination address for your Fyatu business wallet. POST /account/withdrawal-address.
- [Create Collection](https://docs.fyatu.com/v3/api-reference/collections/create.md): Create a payment collection session with hosted checkout. Accept payments from customers with callback and webhook support. POST /collections.
- [List Collections](https://docs.fyatu.com/v3/api-reference/collections/list.md): List all payment collections with pagination and status filtering. GET /collections.
- [Get Collection](https://docs.fyatu.com/v3/api-reference/collections/get.md): Get details of a specific payment collection — amount, status, checkout URL, and metadata. GET /collections/{id}.
- [Verify Account](https://docs.fyatu.com/v3/api-reference/payouts/verify-account.md): Verify a Fyatu recipient account before sending a payout. Validate account existence and details. POST /payouts/verify-account.
- [Create Payout](https://docs.fyatu.com/v3/api-reference/payouts/create.md): Create an instant payout to a Fyatu user. Specify amount, recipient, and reference for reconciliation. POST /payouts.
- [List Payouts](https://docs.fyatu.com/v3/api-reference/payouts/list.md): List all payouts with pagination and status filtering — initiated, completed, or failed. GET /payouts.
- [Get Payout](https://docs.fyatu.com/v3/api-reference/payouts/get.md): Get details of a specific payout — amount, recipient, charges, net amount, and status. GET /payouts/{id}.
- [List Cardholders](https://docs.fyatu.com/v3/api-reference/cardholders/list.md): List all cardholders in your Fyatu card program with pagination and KYC status filtering. GET /cardholders.
- [Create Cardholder](https://docs.fyatu.com/v3/api-reference/cardholders/create.md): Create a new cardholder for virtual card issuing. Submit personal details and start issuing cards immediately. POST /cardholders.
- [Get Cardholder](https://docs.fyatu.com/v3/api-reference/cardholders/get.md): Get cardholder details including KYC status, personal information, and associated cards. GET /cardholders/{id}.
- [Update Cardholder](https://docs.fyatu.com/v3/api-reference/cardholders/update.md): Update cardholder personal information, metadata, or status. PATCH /cardholders/{id}.
- [Delete Cardholder](https://docs.fyatu.com/v3/api-reference/cardholders/delete.md): Delete a cardholder and terminate all associated cards. This action is permanent. DELETE /cardholders/{id}.
- [Initiate KYC Verification](https://docs.fyatu.com/v3/api-reference/cardholders/kyc-session.md): Start identity verification for a cardholder via automated ID + liveness check. Returns a verification URL. POST /cardholders/{id}/kyc/session.
- [Submit KYC Documents](https://docs.fyatu.com/v3/api-reference/cardholders/kyc.md): Submit pre-verified KYC documents for a cardholder via Shared KYC. Available only for businesses with Shared KYC enabled. POST /cardholders/{id}/kyc.
- [List Card Products](https://docs.fyatu.com/v3/api-reference/cards/products.md): List available card products — returns productId, brand, currency, fees, and availability flags. Use productId when creating a card. GET /cards/products.
- [List Cards](https://docs.fyatu.com/v3/api-reference/cards/list.md): List all issued virtual and prepaid cards with pagination — filter by status, cardholder, or product. GET /cards.
- [Create Card](https://docs.fyatu.com/v3/api-reference/cards/create.md): Issue a new virtual Mastercard or Visa prepaid card programmatically. Specify cardholder, amount, and product. POST /cards.
- [Get Card Details](https://docs.fyatu.com/v3/api-reference/cards/get.md): Get full card details — masked number, expiry, brand, balance, status, and spending limits. GET /cards/{cardId}.
- [Terminate Card](https://docs.fyatu.com/v3/api-reference/cards/delete.md): Permanently terminate a virtual card. Remaining balance is returned to your wallet. DELETE /cards/{cardId}.
- [Get Card Transactions](https://docs.fyatu.com/v3/api-reference/cards/transactions.md): Get transaction history for a specific card — merchant name, amount, status, and timestamps. GET /cards/{cardId}/transactions.
- [Download Card Statement](https://docs.fyatu.com/v3/api-reference/cards/statement.md): Download a PDF statement for a card with transaction history, business branding, and card details. GET /cards/{id}/statement.
- [Fund Card](https://docs.fyatu.com/v3/api-reference/cards/fund.md): Add funds to an existing virtual card. Minimum $5, fee applies per pricing. POST /cards/{cardId}/fund.
- [Unload Card](https://docs.fyatu.com/v3/api-reference/cards/unload.md): Withdraw remaining balance from a card back to your business wallet. POST /cards/{cardId}/unload.
- [Freeze Card](https://docs.fyatu.com/v3/api-reference/cards/freeze.md): Temporarily freeze a card to block all transactions. Card can be unfrozen later. POST /cards/{cardId}/freeze.
- [Unfreeze Card](https://docs.fyatu.com/v3/api-reference/cards/unfreeze.md): Reactivate a previously frozen card to resume transactions. POST /cards/{cardId}/unfreeze.
- [Replace Card](https://docs.fyatu.com/v3/api-reference/cards/replace.md): Replace a card with a new one — same cardholder, new card number. POST /cards/{cardId}/replace.
- [Webhook Signature Verification](https://docs.fyatu.com/v3/webhooks/signature-verification.md): How to verify that webhook events are genuinely from Fyatu using HMAC-SHA256 signatures. Examples in Node.js, PHP, Python, Go, Ruby, Java, and C#.
- [Get Webhook Configuration](https://docs.fyatu.com/v3/webhooks/get.md): Retrieve your current webhook configuration — endpoint URL, enabled events, and signing secret status. GET /webhooks.
- [Update Webhook URL](https://docs.fyatu.com/v3/webhooks/update.md): Set or update your webhook endpoint URL for receiving real-time event notifications. PUT /webhooks.
- [Regenerate Webhook Secret](https://docs.fyatu.com/v3/webhooks/regenerate-secret.md): Generate a new HMAC-SHA256 webhook signing secret. Previous secret is immediately invalidated. POST /webhooks/regenerate-secret.
- [Test Webhook](https://docs.fyatu.com/v3/webhooks/test.md): Send a test webhook event to verify your endpoint is receiving and processing notifications correctly. POST /webhooks/test.
- [Card Created](https://docs.fyatu.com/v3/webhooks/webhook-events/card-created.md): Sent when a new virtual card is successfully issued to a cardholder.
- [Card Creation Failed](https://docs.fyatu.com/v3/webhooks/webhook-events/card-failed.md): Sent when a card issuance request fails. The held balance is released automatically.
- [Card Funded](https://docs.fyatu.com/v3/webhooks/webhook-events/card-funded.md): Sent when funds are successfully added to a card.
- [Card Funding Failed](https://docs.fyatu.com/v3/webhooks/webhook-events/card-funding-failed.md): Sent when a card funding attempt fails. Any held amount is released automatically — no funds are deducted.
- [Card Unloaded](https://docs.fyatu.com/v3/webhooks/webhook-events/card-unloaded.md): Sent when funds are successfully withdrawn from a card back to your business wallet.
- [Card Unloading Failed](https://docs.fyatu.com/v3/webhooks/webhook-events/card-unloading-failed.md): Sent when a card unloading attempt fails. The card balance remains unchanged and no funds are credited to your wallet.
- [Card Transaction Approved](https://docs.fyatu.com/v3/webhooks/webhook-events/card-transaction-approved.md): Sent when a card charge is approved at the point of sale or online, and also when fee charges (cross-border, decline fees) are applied to a business card.
- [Card Transaction Declined](https://docs.fyatu.com/v3/webhooks/webhook-events/card-transaction-declined.md): Sent when a card purchase is declined at the point of sale or online.
- [Card Transaction Reversed](https://docs.fyatu.com/v3/webhooks/webhook-events/card-transaction-reversed.md): Sent when a previously approved card authorization is voided or reversed by the merchant.
- [Card Transaction Cross-border Fee](https://docs.fyatu.com/v3/webhooks/webhook-events/card-transaction-cross-border-fee.md): Sent when a cross-border fee is charged on a card transaction made in a foreign currency or at an international merchant.
- [Card Transaction Decline Fee (Domestic)](https://docs.fyatu.com/v3/webhooks/webhook-events/card-transaction-decline-fee-domestic.md): Sent when a domestic decline fee is charged after a card transaction is declined at a domestic merchant.
- [Card Transaction Decline Fee (International)](https://docs.fyatu.com/v3/webhooks/webhook-events/card-transaction-decline-fee-international.md): Sent when an international decline fee is charged after a card transaction is declined at an international merchant.
- [Card Frozen](https://docs.fyatu.com/v3/webhooks/webhook-events/card-frozen.md): Sent when a card is frozen, either via API or automatically by the provider (fraud, inactivity).
- [Card Unfrozen](https://docs.fyatu.com/v3/webhooks/webhook-events/card-unfrozen.md): Sent when a frozen card is reactivated and becomes usable again.
- [Card Terminated](https://docs.fyatu.com/v3/webhooks/webhook-events/card-terminated.md): Sent when a card is permanently terminated. Any remaining balance is automatically refunded to your business wallet.
- [Card Termination Refund](https://docs.fyatu.com/v3/webhooks/webhook-events/card-termination-refund.md): Sent when a terminated card's remaining balance is refunded to your business wallet.
- [Card Post-Termination Refund](https://docs.fyatu.com/v3/webhooks/webhook-events/card-termination-refund-post.md): Sent when funds arrive on an already-terminated card and are refunded to your business wallet.
- [Card Replaced](https://docs.fyatu.com/v3/webhooks/webhook-events/card-replaced.md): Sent when a card is replaced with a new one. The cardId remains the same; last4 and expiry change.
- [Card Tokenization OTP](https://docs.fyatu.com/v3/webhooks/webhook-events/card-tokenization-otp.md): Sent when a one-time code is generated for adding a card to a digital wallet (Apple Pay, Google Pay, Samsung Pay). Display this code to the cardholder immediately — it expires in minutes.
- [Card 3DS OTP](https://docs.fyatu.com/v3/webhooks/webhook-events/card-3ds-otp.md): Sent when a 3DS authentication code is generated during an online purchase. Forward this code to the cardholder immediately — it expires within minutes.
- [Card Maintenance Fee Paid](https://docs.fyatu.com/v3/webhooks/webhook-events/card-maintenance-fee-paid.md): Sent when the monthly card maintenance fee is automatically debited from a card.
- [Card Negative Balance](https://docs.fyatu.com/v3/webhooks/webhook-events/card-negative-balance.md): Sent when a card's balance drops below zero. The outstanding amount is recovered from your business wallet.
- [Card Delete Warning](https://docs.fyatu.com/v3/webhooks/webhook-events/card-delete-warning.md): Sent when a card is scheduled for deletion due to inactivity. Making a transaction before the deletion date will cancel it.
- [Cardholder Created](https://docs.fyatu.com/v3/webhooks/webhook-events/cardholder-created.md): Sent when a new cardholder is created in your app.
- [Cardholder KYC Submitted](https://docs.fyatu.com/v3/webhooks/webhook-events/cardholder-kyc-submitted.md): Sent when a cardholder submits KYC documents for verification.
- [Cardholder KYC Approved](https://docs.fyatu.com/v3/webhooks/webhook-events/cardholder-kyc-approved.md): Sent when a cardholder's KYC verification is approved.
- [Cardholder KYC Rejected](https://docs.fyatu.com/v3/webhooks/webhook-events/cardholder-kyc-rejected.md): Sent when a cardholder's KYC verification is rejected.
- [Collection Initiated](https://docs.fyatu.com/v3/webhooks/webhook-events/collection-initiated.md): Sent when a new payment collection is created.
- [Collection Received](https://docs.fyatu.com/v3/webhooks/webhook-events/collection-received.md): Sent when a payment is successfully received.
- [Collection Failed](https://docs.fyatu.com/v3/webhooks/webhook-events/collection-failed.md): Sent when a collection fails to process.
- [Collection Expired](https://docs.fyatu.com/v3/webhooks/webhook-events/collection-expired.md): Sent when a collection expires without payment.
- [Payout Initiated](https://docs.fyatu.com/v3/webhooks/webhook-events/payout-initiated.md): Sent when a payout request is created.
- [Payout Completed](https://docs.fyatu.com/v3/webhooks/webhook-events/payout-completed.md): Sent when a payout is successfully sent.
- [Payout Failed](https://docs.fyatu.com/v3/webhooks/webhook-events/payout-failed.md): Sent when a payout fails.
- [Refund Initiated](https://docs.fyatu.com/v3/webhooks/webhook-events/refund-initiated.md): Sent when a refund request is created.
- [Refund Completed](https://docs.fyatu.com/v3/webhooks/webhook-events/refund-completed.md): Sent when a refund is successfully processed.
- [Refund Failed](https://docs.fyatu.com/v3/webhooks/webhook-events/refund-failed.md): Sent when a refund fails.

## OpenAPI Specs

- [openapi](https://docs.fyatu.com/v3.20/openapi.json)

## Optional

- [Website](https://fyatu.com)