Skip to main content
The fiat on-ramp lets customers who do not hold cryptocurrency pay using Nigerian bank transfers (NIBSS). When on-ramp is enabled on a payment link, the checkout flow defaults to the on-ramp experience — customers enter their email, receive a dynamically generated virtual bank account, and complete payment by transferring Naira. ZendFi converts the NGN to crypto and settles to the merchant’s wallet.
The on-ramp currently supports NIBSS-based bank transfers for Nigerian payers (NGN) only. Support for additional currencies and payment methods is coming soon.

​
How It Works

​
On-Ramp Checkout Flow

When onramp is set to true on a payment link, the checkout replaces the standard crypto checkout with a dedicated on-ramp flow. The customer does not see wallet connect, QR codes, or manual transfer options — the entire experience is optimized for bank transfers.

​
Step-by-Step

1

Email and customer details

The customer enters their email address. If collect_customer_info is enabled on the payment link (via the REST API), additional fields are shown: name, phone, company, and an optional billing address.
2

Session initiation and verification

ZendFi initiates an on-ramp session and performs background OTP verification. The customer stays on the email screen with a loading indicator while this happens (typically a few seconds).
3

Bank transfer details

Once verified, the customer sees a virtual bank account with:
  • Bank name — the receiving bank
  • Account name — the virtual account holder name
  • Account number — a unique account number for this transaction
  • Amount in NGN — the exact Naira amount to transfer (including any service charges)
The customer transfers the exact amount using their bank app, USSD, or internet banking. The virtual account expires after 30 minutes.
4

Payment confirmation

ZendFi polls for the incoming bank transfer. Once the NIBSS payment is confirmed, the checkout shows a success screen. If the transfer takes longer than 15 minutes, the checkout moves to an “Under Review” state where the customer is assured their payment is being processed and given support contact details.

​
Enable On-Ramp

Set onramp: true when creating a payment link: 
const link = await zendfi.createPaymentLink({
  amount: 49.99,
  currency: 'USD',
  description: '12 months of Pro features',
  onramp: true,
});

console.log('Payment link:', link.url);
// Checkout defaults to the NGN bank transfer flow
When a customer opens this link, they go straight into the on-ramp flow — no crypto wallet required.

​
Supported Payment Method

MethodNetworkCoverage
Bank TransferNIBSSAll major Nigerian banks
Customers can pay from any Nigerian bank that supports NIBSS transfers, which covers virtually all commercial banks in Nigeria.

​
Currency and Conversion

DetailValue
Customer pays inNGN (Nigerian Naira)
Amount displayed asNGN with service charge breakdown
Merchant receivesUSDC (on Solana)
Exchange rateMarket rate at time of payment
The checkout displays the total amount in Naira, including any applicable service charges. If a service charge applies, the breakdown is shown: 
₦75,000
₦73,500 + ₦1,500 service fee

​
Customer Info Collection

When collect_customer_info is enabled on the payment link via the REST API, the email step expands to collect additional details:
FieldRequiredDescription
EmailYesReceipt and verification
Full nameNoCustomer’s name
Phone numberNoContact number
CompanyNoBusiness name
Billing addressNoStreet, city, state, postal code, country
This information is submitted to the ZendFi API once the payment is created, and is available in the payment details and webhooks. 
const link = await zendfi.createPaymentLink({
  amount: 99.99,
  currency: 'USD',
  description: 'One-time license purchase',
  onramp: true,
  metadata: {
    product_id: 'prod_enterprise',
    license_type: 'perpetual',
  },
});

​
Options

FieldTypeRequiredDescription
amountnumberYesPayment amount in USD
currencystringNoCurrency code (defaults to USD)
descriptionstringNoDescription shown on checkout
onrampbooleanNoEnable the on-ramp flow (defaults checkout to bank transfer)
metadataobjectNoCustom key-value metadata
The REST API also supports collect_customer_info (boolean) to collect additional customer details (name, phone, address). This field is not available in the SDK type but can be passed via direct API calls.

​
Webhook Handling

On-ramp payments fire the same webhook events as crypto payments. Your webhook handler does not need any special logic: 
handlers: {
  'payment.confirmed': async (payment) => {
    // This fires for both crypto and on-ramp payments
    console.log('Payment confirmed:', payment.id);

    // The settlement is always in crypto regardless of payment method
    await fulfillOrder(payment.id);
  },
}

​
Settlement

Regardless of whether the customer paid with crypto or via the on-ramp, the merchant always receives crypto:
Customer PaysMerchant Receives
USDC (directly)USDC
NGN bank transfer (via on-ramp)USDC
SOL (directly)SOL
The on-ramp handles the NGN-to-USDC conversion. From the merchant’s perspective, all payments settle identically.

​
API Endpoint

Create payment links with on-ramp enabled via the REST API: 
curl -X POST https://api.zendfi.tech/api/v1/payment-links \
  -H "Authorization: Bearer zfi_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.99,
    "currency": "USD",
    "description": "Pro Plan",
    "onramp": true
  }'

​
Payment Lifecycle

​
Under Review State

If the bank transfer is not confirmed within 15 minutes, the checkout transitions to an “Under Review” screen. This is not a failure — Nigerian bank transfers can sometimes take longer to process. The screen explains what is happening and provides a support email (dispute@zendfi.tech) with the payment reference pre-filled. The payment will still be confirmed automatically once the transfer clears. The customer does not need to take any additional action.

​
Testing

In test mode (zfi_test_ key), on-ramp payments use sandbox credentials. No real Naira is transferred. 
# Create a payment link with on-ramp
curl -X POST https://api.zendfi.tech/api/v1/payment-links \
  -H "Authorization: Bearer zfi_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{"amount": 25, "currency": "USD", "description": "Test On-Ramp", "onramp": true}'

# Open the returned URL
# Enter a test email and complete the flow
# The test environment simulates the bank transfer confirmation

​
Use Cases

​
Nigerian SaaS customers

Many Nigerian users do not hold crypto. Enable on-ramp so they can pay with their regular bank account while you still receive USDC settlement: 
const link = await zendfi.createPaymentLink({
  amount: 29.99,
  currency: 'USD',
  description: 'Pro Plan - Monthly',
  onramp: true,
});

​
E-commerce for Nigerian buyers

Accept payments from Nigerian customers using the payment method they are most familiar with — bank transfers: 
const link = await zendfi.createPaymentLink({
  amount: 15.00,
  currency: 'USD',
  description: 'Order #1234 - Wireless earbuds',
  onramp: true,
});

​
Donation and fundraising

Accept donations from Nigerian supporters without requiring them to have a crypto wallet: 
const link = await zendfi.createPaymentLink({
  amount: 10,
  currency: 'USD',
  description: 'Support Our Project - One-time donation',
  onramp: true,
});

​
Coming Soon

The on-ramp is expanding beyond Nigeria. Planned additions include:
  • Additional African currencies (GHS, KES, ZAR)
  • Card payments (Visa, Mastercard)
  • Mobile money (M-Pesa, MTN MoMo)
  • SEPA transfers (EUR)
Check the changelog for updates as new payment methods go live.