Skip to main content
By the end of this guide you will have provisioned a Virtual Account via API, simulated an incoming bank transfer on sandbox, received the collect.succeeded webhook, fetched the collect, and confirmed the credit on your balance. You need two things before starting: a sandbox account with API keys (Get Started with Tazapay) and an entity — no real onboarding needed on sandbox, you can create an entity and simulate its approval directly. Everything below runs against sandbox, so no real money moves. This walkthrough uses a Singapore SGD Virtual Account. The identical flow applies to Stablecoin Wallets — swap the payload as shown in Requesting via API and a deposit address replaces the bank details.

​
The flow at a glance

  1. Provision the account — POST /v3/collection_account
  2. Account enabled — the enablement request succeeds and status flips to enabled
  3. Fetch account details — the bank coordinates you give your payer
  4. Payer transfers funds — a normal domestic transfer, or SWIFT, or an on-chain send
  5. Collect created & screened — Tazapay creates a collect and runs compliance screening
  6. Collect succeeds — collect.succeeded fires
  7. Balance credited — funds land in your Tazapay balance, converted if needed
1

Set up authentication

The Tazapay API uses HTTP Basic authentication: your API_Key is the username and your API_Secret is the password, joined with a colon, Base64-encoded, and sent as Authorization: Basic <value>. See Authentication for the full breakdown.All calls in this guide use the sandbox base URL. See Endpoints and Environments.
Sandbox base URL
curl -u performs the Basic encoding for you, so the examples below stay copy-pasteable:
Set your credentials
2

Discover what you can create

Before creating anything, ask the Metadata API what your account is actually allowed to provision. This returns the payment method types, currencies, rails, and transfer limits available to you.
Request
Response (trimmed)
Sandbox availability may differ from production. In production, what you can provision depends on your onboarding profile — if a corridor you need is missing here, check Virtual Account coverage and talk to your account manager.
Full reference: Virtual Account Metadata. For stablecoins, call Wallet Metadata instead.
3

Create the collection account

Create a Singapore SGD Virtual Account on the local rail. Only type and payment_method_type are required by the schema; country and currencies are additionally required for virtual accounts.
Request
Response
Note the account is born disabled with an enablement request attached — it cannot receive funds yet. The account’s status is derived from the state of that request, not set directly. For the full request lifecycle and every state a request can pass through, see Collection Account Status Flow.Save the returned id — every step below uses it:
4

Wait for enablement

Subscribe to collection_account.creation_succeeded. It fires when the enablement request succeeds and the account flips to enabled.
collection_account.creation_succeeded (trimmed)
The same family of events reports the unhappy paths — creation_requires_action, creation_under_approval_hold, creation_failed, creation_cancelled. Handle at least creation_failed before going live. Full list and payloads: Collection Account Webhooks.On setting up and securing your endpoint, see the Webhooks Guide and Webhook Authentication.
5

Fetch the account details your payer needs

Fetch the account and read the virtual_account block. These are the coordinates your payer transfers to.
Request
Virtual account details to share with your payer
The keys present under bank_codes vary by country and rail — it may contain swift_code, routing_code, sort_code, ach_routing_number, fedwire_routing_number, bsb_code, or bank_code. Read them dynamically rather than assuming a fixed set. Full reference: Collection Account object.In production, these are the details you display to your customer or print on your invoice. The payer then makes a normal domestic transfer to this account — from their side it looks like paying a local business, not an international wire.
6

Simulate an incoming payment

Sandbox includes a Collect Simulation feature so you can mimic an incoming payment without moving real money. This step is performed from the dashboard, not the API.Go to the Sandbox dashboard → Virtual Accounts/Wallets → Simulate Collect, pick the account you just created, and simulate the succeeded state.You can simulate every intermediate and terminal state, which is how you exercise the unhappy paths in your integration:Stablecoin wallets add detected transitions, since on-chain payments are visible before final confirmation. The complete matrix for both fiat and crypto is on Simulating Collects on Sandbox.
Simulated collects also create a real sandbox balance, which you can then use to fund and test payouts end to end.
7

Receive the collect and confirm the credit

The webhook. As soon as the collect settles, collect.succeeded fires. This is the event your system should treat as the signal that money arrived — note balance_transaction, which ties the collect to the ledger entry on your balance.
collect.succeeded
All collect events and their payloads: Collect Webhooks.The sibling events are collect.failed, collect.on_hold, and collect.detected (wallets only). See Collect Webhooks.Fetch the collect. Take the collect ID from the webhook and fetch it directly:
Request
Collect — succeeded USD collect
Field-level reference: Collect object. Amounts are in the currency’s smallest unit — 100000 here is USD 1,000.00.The four fields to reconcile against are status (succeeded), amount and currency (what arrived), destination (which collection account received it), and balance_transaction (the ledger entry).Confirm the balance. Finally, check that the funds are on your balance:
Request
Response (trimmed)
Balance amounts are strings in the currency’s smallest unit — "100000" is SGD 1,000.00.If the incoming currency is not one of your holding currencies, it is converted automatically at the point of credit rather than as a separate step — see FX.

​
Going to production

Request via Dashboard

Prefer no code? Provision the same account from the Tazapay dashboard.

Collection Account API Reference

Every field, enum, and endpoint for collection accounts.