Cross Currency Payouts

The Endpoint allows you to convert funds between currency pairs.

Request parameters

Pass these as request body on the /fx-quotes endpoint.

string

The currency you want to convert to. ISO 4217 format.

string

The currency you want to convert from. ISO 4217 format.

number

The amount you want to convert to. This is conditionally required.

number

The amount you want to convert from. This is conditionally required.

string

The ID of the account from which to debit the funds.

string

required

The ID of the counterparty involved in the exchange.

string

required

The ID of the payment details associated with the exchange.

Convert funds between currency pairs.

You can specify either the amount_to or amount_from field, but not both. The endpoint calculates the other amount based on the current exchange rate.

  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \ 
  -d '{
  "to_currency": "NGN",
  "from_currency": "USD",
  "amount_to": 100,
  "amount_from": 100,
  "account_id": "acc-id",
  "counterparty_id": "cp_id", //Required
  "payment_detail_id":  "pd_id", // Required
}'

Response Parameters

string

Unique entity identifier.

string

Currency converted to.

number

The exchange rate applied to the conversion.

string

Currency converted from

object

The quote details associated with this forex exchange.

Show quote fields

null

Timestamp for when the quote was used in a forex exchange.

number

Timestamp for when the quote expires.

null

The ID of the payment that utilized this quote.

number

The duration in seconds for which the quote is valid.

string

The current status of the quote. Example active.

number

Timestamp for when the forex exchange was created.

number

Timestamp for when the forex exchange was last updated.

Example

{
  "id": "01HXYZ5678EFGH",
  "to": "NGN",
  "from": "USD",
  "rate": 750,
  "quote": {
    "used_at": null,
    "expires_at": 1700000000,
    "used_in_payment_id": null,
    "valid_for": 300,
    "status": "active"
  },
  "created": 1690000000,
  "updated": 1690000000
}

Initiate Transfer

To initiate a cross currency transfer, you can use the id of the forex exchange in the fx_quote_id field when creating a payment. This will apply the exchange rate from the forex exchange to the payment.

Request parameters

string

required

The ID of the source account to debit.

string

required

The ID of the payment detail record with payment_method: "momo-transfer".

string

required

The payment type of the transfer. It can be bank-transfer, momo-transfer, stablecoin-transfer, and book-transfer.

string

required

Transfer description. Maximum 100 characters.

string

required

Idempotency key. Maximum 64 characters.

string

required

The ID of the forex exchange quote to apply to this transfer.

Request

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

Get Started

Core Concepts

Webhooks

Guides

Cross Currency Payouts

Request parameters

Convert funds between currency pairs.

Response Parameters

Initiate Transfer

Request parameters

Request

​Request parameters

​Convert funds between currency pairs.

​Response Parameters

​Initiate Transfer

​Request parameters

​Request

Request parameters

Convert funds between currency pairs.

Response Parameters

Initiate Transfer

Request parameters

Request