NigeriaNigeria — Permanent NGN virtual accountNigeria — Permanent NGN virtual account
Base URL
https://api.transacty.ai
Summary
Accept permanent NGN virtual-account deposits and send NGN bank payouts. Settled proceeds credit your merchant NGN wallet.
After the virtual account is ready, payers transfer any amount to those bank
details. There is no create-per-payment call — no POST …/collections and no
payment-intent for NGN collect.
Exact-amount temporary collections, amount/expiry pay instructions, MoMo, and swaps are not in this product.
Live only
This rail has no sandbox. Use a live API key. A test key returns 503
{ "code": "payment_unavailable" }.
Settlement wallet & market
| Collect | Payer transfers NGN to your permanent virtual account |
| Settle | Transacty creates a pay-in and credits your NGN wallet (fees applied) |
| Payout | Debit merchant NGN → Nigerian bank account |
| Spend | EUR / USDC / PYUSD-USDC / other pockets cannot fund NGN payouts |
| Live only | Use a live API key. test → 503 payment_unavailable |
| Market | nigeria must be approved and KYC verified |
NGN is a separate wallet pocket. Never sum unlike currencies into one headline
number. Read it on GET /v1/balance items[].
Enable the nigeria market first. Until Nigeria is KYB-approved (and KYC
verified), /v1/ngn/* returns 403 (market_not_enabled).
Limits (major units)
Pay-in limits apply when a credit settles, not when the virtual account is created.
| Flow | Min | Max |
|---|---|---|
| Pay-in (per inbound credit) | 100 | 5,000,000 |
| Payout | 500 | 5,000,000 |
Required headers
Every request uses HMAC authentication (same scheme as all /v1/* endpoints):
X-Transacty-KeyX-Transacty-Timestamp(Unix seconds)X-Transacty-Signature=HMAC-SHA256(secret, "{timestamp}.{rawBody}")Content-Type: application/jsonon POSTIdempotency-Key(required on virtual-account provision and payout create)
Required scopes
payin:create— virtual account GET/POSTpayout:create— verify account and payouts- Banks list:
payin:createorpayout:create
Collect flow (no create-per-payment)
| Step | Merchant server | Transacty API |
|---|---|---|
| 1 | Get or provision the virtual account | GET / POST /v1/ngn/virtual-account |
| 2 | When ready: true, share accountNumber / bankName / accountName | — |
| 3 | Payer transfers any amount to those details | — |
| 4 | Wait for webhook | payin.completed |
| 5 | Credit your order on payin.completed (currency: "NGN") | — |
Transacty creates the pay-in when the inbound credit settles. List history with
GET /v1/transactions?type=payin, then filter
rail === "nigeria" in your app (no rail= query).
Payout flow
| Step | API |
|---|---|
| 1 | GET /v1/ngn/banks?search= |
| 2 | POST /v1/ngn/verify-account (name enquiry) |
| 3 | POST /v1/ngn/payouts with Idempotency-Key |
| 4 | GET /v1/ngn/payouts/:transactionId or wait for webhook |
Webhook events
When a webhook URL is configured, Transacty sends:
payin.completed— VA credit settled to NGN (currency: "NGN")payin.failed— rare on the VA pathpayout.completed/payout.failed— bank withdraw finalized
See Webhooks for signature verification.