Cross Currency Payouts

Nuvion converts funds between currency pairs at the point of a transfer. This guide covers requesting an FX quote and applying it to a transfer. It assumes you’ve completed Steps 1–2 of Send a Payout to create a counterparty and register their payment details in the destination currency.

Step 1: Create an FX quote

Request a quote to lock in an exchange rate before sending funds in a currency different from the source account’s. Use POST /fx-quotes, passing either amount_from or amount_to. See FX Quotes for the full request and response field reference.

curl -X POST https://api.nuvion.dev/fx-quotes \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_currency": "USD",
    "to_currency": "GHS",
    "amount_from": 5000,
    "account_id": "01KR3NQSCAY9SC8WVKWAX2XJAB"
  }'

Response

{
  "status": "success",
  "message": "FX quote created successfully",
  "data": {
    "id": "01HXYZ4680ABCDEFGHJKMNPQRS",
    "from": "USD",
    "to": "GHS",
    "amount_from": 5000,
    "amount_to": 50180,
    "rate": 10.036105,
    "quote": {
      "status": "active",
      "expires_at": 1787286987311,
      "valid_for": 179,
      "used_at": null,
      "used_in_payment_id": null
    },
    "created": 1787286808311,
    "updated": 1787286808311
  }
}

A quote is only valid for a limited window. Check quote.valid_for (in seconds) and quote.expires_at before using it on a transfer.

Step 2: Initiate the transfer

Pass the FX quote’s id as fx_quote_id on the transfer. Nuvion applies the rate locked in by the quote, debiting the source account in currency (the quote’s from_currency) and paying out via payment_detail_id in the destination currency.

Request parameters

string

required

The id of the FX quote from Step 1.

fx_quote_id is the only field this guide adds. See Send a Payout: Step 3 for the full set of transfer fields (account_id, payment_detail_id, counterparty_id, amount, currency, payment_type, narration, unique_reference).

curl -X POST https://api.nuvion.dev/transfers \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "01KR3NQSCAY9SC8WVKWAX2XJAB",
    "payment_detail_id": "01HXYZ8024ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ3579ABCDEFGHJKMNPQRS",
    "amount": 5000,
    "currency": "USD",
    "narration": "Invoice payment INV-2025-001",
    "payment_type": "bank-transfer",
    "unique_reference": "PAY-2025-001",
    "fx_quote_id": "01HXYZ4680ABCDEFGHJKMNPQRS"
  }'

See Create a bank transfer for the full response schema and error codes.

Get Started

Core Concepts

Webhooks

Guides

Cross Currency Payouts

Step 1: Create an FX quote

Response

Step 2: Initiate the transfer

Request parameters

​Step 1: Create an FX quote

​Response

​Step 2: Initiate the transfer

​Request parameters

Step 1: Create an FX quote

Response

Step 2: Initiate the transfer

Request parameters