Fiat payment intents

A fiat payment intent creates a time-limited virtual bank account for an NGN collection and records the approved crypto settlement destination.

Fiat availability depends on the banking provider and settlement configuration enabled for your organization. The current API accepts NGN. With the currently enabled network policy, the production path is TRON settlement using an active supported token such as USDC. Confirm the exact asset during onboarding.

Get the current fiat rate#

GET /payment/fiat-rate?currency=ngn

Query field	Type	Required	Description
`currency`	string	no	Defaults to `ngn`. Other currency values currently return an error.

bash

curl --request GET \
  --url 'https://bridge.relayfinance.io/payment/fiat-rate?currency=ngn' \
  --header 'accesskey: YOUR_ORGANIZATION_API_KEY'

json

{
  "success": true,
  "data": {
    "currency": "ngn",
    "rate": 1652.5
  },
  "meta": {
    "requestId": "ee26a15c-6224-4d2e-9c78-5574a80c358c"
  }
}

rate is the buffered NGN-per-USD conversion rate as a JSON number. It is indicative and can change before intent creation; use the values returned on the created payment as the final quote for that intent.

Create a fiat payment intent#

POST /payment/create-fiat-payment-intent

Returns HTTP 201 Created with a payment object and fiatDetail virtual-account instructions.

Request fields#

Field	Type	Required	Description
`amount`	number	yes	Fiat amount the customer must pay. Must be greater than zero.
`currency`	string	yes	Currently `ngn`.
`txRef`	string	yes	Your merchant order or invoice reference. Not an idempotency key.
`useremail`	string	yes	Valid customer email address.
`postTransactionType`	string	no	`external_wallet` by default, or `organization_settlement`.
`settlement`	object	yes	Crypto network, token, and—when required—destination.
`settlement.network`	string	yes	Enabled settlement network.
`settlement.token`	string	yes	Enabled settlement token. Fiat logic permits USDC and, where the network is enabled, ETH.
`settlement.address`	string	conditional	Required for `external_wallet`; must be omitted for `organization_settlement`.
`validFor`	number	no	Requested virtual-account validity in seconds. The provider may return the effective value.
`metadata`	object	no	Your structured correlation data.

json

{
  "amount": 500000,
  "currency": "ngn",
  "txRef": "invoice-2218",
  "useremail": "buyer@example.com",
  "postTransactionType": "organization_settlement",
  "settlement": {
    "network": "tron",
    "token": "USDC"
  },
  "validFor": 1800,
  "metadata": {
    "customerId": "cus_18fd"
  }
}

Virtual-account response#

json

{
  "success": true,
  "data": {
    "txRef": "invoice-2218",
    "type": "fiat",
    "direction": "deposit",
    "cryptonetwork": "tron",
    "cryptotoken": "USDC",
    "expectedAmount": "302.571860817",
    "rate": "1652.5",
    "expectedSettlementTokenAmount": "302.571860817",
    "virtualAccountExpiresAt": "2026-09-20T12:30:00.000Z",
    "virtualAccountExpiresIn": 1800,
    "txId": "RLY-01K5W6K8A2T9",
    "status": "pending",
    "fiatDetail": {
      "fiatCurrency": "ngn",
      "fiatAmount": "500000",
      "settlementNetwork": "tron",
      "settlementToken": "USDC",
      "settlementAddress": "TQ9ExampleDestinationAddress",
      "virtualAccountNumber": "1234567890",
      "virtualAccountBankCode": "090286",
      "virtualAccountAccountName": "Relay / invoice-2218",
      "virtualAccountCurrencyCode": "NGN",
      "virtualAccountStatus": "ACTIVE",
      "virtualAccountValidFor": 1800,
      "virtualAccountExpiryDate": "2026-09-20T12:30:00.000Z"
    }
  },
  "meta": {
    "requestId": "1563bb6a-bc85-4d33-b2c3-f5d42af9120e"
  }
}

Display the account name, number, bank details, exact NGN amount, and expiry to the customer. Do not display or use the internal callback URL if one appears in fiatDetail.

Retrieve and reconcile#

Use the same retrieval route as crypto payments:

GET /payment/get-payment-intent/{txId}

The response contains the same payment and fiat fields. Bank-provider notifications update the intent asynchronously, so receive payment webhooks and periodically reconcile pending records through retrieval.

Common errors#

HTTP	Message	Cause
`400`	`Only NGN is supported for fiat intents`	Unsupported fiat currency
`400`	`Invalid settlement details`	Missing network, token, or required address
`400`	`Omit settlement.address when using organization_settlement`	Address supplied when Relay should resolve the saved destination
`400`	`Network is disabled`	Settlement network is not enabled for new work
`400`	`Solana is supported for crypto payment intents only`	Solana selected for fiat settlement
`400`	`Only USDC and ETH are supported for settlement`	Unsupported settlement asset
`400`	`Unable to fetch exchange rate`	The pricing provider is temporarily unavailable
`400`	provider/configuration-specific message	Virtual-account creation or settlement configuration failed