Remittance

Send cross-border transfers (e.g. NGN → GBP) via Flutterwave. Requires API key authentication and KYC approval.

Auth required: API key (X-API-Key)
Base path: /api/v1/remittance

For dashboard-initiated transfers (JWT + 2FA), see the JWT variant below.

---

Get Quote

POST /api/v1/remittance/quote
X-API-Key: <key>
Content-Type: application/json

{
  "business_id": "your-business-uuid",
  "source_currency": "NGN",
  "source_amount": "5000000",
  "dest_currency": "GBP"
}

Response

{
  "source_currency": "NGN",
  "source_amount": "5000000.00",
  "dest_currency": "GBP",
  "dest_amount": "2500.00",
  "exchange_rate": 0.0005,
  "fee_amount": "62500.00",
  "fee_percent": "1.25",
  "rpay_discount_applied": true,
  "rpay_discount_amount": "12500.00",
  "total_cost": "5062500.00",
  "estimated_time": "15-30 minutes"
}

---

Create Transfer

Requires an HMAC-SHA256 request signature in the X-Transfer-Signature header to prevent replay attacks.

POST /api/v1/remittance/transfer
X-API-Key: <key>
X-Transfer-Signature: <hmac>
Content-Type: application/json

{
  "business_id": "your-business-uuid",
  "source_currency": "NGN",
  "source_amount": "5000000",
  "dest_currency": "GBP",
  "recipient_name": "Sarah's Fabrics Ltd",
  "recipient_account": "12345678",
  "recipient_bank": "Barclays",
  "recipient_email": "sarah@sarahsfabrics.co.uk",
  "recipient_country": "GB",
  "reference": "INV-001",
  "purpose": "Payment for fabric order"
}

Response (201 Created)

{
  "id": "1",
  "business_uuid": "...",
  "source_currency": "NGN",
  "source_amount": "5000000.00",
  "dest_currency": "GBP",
  "dest_amount": "2500.00",
  "recipient_name": "Sarah's Fabrics Ltd",
  "status": "pending",
  "exchange_rate": "0.0005",
  "fee_amount": "62500.00",
  "rpay_discount_used": true,
  "created_at": "2025-06-18T10:00:00Z"
}

---

Get Transfer

GET /api/v1/remittance/transfers/:id
X-API-Key: <key>

---

List Transfers

GET /api/v1/remittance/transfers?business_id=<uuid>&limit=50&offset=0
X-API-Key: <key>

---

List Exchange Rates

GET /api/v1/remittance/rates
X-API-Key: <key>

Returns rates for supported pairs: NGNCNY, NGNUSD, NGNGBP, USDCNY.

---

JWT Dashboard Variant

When initiating a remittance from the dashboard (not via API key), use:

POST /api/v1/remittance/create
Authorization: Bearer <token>
Content-Type: application/json

Same fields as above, plus otp_code if 2FA is enabled:

{
  "business_id": "...",
  "source_currency": "NGN",
  "source_amount": "5000000",
  "dest_currency": "GBP",
  "recipient_name": "Sarah's Fabrics Ltd",
  "recipient_account": "12345678",
  "recipient_bank": "Barclays",
  "recipient_country": "GB",
  "otp_code": "123456"
}

---

Transfer Status Flow

pending → processing → completed
                    ↘ failed