Cross-Border Remittance

Receive local currency (NGN), hold USD, and pay out globally.

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 using a supported payout currency.

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.
3. Outflow (Off-Ramp): You define a recipient and initiate a withdrawal to them in their local currency.

1. Receive Funds (NGN)

First, generate a virtual account or payment instruction for your customer to send NGN.

Use the Create Deposit endpoint.

cURL

curl -X POST "https://api.bullring.finance/v1/ramp/{subaccountId}/banking/deposits" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "ngn-channel-id-bullring-finance",
    "source": {
      "accountType": "bank"
    }
  }'

Expected Response

{
  "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 (GHS)

Before paying your supplier, save their payout details as a recipient.

Use the Create Recipient endpoint.

cURL

curl -X POST "https://api.bullring.finance/v1/ramp/{subaccountId}/banking/recipients" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "GHS",
    "phone_number": "[phone]",
    "account_owner_name": "Supplier Company"
  }'

Expected Response

{
  "id": "e1780b01-39d0-4c9c-89cf-27585d5b6004",
  "currency": "GHS",
  "account_owner_name": "Supplier Company",
  "status": "active"
}

3. Pay Supplier (GHS)

Finally, initiate the transfer to the recipient you just created.

Use the Create Withdrawal endpoint.

cURL

curl -X POST "https://api.bullring.finance/v1/ramp/{subaccountId}/banking/withdrawals" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_id": "e1780b01-39d0-4c9c-89cf-27585d5b6004",
    "amount": "5000",
    "currency": "GHS"
  }'

Expected Response

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