Payins

Overview

Payins fund your Zuba balance. These deposit methods are live today:

NGN bank transfers: transfers into your fixed virtual account are credited automatically; dynamic per-deposit virtual accounts are also available via the API.
EUR & GBP bank transfers: transfers into your dedicated named accounts (EUR IBAN via SEPA, GBP sort code + account number via Faster Payments) are credited automatically.
USD bank deposits: transfers into your managed USD deposit account are credited automatically.
XOF & XAF bank transfers: receiving accounts fund your trade-desk orders. Upload evidence only when the returned settlement has requirements.proofOfPayment: true; other orders reconcile without a proof upload.
Crypto deposits: provision an on-chain address and receive USDC or USDT, credited on confirmation. Live accounts apply a per-transfer minimum, below which a transfer is not credited.

Zuba records each accepted deposit in the ledger and credits your balance once funds are received.

NGN Deposits

Fixed virtual account

Your workspace has a dedicated NGN virtual account in your business name (Zuba {Merchant Name}). Transfers sent to it are credited to your NGN balance automatically. No create call is required. Fetch the details with GET /v1/virtual-accounts/me:

Get My Virtual Account Response

{
  "currency": "NGN",
  "accountNumber": "8012345678",
  "accountName": "Zuba Acme Ltd",
  "bankName": "Wema Bank",
  "status": "active"
}

The account details are also shown in the dashboard. Contact your account manager if no virtual account has been provisioned yet.

Dynamic virtual accounts (per deposit)

Alternatively, create a deposit with POST /v1/deposits to receive one-off virtual account details for a specific sender. NGN deposits created this way require the sender’s firstName, lastName, email, and phoneNumber to generate the virtual account:

curl -X POST "https://api.sandbox.zuba.com/v1/deposits" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "50000.00",
    "currency": "NGN",
    "clientRef": "DEPOSIT-REF-001",
    "description": "Account top-up",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phoneNumber": "+2348012345678"
  }'

const deposit = await fetch('https://api.sandbox.zuba.com/v1/deposits', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: '50000.00',
    currency: 'NGN',
    clientRef: 'DEPOSIT-REF-001',
    description: 'Account top-up',
    firstName: 'John',
    lastName: 'Doe',
    email: 'john.doe@example.com',
    phoneNumber: '+2348012345678'
  })
});

const data = await deposit.json();

The response contains the virtual account details to display to the sender:

Create Deposit Response (NGN)

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "method": "manual_deposit",
  "amount": "50000.00",
  "currency": "NGN",
  "status": "pending",
  "iban": "3234567890",
  "bic": "Example Bank",
  "reference": "DEP-REF-1706510200000",
  "description": "Account top-up",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "providerReference": "DEP-REF-1706510200000",
    "accountNumber": "3234567890",
    "accountName": "John Doe",
    "bankName": "Example Bank",
    "expiresAt": "2024-01-16T10:30:00Z"
  }
}

The iban and bic field names are shared across deposit methods. For NGN deposits, iban carries the virtual account number and bic carries the bank name. Display the metadata block to the sender: accountNumber, accountName, bankName, and expiresAt are the details they need to complete the transfer before the virtual account expires.

EUR & GBP Bank Deposits

Your workspace can be provisioned with dedicated named accounts in your business name: an EUR IBAN reachable over SEPA and a GBP account number + sort code reachable over Faster Payments. Transfers sent to them are credited to the matching balance automatically (no create call is required) and appear as deposits with method virtual_account in GET /v1/deposits. The account details are shown in the dashboard. Contact your account manager to provision named accounts.

USD Bank Deposits

USD deposits settle into a managed deposit account provisioned for your business. Transfers sent to your account details are credited to your USD balance automatically and appear as deposits with method bank_deposit in GET /v1/deposits. No create call is required. Contact your account manager to provision a USD deposit account.

Requesting an account

Accounts can also be requested over the API with POST /v1/virtual-accounts, for your own workspace or for a customer account you manage (pass its id in Zuba-Account-Id). An account can only be opened once the owner has an approved application carrying everything the receiving bank asks for. Those attributes vary by currency and are not all collected during onboarding, so rather than discovering a gap from a failed request, ask first:

Check what is outstanding

