Buy & Sell

Simplified fiat-in and fiat-out flows using IvoryPay's Buy and Sell features.

Buy and Sell are simplified flows where IvoryPay handles the crypto conversion internally. Unlike On-Ramp/Off-Ramp, the user doesn't interact with crypto directly — they deal in fiat only.

Buy: Collect fiat from users

The Buy flow collects fiat from a user via bank transfer. This is useful for topping up user wallets, collecting payments, or funding accounts.

Buy integration steps

1

Initiate the Buy transaction

Call POST /v1/buy with the user and payment details:

curl -X POST https://ramp-api.ivorypay.io/api/v1/buy \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Kemi",
    "lastName": "Adeyemi",
    "email": "[e-mail]",
    "fiatAmount": 25000,
    "fiatCurrency": "NGN",
    "reference": "770e8400-e29b-41d4-a716-446655440002",
    "redirectUrl": "https://yourapp.com/payment/complete"
  }'

Response

{
  "statusCode": 200,
  "success": true,
  "message": "Buy initiated successfully",
  "data": {
    "firstName": "Kemi",
    "lastName": "Adeyemi",
    "email": "[e-mail]",
    "refCode": "buy123abc0",
    "reference": "770e8400-e29b-41d4-a716-446655440002",
    "transferDetails": {
      "id": "uuid-here",
      "accountName": "IvoryPay - Kemi Adeyemi",
      "accountNumber": "9876543210",
      "bank": "Providus Bank",
      "amountPayable": 25000,
      "expiresAt": "2026-03-26T13:00:00.000Z",
      "currency": "NGN",
      "businessFee": 0,
      "platformFee": 125,
      "createdAt": "2026-03-26T12:00:00.000Z",
      "checkoutUrl": "https://checkout.ivorypay.io/pay/buy123"
    }
  }
}

2

User pays via bank transfer or checkout

Direct the user to the checkoutUrl or display the bank account details (accountNumber, bank, amountPayable) in your own UI. The user completes the payment via bank transfer.

3

Listen for Buy webhooks

Event	Description
buy.success	Payment received and confirmed
buy.failed	Payment processing failed
buy.mismatch	Amount received differs from expected amount

Webhook payload: buy.success

{
  "event": "buy.success",
  "data": {
    "reference": "770e8400-e29b-41d4-a716-446655440002",
    "status": "SUCCESS",
    "accountNumber": "9876543210",
    "currency": "NGN",
    "accountName": "IvoryPay - Kemi Adeyemi",
    "bankName": "Providus Bank",
    "amount": 25000,
    "customer": { ... }
  }
}

---

Sell: Send fiat to users

The Sell flow sends fiat to a user's bank account. This is useful for disbursements, withdrawals, or payouts.

Sell integration steps

1

Initiate the Sell transaction

Call POST /v1/sell with the recipient and payout details:

curl -X POST https://ramp-api.ivorypay.io/api/v1/sell \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Tunde",
    "lastName": "Bakare",
    "email": "[e-mail]",
    "fiatAmount": 75000,
    "fiatCurrency": "NGN",
    "accountNumber": "0123456789",
    "bankCode": "058",
    "reference": "880e8400-e29b-41d4-a716-446655440003",
    "redirectUrl": "https://yourapp.com/payout/complete"
  }'

Response

{
  "statusCode": 200,
  "success": true,
  "message": "Sell initiated successfully",
  "data": {
    "firstName": "Tunde",
    "lastName": "Bakare",
    "email": "[e-mail]",
    "refCode": "sell456xyz",
    "reference": "880e8400-e29b-41d4-a716-446655440003",
    "transferDetails": {
      "id": "uuid-here",
      "currency": "NGN",
      "businessFeeInFiat": 0,
      "platformFeeFiat": 375,
      "fiatAmount": 75000,
      "accountName": "Tunde Bakare",
      "accountNumber": "0123456789"
    }
  }
}

2

IvoryPay processes the bank transfer

Once initiated, IvoryPay handles the fiat payout to the user's bank account automatically. No further action is required from your side.

3

Listen for Sell webhooks

Event	Description
sell.success	Fiat payout delivered to bank account
sell.failed	Payout failed
sell.cancelled	Payout was cancelled

---

When to use Buy/Sell vs On-Ramp/Off-Ramp

Feature	Buy / Sell	On-Ramp / Off-Ramp
User interacts with crypto	No	Yes
Requires wallet address	No	Yes (On-Ramp)
Requires bank account	Yes (Sell)	Yes (Off-Ramp)
Use case	Fiat collection/disbursement	Crypto purchase/sale
Business fee support	Yes (businessFeeInFiat)	Yes (fiat or crypto)

Frequently asked questions

What is the difference between Buy/Sell and On-Ramp/Off-Ramp?

Buy and Sell are simplified fiat-only flows where the user never interacts with cryptocurrency directly. On-Ramp and Off-Ramp involve the user sending or receiving crypto to/from a wallet address. Use Buy/Sell when you want to abstract away the crypto layer entirely, and On-Ramp/Off-Ramp when the user needs to work with crypto wallets.

What does the buy.mismatch event mean?

The buy.mismatch event fires when the fiat amount received from the user does not match the expected amountPayable. For example, if you requested 25,000 NGN but the user transferred 20,000 NGN. You should handle this in your application by notifying the user and deciding whether to accept the partial payment or request the remaining amount.

What happens if a Buy payment session expires?

The virtual bank account details are only valid until the expiresAt time. If the user does not pay before this deadline, the transaction expires. You will need to create a new Buy transaction. Consider displaying a countdown timer in your UI so the user is aware of the deadline.

Why did my Sell payout fail or get cancelled?

A sell.failed event means the bank transfer could not be completed. Common causes include invalid bank details, bank downtime, or compliance issues. A sell.cancelled event means the payout was explicitly cancelled. Check the webhook payload for details, correct the issue, and create a new Sell transaction if needed.

Can I add a business fee to Buy and Sell transactions?

Yes. You can include a businessFeeInFiat field in your request to add a fee on top of the transaction amount. This fee is collected by your business. The platform fee charged by IvoryPay is separate and shown in the response.