Collection API

Base path: https://gateway.useyona.com/b/v1

Collect invoice payments from buyers via virtual (bank) accounts. A buyer pays an invoice by bank transfer into a virtual account you mint; the payment is reconciled against the seller’s invoices and any excess is held as buyer credit, then settled to the seller’s registered bank. Yona never holds buyer money — funds route directly to the seller’s settlement account.

Permissions: read endpoints require collection.read; create/modify endpoints require collection.manage. Grant these to an API key or role like any other permission.

Prerequisite: a seller must have a settlement account on file before you can mint a collection account for them — the mint routes settlement to the seller’s registered bank.

Register a settlement account

POST /b/v1/collection/settlement-accounts

Body parameters

Parameter	Type	Required	Description
`sellerId`	string	Yes	Seller party (invoice issuer) this account is for
`bankCode`	string	Yes	Canonical bank code (NIP/CBN), e.g. `058`
`accountNumber`	string	Yes	Seller’s 10-digit NUBAN
`currency`	string	No	ISO 4217 (default `NGN`)
`jurisdiction`	string	No	ISO 3166-1 alpha-2 (default `NG`)
`sellerName`	string	No	Seller party display name (snapshotted)
`sellerType`	string	No	Seller party type (`individual`, `company`, …)

bash

curl -X POST https://gateway.useyona.com/b/v1/collection/settlement-accounts \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sellerId": "sel_123",
    "bankCode": "058",
    "accountNumber": "0123456789"
  }'

Resolve a bank account

POST /b/v1/collection/settlement-accounts/resolve

Name-enquiry against a bank account, with no persistence. Use it to confirm the account holder name before registering a settlement account. Requires collection.read.

Body parameters

Parameter	Type	Required	Description
`bankCode`	string	Yes	Canonical bank code (NIP/CBN)
`accountNumber`	string	Yes	10-digit NUBAN
`jurisdiction`	string	No	ISO 3166-1 alpha-2 (default `NG`)

bash

curl -X POST https://gateway.useyona.com/b/v1/collection/settlement-accounts/resolve \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "bankCode": "058", "accountNumber": "0123456789" }'

List settlement accounts

GET /b/v1/collection/settlement-accounts

List your organization’s settlement accounts (newest first). Requires collection.read.

bash

curl https://gateway.useyona.com/b/v1/collection/settlement-accounts \
  -H "Authorization: Bearer sk_test_your_key_here"

Get a seller’s settlement account

GET /b/v1/collection/settlement-accounts/:sellerId

Returns 404 if the seller has no settlement account registered. Requires collection.read.

bash

curl https://gateway.useyona.com/b/v1/collection/settlement-accounts/sel_123 \
  -H "Authorization: Bearer sk_test_your_key_here"

List settlement banks

GET /b/v1/collection/banks

List the settlement banks available for a jurisdiction’s provider (for a bank picker). Requires collection.read.

Query parameters

Parameter	Type	Required	Description
`jurisdiction`	string	Yes	ISO 3166-1 alpha-2, e.g. `NG`
`provider`	string	No	Restrict to a specific provider’s bank list

bash

curl "https://gateway.useyona.com/b/v1/collection/banks?jurisdiction=NG" \
  -H "Authorization: Bearer sk_test_your_key_here"

Mint a collection account

POST /b/v1/collection/accounts

Mint a virtual account a buyer can pay into. Use persistent mode for a stable per-buyer account, or dynamic for a one-time, amount-specific account that expires. Requires collection.manage.

Body parameters

Parameter	Type	Required	Description
`mode`	`'persistent' \| 'dynamic'`	Yes	Account mode
`jurisdiction`	string	Yes	ISO 3166-1 alpha-2 (seller jurisdiction)
`sellerId`	string	Yes	Seller party whose settlement bank receives the funds (must have a settlement account)
`reference`	string	Yes	Unique, idempotent reference for this request
`customer`	object	Yes	Buyer/payer details — `name` required; `firstName`, `lastName`, `phoneNumber`, `email`, `bvn` optional
`currency`	string	No	ISO 4217 (default `NGN`)
`accountReference`	string	No	Stable per-buyer reference (persistent mode, 12–30 chars)
`invoiceId`	string	No	Invoice this account collects for
`buyerId`	string	No	Buyer this account is tied to
`amount`	number	No	Expected amount (major units) — required for `dynamic` mode
`expiresAt`	string	No	ISO 8601 timestamp — dynamic-mode expiry
`method`	string	No	Payment method hint, e.g. `BANK_TRANSFER`
`preferredProvider`	string	No	Preferred provider when several cover the jurisdiction
`callbackUrl`	string	No	Per-account webhook override
`fundingTransactionLimit`	number	No	Cap on a single inbound transfer

