> ## Documentation Index
> Fetch the complete documentation index at: https://developer.obiex.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoice settlement

> Settle international invoices in USD using NGN, USDC, or USDT

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.

| `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

<Tabs>
  <Tab title="DEPOSIT (NGNX)">
    <Steps>
      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Settlement">
        Once the deposit is confirmed, the invoice moves to `APPROVED` and Obiex processes the USD payout to the beneficiary account.
      </Step>
    </Steps>

    <Warning>
      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.
    </Warning>
  </Tab>

  <Tab title="WALLET (NGNX, USDC, USDT)">
    <Steps>
      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Settlement">
        Obiex processes the USD payout to the beneficiary account. You can track progress via the invoice status or webhook notifications.
      </Step>
    </Steps>

    <Info>
      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.
    </Info>
  </Tab>
</Tabs>

## 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`.

<CodeGroup>
  ```json DEPOSIT invoice (NGNX) theme={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"
  }
  ```

  ```json WALLET invoice (USDC) theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

## 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                |