Invoice settlement

Invoice settlement lets your business pay international invoices in USD using Nigerian Naira (NGNX), USDC, or USDT. You provide the invoice details and beneficiary bank account, and Obiex handles the conversion and cross-border transfer.

Funding source

Every invoice requires a fundingSource — either DEPOSIT or WALLET. This determines both how the payment is collected and which source currencies are accepted. If omitted, it defaults to DEPOSIT.

`fundingSource`	Accepted source currencies	How it works
`DEPOSIT`	NGNX	Obiex provides a virtual NGN bank account. You transfer the required amount within 30 minutes.
`WALLET`	NGNX, USDC, USDT	Obiex debits the required amount from your wallet immediately. Invoice goes straight to `APPROVED`.

How it works

DEPOSIT (NGNX)
WALLET (NGNX, USDC, USDT)

Upload your invoice document

Upload the invoice file (image or PDF) via the document upload endpoint. You’ll receive a URL to include when creating the invoice.

Create the invoice

Submit the invoice with fundingSource: "DEPOSIT", source: "NGNX", the target USD amount, beneficiary bank details, and the document URL. Obiex returns a virtual NGN bank account and the exact NGN amount to deposit.

Deposit NGN

Transfer the exact NGN amount to the virtual account provided. The account is valid for 30 minutes. The invoice expires if no deposit is received within that window.

Settlement

Once the deposit is confirmed, the invoice moves to APPROVED and Obiex processes the USD payout to the beneficiary account.

The virtual account expires 30 minutes after the invoice is created. If payment is received after expiry, the invoice is marked EXPIRED and the NGN is credited back to your wallet.

Upload your invoice document

Upload the invoice file (image or PDF) via the document upload endpoint. You’ll receive a URL to include when creating the invoice.

Create the invoice

Submit the invoice with fundingSource: "WALLET", the source currency (NGNX, USDC, or USDT), the target USD amount, beneficiary bank details, and the document URL. Obiex immediately debits the required amount from your wallet and sets the invoice to APPROVED. No virtual account is generated.

Settlement

Obiex processes the USD payout to the beneficiary account. You can track progress via the invoice status or webhook notifications.

Your wallet must have sufficient balance in the chosen source currency at the time of creation. If the balance is insufficient, the request is rejected and nothing is debited.

Invoice status lifecycle

Status	Description
`PENDING`	Invoice created, awaiting NGN deposit (`DEPOSIT` funding only)
`APPROVED`	Deposit confirmed (`DEPOSIT`) or wallet debited (`WALLET`) — payout pending
`PROCESSING`	USD payout is being processed
`COMPLETED`	Payout completed. A `trackingId` is attached
`FAILED`	Payout failed
`EXPIRED`	Virtual account expired before deposit was received (`DEPOSIT` only)
`REFUNDED`	Funds returned to your account

Webhook notifications

Obiex sends a webhook to your callback URL on every status change. For DEPOSIT invoices, the payload includes virtual account fields. For WALLET invoices, those fields are null.

{
  "type": "INVOICE",
  "invoiceId": "a3f1c2d4-8b0e-4f3a-9c7d-1e2b3a4c5d6e",
  "reference": "INV-2026-001",
  "status": "COMPLETED",
  "sourceCurrency": "NGNX",
  "sourceAmount": 1625000,
  "targetCurrency": "USD",
  "targetAmount": 1000,
  "rate": 1625,
  "beneficiaryAccountNumber": "12345678901",
  "beneficiaryAccountName": "Acme Corp",
  "beneficiaryBankName": "First International Bank",
  "swiftCode": "FIBKUS33XXX",
  "virtualAccountNumber": "9012345678",
  "virtualAccountName": "Obiex / Acme Corp",
  "virtualBankName": "Providus Bank",
  "accountExpiresAt": "2026-06-10T11:30:00.000Z",
  "createdAt": "2026-06-10T11:00:00.000Z",
  "lastUpdated": "2026-06-10T12:45:00.000Z",
  "trackingId": "TRK-20260610-001"
}

{
  "type": "INVOICE",
  "invoiceId": "b7e2d1c3-9a0f-4e2b-8d6c-2f3a4b5c6d7e",
  "reference": null,
  "status": "COMPLETED",
  "sourceCurrency": "USDC",
  "sourceAmount": 1000,
  "targetCurrency": "USD",
  "targetAmount": 1000,
  "rate": 1,
  "beneficiaryAccountNumber": "12345678901",
  "beneficiaryAccountName": "Acme Corp",
  "beneficiaryBankName": "First International Bank",
  "swiftCode": "FIBKUS33XXX",
  "virtualAccountNumber": null,
  "virtualAccountName": null,
  "virtualBankName": null,
  "accountExpiresAt": null,
  "createdAt": "2026-06-10T11:00:00.000Z",
  "lastUpdated": "2026-06-10T12:45:00.000Z",
  "trackingId": "TRK-20260610-002"
}

Key endpoints

Method	Endpoint	Description
POST	`/uploads/invoices`	Upload an invoice document (image or PDF)
POST	`/invoices`	Create an invoice
GET	`/invoices/me`	List all invoices for your account
GET	`/invoices/{invoiceId}`	Get a single invoice by ID

Getting Started

Features

SDKs

Use Cases

Invoice settlement

Funding source

How it works

Invoice status lifecycle

Webhook notifications

Key endpoints

​Funding source

​How it works

​Invoice status lifecycle

​Webhook notifications

​Key endpoints

Funding source

How it works

Invoice status lifecycle

Webhook notifications

Key endpoints