bash

curl -X POST https://gateway.useyona.com/b/v1/collection/accounts \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "dynamic",
    "jurisdiction": "NG",
    "sellerId": "sel_123",
    "reference": "inv-2026-001",
    "amount": 50000,
    "invoiceId": "inv_123",
    "customer": { "name": "Mama Ngozi Stores", "email": "buyer@example.com" }
  }'

List collection accounts

GET /b/v1/collection/accounts

List your collection accounts (auto-scoped to your organization). Requires collection.read.

Query parameters

Parameter	Type	Required	Description
`sellerId`	string	No	Filter by seller party
`buyerId`	string	No	Filter by buyer
`invoiceId`	string	No	Filter by invoice
`provider`	string	No	Filter by provider
`mode`	`'persistent' \| 'dynamic'`	No	Filter by mode
`jurisdiction`	string	No	Filter by jurisdiction
`status`	`'active' \| 'expired' \| 'deactivated'`	No	Filter by status
`page`, `pageSize`	number	No	Pagination

bash

curl "https://gateway.useyona.com/b/v1/collection/accounts?status=active" \
  -H "Authorization: Bearer sk_test_your_key_here"

Get a collection account

GET /b/v1/collection/accounts/:id

Requires collection.read.

bash

curl https://gateway.useyona.com/b/v1/collection/accounts/col_9a8b7c \
  -H "Authorization: Bearer sk_test_your_key_here"

Get live account status

GET /b/v1/collection/accounts/:id/status

Fetch the live provider status for an account (a reconciliation fallback). Requires collection.read.

bash

curl https://gateway.useyona.com/b/v1/collection/accounts/col_9a8b7c/status \
  -H "Authorization: Bearer sk_test_your_key_here"

Deactivate a collection account

POST /b/v1/collection/accounts/:id/deactivate

Deactivate a persistent account at the provider and locally. Idempotent — a deactivated account no longer receives funds. Requires collection.manage.

Body parameters

Parameter	Type	Required	Description
`reason`	string	No	Reason recorded with the provider/audit

bash

curl -X POST https://gateway.useyona.com/b/v1/collection/accounts/col_9a8b7c/deactivate \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "buyer relationship ended" }'

List received payments

GET /b/v1/collection/payments

The ledger of payments received on your collection accounts. Requires collection.read.

Query parameters

Parameter	Type	Required	Description
`reconciliationStatus`	`'pending' \| 'applied' \| 'overpaid' \| 'unmatched'`	No	Filter by reconciliation state

bash

curl "https://gateway.useyona.com/b/v1/collection/payments?reconciliationStatus=applied" \
  -H "Authorization: Bearer sk_test_your_key_here"

Refund a payment

POST /b/v1/collection/payments/:id/refund

Refund a received payment, in full or part. Requires collection.manage.

Body parameters

Parameter	Type	Required	Description
`amount`	number	No	Partial amount to refund (major units). Defaults to the full amount
`reason`	string	No	Reason passed to the provider

bash

curl -X POST https://gateway.useyona.com/b/v1/collection/payments/pay_123/refund \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "duplicate payment" }'

List exceptions

GET /b/v1/collection/exceptions

Payments that need attention — unmatched (no invoice/buyer found) or overpaid. Requires collection.read.

bash

curl https://gateway.useyona.com/b/v1/collection/exceptions \
  -H "Authorization: Bearer sk_test_your_key_here"

Resolve an exception

POST /b/v1/collection/exceptions/:paymentId/resolve

Manually replay an exception against a specific invoice, or spread it across a buyer’s open invoices. Requires collection.manage.

Body parameters

Parameter	Type	Required	Description
`invoiceId`	string	No	Apply the payment to this invoice
`buyerId`	string	No	Spread the payment across this buyer’s open invoices

bash

curl -X POST https://gateway.useyona.com/b/v1/collection/exceptions/pay_123/resolve \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "invoiceId": "inv_123" }'

List buyer credits

GET /b/v1/collection/credits

Outstanding buyer credit balances (from overpayments or unmatched funds), one per buyer + currency. These auto-apply to future invoices or can be refunded. Requires collection.read.

bash

curl https://gateway.useyona.com/b/v1/collection/credits \
  -H "Authorization: Bearer sk_test_your_key_here"