Skip to main content

​
Overview

This guide demonstrates how an exporter in Nigeria can receive payments in Nigerian Naira (NGN), automatically convert them to USD to hedge against devaluation, and subsequently pay suppliers in Europe using Euros (EUR).

​
Mental Model

When using the Bullring API for this flow, think of it as a three-step pipeline:
  1. Inflow (On-Ramp): You request a deposit instruction. The customer pays NGN to a local bank account. Bullring detects this and credits the subaccount in USD.
  2. Storage: Funds are held in the subaccount in USD (Stablecoin).
  3. Outflow (Off-Ramp): You define a beneficiary (Recipient) and initiate a withdrawal to them in their local currency (EUR).

​
1. Receive Funds (NGN)

First, generate a virtual account or payment instruction for your customer to send NGN. Use the Create Deposit endpoint. 
curl -X POST "https://api.bullring.finance/v1/ramp/{subaccountId}/banking/deposits" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "ngn-channel-id-bullring-finance",
    "source": {
      "accountType": "bank"
    }
  }'

​
Expected Response

The API returns banking details that you should present to your customer. 
{
  "status": "pending",
  "currency": "USD",
  "country": "NG",
  "rate": 1500.50,
  "localCurrency": "NGN",
  "bankInfo": {
    "bankBeneficiaryName": "Bullring/Merchant Name",
    "bankName": "Providus Bank",
    "bankAccountNumber": "1234567890"
  },
  "channelId": "ngn-channel-id-bullring-finance"
}
Once the customer transfers the funds, the subaccount balance is credited in USD.

​
2. Create Recipient (EUR)

Before paying your supplier, you must save their banking details as a Recipient. Use the Create Recipient endpoint. 
curl -X POST "https://api.bullring.finance/v1/ramp/{subaccountId}/banking/recipients" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "account_owner_name": "European Supplier Ltd",
    "bank_name": "Deutsche Bank",
    "account_number": "DE89370400440532013000",
    "bic": "DEUTDEBBXXX",
    "country": "DE",
    "account_owner_type": "company"
  }'

​
Expected Response

{
  "id": "e1780b01-39d0-4c9c-89cf-27585d5b6004",
  "currency": "EUR",
  "account_owner_name": "European Supplier Ltd",
  "account_number": "DE89370400440532013000",
  "bank_name": "Deutsche Bank",
  "status": "active"
}

​
3. Pay Supplier (EUR)

Finally, initiate the transfer to the recipient you just created. The USD balance in the subaccount will be converted to EUR. Use the Create Withdrawal endpoint. 
curl -X POST "https://api.bullring.finance/v1/ramp/{subaccountId}/banking/withdrawals" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "external_account_id": "e1780b01-39d0-4c9c-89cf-27585d5b6004",
    "amount": "5000",
    "currency": "EUR",
    "sepa_message": "Invoice #INV-2024-001"
  }'

​
Expected Response

{
  "id": "withdrawal-uuid-1234",
  "amount": "5000",
  "currency": "EUR",
  "status": "processing",
  "created_at": "2024-01-01T12:00:00Z",
  "fee_amount": "5.00"
}