curl "https://api.zuba.com/v1/virtual-accounts/requirements?currency=USD" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Zuba-Account-Id: $ACCOUNT_ID"

Requirements Response

{
  "currency": "USD",
  "ready": false,
  "status": "action_required",
  "requirements": [
    {
      "code": "business.industry_code",
      "scope": "business",
      "description": "The 6-digit NAICS code describing what the business does.",
      "resolution": {
        "method": "POST",
        "path": "/v2/applications/6f1c.../enrich",
        "field": "industryCode"
      }
    },
    {
      "code": "ubo.occupation_code",
      "scope": "person",
      "description": "The 6-digit SOC code for the beneficial owner's occupation.",
      "resolution": {
        "method": "POST",
        "path": "/v2/applications/6f1c.../persons/8dbb.../enrich",
        "field": "occupationCode"
      }
    }
  ]
}

Branch on ready. When it is false, each entry names what is outstanding and, in resolution, the exact call that supplies it — already resolved down to the specific person where the value belongs to one. Send those, then request the account. Read code rather than description: the codes are stable, the prose is not. A requirement whose resolution is null is one no API call sets, either because it is a detail recorded when the application was reviewed or because it is a state of the account or workspace rather than a value. Its description says what clears it. status distinguishes the cases where nothing is outstanding: ready (the request would succeed), already_exists (the owner already holds an account in this currency, and requesting one returns it), and unavailable (the currency is not offered to this owner, and no value they supply changes that). The check is read-only and safe to call as often as you like — collecting these from your customer at signup avoids a failed request later.

Crypto Deposits

Provision an on-chain deposit address with POST /v1/deposits/crypto-address, then send USDC or USDT to it. The deposit is recorded and credited once the transfer confirms on-chain, and appears with method crypto_deposit.

Live accounts enforce a minimum of 1 USDC or USDT per transfer. A smaller transfer is not credited, does not appear in GET /v1/deposits, and cannot be recovered. Contact your account manager if you have sent one. Amounts do not accumulate: two 0.60 transfers stay uncredited rather than combining to clear the minimum.Transfers funding a trade-desk order are exempt, so a shortfall top-up of any size still reaches your balance.The sandbox enforces no minimum, so sub-unit test transfers are credited there.

curl -X POST "https://api.sandbox.zuba.com/v1/deposits/crypto-address" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "eip155:1",
    "clientRef": "customer-1234"
  }'

const response = await fetch('https://api.sandbox.zuba.com/v1/deposits/crypto-address', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    network: 'eip155:1',
    clientRef: 'customer-1234'
  })
});

const { network, address, clientRef } = await response.json();
// { network: 'eip155:1', address: '0x1234...5678', clientRef: 'customer-1234' }

network is a CAIP-2 chain identifier:

Network	`network` value	Assets credited
Ethereum (ERC-20)	`eip155:1`	USDC, USDT
Solana (SPL)	`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`	USDC, USDT
Tron (TRC-20)	`tron:mainnet`	USDT

Address behaviour:

Addresses are reused. Omitting clientRef returns your single default address for the network; the same call always returns the same address. Pass distinct clientRef values (for example, your end-customer IDs) to provision distinct addresses.
The address is asset-agnostic: it receives any supported stablecoin on its network.
EVM addresses are valid across all EVM chains.
A 409 Conflict means the address for that client/network/reference is frozen or archived and cannot be re-created. Contact support.

Crypto deposits are availability-gated per environment. Contact your account manager to enable them. For the crypto payout side, see Payouts.

Deposit Lifecycle

Deposit Statuses

Status	Description
`pending`	Deposit created, awaiting funds
`processing`	Transfer detected, being verified
`in_review`	Held for compliance review before crediting
`completed`	Funds received and credited to your balance
`failed`	Deposit expired or transfer failed
`cancelled`	Deposit cancelled before completion
`refunding`	Return of funds to the sender in progress
`refunded`	Funds returned to the sender

Checking Deposit Status

Deposit IDs are UUIDs. Fetch a deposit by ID to get its current status:

curl -X GET "https://api.sandbox.zuba.com/v1/deposits/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const status = await fetch(`https://api.sandbox.zuba.com/v1/deposits/${depositId}`, {
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
});

const data = await status.json();
console.log(data.status); // pending, processing, completed, etc.

