Payins

Overview

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

NGN bank transfers: transfers into your standing 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 USD receiving account, over ACH, Fedwire or SWIFT, are credited automatically.
KES deposits: fund your KES virtual account by bank transfer (PesaLink, RTGS, or SWIFT) or over M-Pesa — either an STK-push pull you initiate with POST /v1/deposits, or a customer paybill deposit. Every rail credits the same account.
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

Standing virtual account

Your workspace can hold a dedicated NGN virtual account in your business name (Zuba {Merchant Name}). Transfers sent to it are credited to your NGN balance automatically, and the same account number stays payable indefinitely. Request one with POST /v1/virtual-accounts once your business verification is approved:

Create Virtual Account Request

{
  "currency": "NGN"
}

The call is idempotent per currency: if you already hold a live NGN account it is returned with a 200 instead of a 201. Currencies you name during onboarding are requested for you when your verification is approved, so you may already have one — 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. GET /v1/virtual-accounts/requirements?currency=NGN reports anything still outstanding before one can be issued.

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.

USD Bank Deposits

A USD receiving account is held in your business name and reachable over three rails: ACH, Fedwire, and SWIFT. Transfers sent to its account and routing numbers are credited to your USD balance automatically, with no create call per transfer, and appear as deposits in GET /v1/deposits. The account details are shown in the dashboard and returned by the API once the account is active.

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 bank_deposit in GET /v1/deposits and on the deposit.completed webhook. Deposits created before this field settled carry virtual_account instead, so match on both values when reading a full deposit history. The account details are shown in the dashboard. Contact your account manager to provision named accounts.

KES Deposits

Every KES collection is received into a KES virtual account — it is the prerequisite for all the methods below, and each of them settles funds into it. Request one with POST /v1/virtual-accounts:

Create Virtual Account Request

{
  "currency": "KES"
}

Issuance is asynchronous and gated on your Kenya business verification. GET /v1/virtual-accounts/requirements?currency=KES reports anything still outstanding before one can be issued — see Requesting an account for the full flow. Every deposit below appears in GET /v1/deposits.

Bank transfer

Send funds to your KES virtual account number over PesaLink, RTGS, or SWIFT (SWIFT/BIC CHFIKENX). Transfers are credited to your KES balance automatically — no create call per transfer — and appear with method virtual_account.

Mobile money (M-Pesa)

Two ways to collect over M-Pesa, both crediting the same KES virtual account.

STK push

Pull a specific amount by prompting the payer’s phone: create a deposit with POST /v1/deposits, method: "mobile_money", and the payer’s phoneNumber. The payer keys in their M-Pesa PIN on the prompt to approve the transfer.

curl -X POST "https://api.sandbox.zuba.com/v1/deposits" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500",
    "currency": "KES",
    "method": "mobile_money",
    "clientRef": "DEPOSIT-REF-002",
    "description": "Account top-up",
    "phoneNumber": "+254712345678"
  }'

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: '500',
    currency: 'KES',
    method: 'mobile_money',
    clientRef: 'DEPOSIT-REF-002',
    description: 'Account top-up',
    phoneNumber: '+254712345678'
  })
});

const data = await deposit.json();

The request returns a processing deposit once the prompt is sent; the credit is confirmed asynchronously after the payer approves it:

Create Deposit Response (KES STK push)

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "method": "mobile_money",
  "amount": "500",
  "currency": "KES",
  "status": "processing",
  "reference": "STK-1706510200000",
  "description": "STK push sent — approve the prompt on your phone to complete.",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

KES STK-push deposits have three input rules:

method must be mobile_money — KES does not accept the default manual_deposit.
amount must be a whole KES number greater than zero; M-Pesa does not settle fractional shillings.
phoneNumber is the payer’s MSISDN the prompt is sent to.

Poll GET /v1/deposits/{id} for the outcome — the deposit moves to completed once the payer approves the prompt and M-Pesa settles, or failed if the prompt is declined or times out.

Paybill deposit

