Skip to main content
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.
fundingSourceAccepted source currenciesHow it works
DEPOSITNGNXObiex provides a virtual NGN bank account. You transfer the required amount within 30 minutes.
WALLETNGNX, USDC, USDTObiex debits the required amount from your wallet immediately. Invoice goes straight to APPROVED.

​
How it works

1

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.
2

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.
3

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.
4

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.

​
Invoice status lifecycle

StatusDescription
PENDINGInvoice created, awaiting NGN deposit (DEPOSIT funding only)
APPROVEDDeposit confirmed (DEPOSIT) or wallet debited (WALLET) — payout pending
PROCESSINGUSD payout is being processed
COMPLETEDPayout completed. A trackingId is attached
FAILEDPayout failed
EXPIREDVirtual account expired before deposit was received (DEPOSIT only)
REFUNDEDFunds 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

MethodEndpointDescription
POST/uploads/invoicesUpload an invoice document (image or PDF)
POST/invoicesCreate an invoice
GET/invoices/meList all invoices for your account
GET/invoices/{invoiceId}Get a single invoice by ID