Deposits & Settlements

Understanding fiat deposits via virtual accounts and their crypto settlement lifecycle.

Virtual accounts allow your business to receive fiat deposits that are automatically settled into crypto. This is ideal for businesses that want to accept local bank transfers and settle in stablecoins.

How it works

1. Create a virtual account for a user (POST /v1/virtual-accounts)
2. User sends fiat to the virtual account via bank transfer
3. IvoryPay detects the deposit → webhook: deposit.received
4. Settlement begins: fiat is converted to crypto
5. Crypto is sent to your configured wallet
6. Settlement lifecycle webhooks fire at each stage

Integration steps

1

Create a virtual account

curl -X POST https://ramp-api.ivorypay.io/api/v1/virtual-accounts \
  -H "Authorization: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "identityType": "bvn",
    "identityNumber": "22222222222",
    "currency": "NGN"
  }'

The user can now transfer fiat to this virtual account at any time.

2

Receive deposit notifications

When a user transfers money to the virtual account, you will receive a webhook:

Webhook: deposit.received

{
  "event": "deposit.received",
  "data": {
    "reference": "dep_abc123",
    "processorReference": "prov_xyz789",
    "accountNumber": "1234567890",
    "accountName": "IvoryPay - User Name",
    "currency": "NGN",
    "receivedAmount": 100000,
    "settledAmount": 99500,
    "status": "SUCCESS",
    "sourceAccountNumber": "0987654321",
    "sourceAccountName": "Sender Name",
    "sourceBankName": "GTBank",
    "paymentDate": "2026-03-26T14:30:00.000Z"
  }
}

3

Track settlement lifecycle

After a deposit is received, IvoryPay automatically initiates settlement (converting fiat to crypto). The settlement progresses through these stages:

Stage	Webhook event	Description
Awaiting account	settlement.awaitingSettlementAccount	Waiting for settlement account configuration
Converting	settlement.converting	Fiat-to-crypto conversion in progress
Payout initiated	settlement.payoutInitiated	Crypto payout has been queued
Payout processing	settlement.payoutProcessing	Crypto is being sent on-chain
Completed	settlement.success	Crypto delivered to your wallet
Failed	settlement.failed	Settlement failed — check failureReason

Webhook: settlement.success

{
  "event": "settlement.success",
  "data": {
    "reference": "set_abc123",
    "settlementId": "uuid-here",
    "depositId": "dep_abc123",
    "fiatAmount": 99500,
    "fiatCurrency": "NGN",
    "cryptoAmount": 62.18,
    "token": "USDT",
    "chain": "BSC_MAINNET",
    "destinationAddress": "0xYourWalletAddress...",
    "conversionRate": 1600,
    "platformFee": 0.31,
    "businessFee": 0,
    "gasFee": 0.5,
    "transactionHash": "0xsettlement123...",
    "status": "COMPLETED"
  }
}

4

Query deposits and settlements

List all deposits

curl -X GET "https://ramp-api.ivorypay.io/api/v1/deposits" \
  -H "Authorization: your_api_key"

GET /v1/deposits does not currently accept query filters — it returns the merchant's deposits as wired by the controller.

Get settlement for a specific deposit

The :depositId path parameter is validated as a UUID.

curl -X GET "https://ramp-api.ivorypay.io/api/v1/settlements/deposit/f1e2d3c4-b5a6-7890-fedc-ba0987654321" \
  -H "Authorization: your_api_key"

Settlement lifecycle

DEPOSIT RECEIVED → AWAITING_SETTLEMENT_ACCOUNT → CONVERTING → PAYOUT_INITIATED
  → PAYOUT_PROCESSING → COMPLETED
                      → FAILED

Frequently asked questions

How long does settlement take after a deposit is received?

Settlement typically completes within a few minutes after the deposit is confirmed. The exact time depends on blockchain network congestion and the conversion process. You can track progress in real time via the settlement lifecycle webhooks (settlement.converting, settlement.payoutInitiated, settlement.payoutProcessing, settlement.success).

What happens if a settlement fails?

If a settlement fails, you will receive a settlement.failed webhook with a failureReason field explaining the cause. Common reasons include wallet configuration issues or temporary network problems. Contact IvoryPay support if the issue persists, as failed settlements may need to be retried on their end.

Can a user send multiple deposits to the same virtual account?

Yes. Virtual accounts are persistent and can receive multiple deposits over time. Each deposit triggers its own deposit.received webhook and initiates a separate settlement cycle. There is no need to create a new virtual account for each transaction.

What does the settlement.awaitingSettlementAccount stage mean?

This stage means IvoryPay is waiting for a settlement account (destination crypto wallet) to be configured for your business. If you see settlements stuck in this stage, check your IvoryPay dashboard to ensure your settlement wallet address is properly set up.

Why is the settledAmount different from the receivedAmount?

The settledAmount may be less than the receivedAmount due to platform fees deducted by IvoryPay before settlement. The difference represents the fee charged for processing the deposit. You can see the detailed fee breakdown in the settlement webhook payload.

Can I query historical deposits and settlements via the API?

Yes. Use GET /v1/deposits to list all deposits for your merchant account (no query filters are currently wired). Use GET /v1/settlements/deposit/{depositId} — where depositId is a UUID — to retrieve the settlement details for a specific deposit.