The payer pushes funds themselves: they pay the Zuba paybill, entering your KES virtual account number as the account number. No create call is needed — the credit is matched to your account and appears with method virtual_account.

Environment	Paybill number
Sandbox	`4101847`
Production	`444174`

Requesting an account

Request an account 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). Issuance is asynchronous: the request answers immediately with a pending account, and the account becomes usable once the receiving bank opens it. Subscribe to the virtual_account.active webhook to learn when its details are available, and virtual_account.failed to learn that it will not be opened. Requesting again while one is pending returns the same account rather than opening a second. 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"
      },
      "disclosures": null
    },
    {
      "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"
      },
      "disclosures": null
    },
    {
      "code": "disclosure.acknowledgement",
      "scope": "disclosure",
      "description": "The terms this account would be opened under have not all been accepted at the version currently in force. Every outstanding document is listed in `disclosures`, each with the exact wording that must be agreed. They are accepted while the account owner's application is still open; for an owner whose application is already approved, contact support.",
      "resolution": null,
      "disclosures": [
        {
          "slug": "funds-availability-disclosure",
          "title": "Funds Availability Disclosure",
          "version": "2026.08.07",
          "pdfUrl": "/disclosures/acme/v2026.08.07/funds-availability-disclosure.pdf",
          "displayOrder": 30,
          "checkboxWording": "I have read and acknowledge the Funds Availability Disclosure."
        }
      ]
    }
  ]
}

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 — a detail recorded when the application was reviewed, acceptance the account owner owes for the terms the account would be opened under, or a state of the account or workspace rather than a value. Its description says what clears it. The disclosure.* codes are that acceptance: the partner bank’s own documents, which the account owner agrees to before the account can be opened. One code covers the whole outstanding package, and the documents travel with it in disclosures — slug, title, version, a link to the PDF, the order to show them in, and the exact wording each acceptance stands for — so you render them without a second call. disclosures is null on every other code. Acceptance is collected while the owner’s application is still open, which is where the onboarding flow already asks for it; once an application is approved its acceptances are frozen, so an owner still owing one after approval needs support. That is why the resolution is null rather than a call you could make. 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

Open a wallet with POST /v1/wallets, then send USDC or USDT to its address. The deposit is recorded and credited once the transfer confirms on-chain, and appears with method crypto_deposit. GET /v1/wallets lists the wallets you hold, newest first with cursor pagination; GET /v1/wallets/{id} reads one.

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/wallets" \
  -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/wallets', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    network: 'eip155:1',
    clientRef: 'customer-1234'
  })
});

const wallet = await response.json();
// {
//   id: '9b2f4c1e-...',
//   network: 'eip155:1',
//   networkName: 'Ethereum',
//   address: '0x1234...5678',
//   assets: ['USDT', 'USDC'],
//   status: 'active',
//   clientRef: 'customer-1234',
//   createdAt: '2026-09-09T12:00:00.000Z'
// }

network names the chain. Pass the CAIP-2 chain identifier or any of the friendly spellings beside it, in any casing; both POST /v1/wallets and the ?network= filter on GET /v1/wallets accept either.

Network	`network` value	Also accepted	Assets credited
Ethereum (ERC-20)	`eip155:1`	`ethereum`, `eth`	USDT, USDC
Base	`eip155:8453`	`base`	USDC
Solana (SPL)	`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`	`solana`, `sol`	USDC, USDT
Tron (TRC-20)	`tron:mainnet`	`tron`, `trx`	USDT

Every wallet comes back with the CAIP-2 identifier in network whichever spelling you sent, and the chain’s readable name in networkName for display. Key your own logic on network. The network values listed in the API reference but absent from this table are test networks or networks enabled for individual accounts; a request for one you are not enabled on is refused with METHOD_NOT_ENTITLED. Each wallet’s assets lists the stablecoins your account is credited for on that network. Wallet behaviour:

One wallet per owner, network and reference. The first request answers 201 and opens the wallet; every later request for the same network and clientRef answers 200 with the same wallet, as long as at least one stablecoin on that network is still enabled for you. If none is, opening is refused with 403 METHOD_NOT_ENTITLED; read the wallet you already hold with GET /v1/wallets instead. Omit clientRef for your single default wallet on the network; pass distinct values (for example, your end-customer IDs) to open distinct wallets. A clientRef is 1 to 100 single-byte characters with no line break, must not begin or end with whitespace, and must not start with pool-.
A wallet is asset-agnostic: its address receives every stablecoin in assets. A wallet whose status is not active credits nothing, so its assets is empty.
A wallet credits deposits only on the network it was opened on. An EVM address is syntactically valid on every EVM chain, but a transfer sent to it on another chain is not credited and cannot be recovered. Open a separate wallet per network.
Sub-accounts hold their own wallets. Pass Zuba-Account-Id to open, list, or read a sub-account’s wallets; deposits to them settle into that sub-account’s balance. Without the header you act on, and see, your master account’s wallets only.
A 409 Conflict means the wallet for that owner, network and reference is frozen or archived and cannot be re-opened. 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

What the Deposit Credits

amount is what arrived. Where your plan prices deposits, Zuba’s charge is serviceFee and your balance moves by creditedAmount — amount less that fee, in the deposit’s own currency. Both fields are on every deposit from GET /v1/deposits/{id} and on the deposit.completed webhook, and serviceFee is "0.00000000" where your plan prices no deposits. Credit your own customer from creditedAmount. Reconciling against amount over-credits by the fee on every priced deposit.

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.

A deposit’s terminal outcome is delivered as a webhook: subscribe an endpoint to deposit.completed (funds credited) and deposit.failed (the collection terminally failed, e.g. a declined M-Pesa prompt) — see the Webhooks guide. No webhook fires for the pending/processing stages; to follow those, poll GET /v1/deposits/{id}, which also triggers an asynchronous status refresh on a pending or processing deposit.

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. If you manage customer accounts, pass Zuba-Account-Id: <accountId> to list only that account’s deposits; without the header the list covers the whole workspace. Each deposit carries an accountId naming the account it was credited to (null for your own workspace-level deposits).

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`	`Deposit method manual_deposit is not supported for KES`	KES deposit created without `method: "mobile_money"`
`400`	`M-Pesa STK amount must be a whole KES number greater than zero`	KES M-Pesa `amount` was fractional, zero, or negative
`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

Standing virtual account

Dynamic virtual accounts (per deposit)

USD Bank Deposits

EUR & GBP Bank Deposits

KES Deposits

Bank transfer

Mobile money (M-Pesa)

STK push

Paybill deposit

Requesting an account

Crypto Deposits

Deposit Lifecycle

What the Deposit Credits

Deposit Statuses

Checking Deposit Status

Listing Deposits

Error Handling

Best Practices

Next Steps

Payouts

Webhook Setup

Ledger System

API Reference

​Overview

​NGN Deposits

​Standing virtual account

​Dynamic virtual accounts (per deposit)

​USD Bank Deposits

​EUR & GBP Bank Deposits

​KES Deposits

​Bank transfer

​Mobile money (M-Pesa)

​STK push

​Paybill deposit

​Requesting an account

​Crypto Deposits

​Deposit Lifecycle

​What the Deposit Credits

​Deposit Statuses

​Checking Deposit Status

​Listing Deposits

​Error Handling

​Best Practices

​Next Steps

Payouts

Webhook Setup

Ledger System

API Reference

Overview

NGN Deposits

Standing virtual account

Dynamic virtual accounts (per deposit)

USD Bank Deposits

EUR & GBP Bank Deposits

KES Deposits

Bank transfer

Mobile money (M-Pesa)

STK push

Paybill deposit

Requesting an account

Crypto Deposits

Deposit Lifecycle

What the Deposit Credits

Deposit Statuses

Checking Deposit Status

Listing Deposits

Error Handling

Best Practices

Next Steps