Deposit status changes are not currently delivered as webhook events. The webhook event catalog covers payout, order, and account events (see the Webhooks guide). Poll GET /v1/deposits/{id} to track a deposit: fetching a pending or processing deposit also triggers an asynchronous status refresh, so polling keeps the record fresh.

Listing Deposits

Retrieve deposits for your account as a paginated list, newest first. Filter with status, and page with limit (1–100, default 20) plus cursor:

curl -X GET "https://api.sandbox.zuba.com/v1/deposits?status=completed&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const page = await fetch('https://api.sandbox.zuba.com/v1/deposits?status=completed&limit=20', {
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
});

const { deposits, nextCursor, hasMore } = await page.json();
// deposits: array of deposit objects (id, status, amount, currency, method, clientRef, timestamps)

if (hasMore) {
  const next = await fetch(
    `https://api.sandbox.zuba.com/v1/deposits?limit=20&cursor=${encodeURIComponent(nextCursor)}`,
    { headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' } }
  );
}

Treat nextCursor as an opaque token: pass it back verbatim in the cursor query parameter to fetch the next page, and stop when hasMore is false. An invalid cursor, limit, or status value returns a 400 with field-level details.

Error Handling

Payin endpoints return standard error bodies:

400 Bad Request

{
  "statusCode": 400,
  "message": "Missing required fields for NGN currency: firstName, lastName, email, phoneNumber",
  "error": "Bad Request"
}

Common cases:

Status	Message	Cause
`400`	`Validation failed`	Malformed request body: for example, a non-decimal `amount` or an unsupported `currency`
`400`	`Missing required fields for NGN currency: firstName, lastName, email, phoneNumber`	NGN deposit created without the required sender details
`400`	`Duplicate request: clientRef <ref> already exists`	The `clientRef` was already used. Supply a unique value per deposit
`400`	(varies)	`GET /v1/deposits/{id}` called with a non-UUID `id`
`401`	(varies)	Missing or invalid access token
`404`	(varies)	Deposit not found or does not belong to your account

See the Error Handling guide for retry and recovery strategies.

Best Practices

Deposit Creation

Always include a unique clientRef for idempotency and reconciliation (duplicates are rejected with a 400)
Display the full metadata block to the sender: account number, account name, bank name, and expiry
Communicate the virtual account expiry (metadata.expiresAt) so the sender transfers in time
Store deposit IDs (UUIDs) for status tracking and customer support

Status Monitoring

Poll GET /v1/deposits/{id} with exponential backoff
Handle all eight statuses, including in_review, refunding, and refunded
Treat in_review as not-yet-credited: funds are held for compliance review
Log deposit events for audit and debugging

Security

Use HTTPS for all API communications
Never log sensitive customer payment data
Implement proper access controls for deposit endpoints
If you consume webhooks for other events, verify signatures (see Verifying Signatures)

Next Steps

Payouts

Send money globally to beneficiaries

Webhook Setup

Real-time notifications for payout, order, and account events

Ledger System

Track transactions with double-entry accounting

API Reference

Complete API documentation

Get Started

Core Concepts

Guides

Overview

NGN Deposits

Fixed virtual account

Dynamic virtual accounts (per deposit)

EUR & GBP Bank Deposits

USD Bank Deposits

Requesting an account

Crypto Deposits

Deposit Lifecycle

Deposit Statuses

Checking Deposit Status

Listing Deposits

Error Handling

Best Practices

Next Steps

Payouts

Webhook Setup

Ledger System

API Reference

​Overview

​NGN Deposits

​Fixed virtual account

​Dynamic virtual accounts (per deposit)

​EUR & GBP Bank Deposits

​USD Bank Deposits

​Requesting an account

​Crypto Deposits

​Deposit Lifecycle

​Deposit Statuses

​Checking Deposit Status

​Listing Deposits

​Error Handling

​Best Practices

​Next Steps

Payouts

Webhook Setup

Ledger System

API Reference

Overview

NGN Deposits

Fixed virtual account

Dynamic virtual accounts (per deposit)

EUR & GBP Bank Deposits

USD Bank Deposits

Requesting an account

Crypto Deposits

Deposit Lifecycle

Deposit Statuses

Checking Deposit Status

Listing Deposits

Error Handling

Best Practices

Next Steps