Nigeria API Reference (Merchant Server)

All endpoints use HMAC authentication on https://api.transacty.ai. Live API keys only — a test key returns 503 payment_unavailable. The nigeria market must be approved (and KYC verified) or /v1/ngn/* returns 403 market_not_enabled.

Virtual account

Method	Path	Scope	Purpose
`GET`	`/v1/ngn/virtual-account`	`payin:create`	Get VA status / bank details
`POST`	`/v1/ngn/virtual-account`	`payin:create`	Provision VA (BVN Basic). `Idempotency-Key` required

Banks, verify, payout

Method	Path	Scope	Purpose
`GET`	`/v1/ngn/banks`	`payin:create` or `payout:create`	List banks (`?search=`)
`POST`	`/v1/ngn/verify-account`	`payout:create`	Name enquiry
`POST`	`/v1/ngn/payouts`	`payout:create`	Create NGN payout. `Idempotency-Key` required
`GET`	`/v1/ngn/payouts/:transactionId`	`payout:create`	Get payout status

Shared read endpoints

Method	Path	Notes
`GET`	`/v1/transactions`	Filter `type=payin\|payout` only; then filter `rail === "nigeria"` in your app
`GET`	`/v1/transactions/:transactionId`	Status poll; same rail fields
`GET`	`/v1/balance`	Read `items[]` — Nigeria is `NGN`
`PATCH`	`/v1/me/webhook`	Register the URL for Transacty → merchant events

Settlement

Inbound VA credits settle to your NGN wallet. Limits 100–5,000,000 apply when a credit settles, not when the VA is created.
Payouts debit NGN and send NGN to the beneficiary bank. Body field is beneficiary (accountNumber, bankCode, accountName, bankName).
NGN is a separate wallet pocket. EUR payouts cannot spend it; NGN payouts cannot spend USDC or PYUSD-USDC.
There is no create-per-payment collect endpoint.

Webhook events

When configured, Transacty sends payin.completed / payin.failed and payout.completed / payout.failed. Payload currency for NGN money movements is NGN. The same webhook URL serves all rails. See Webhooks.