Skip to main content
POST
/
v1
/
transactions
/
fiat-payouts
cURL
curl --request POST \
  --url https://api.nxos.io/v1/transactions/fiat-payouts \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "beneficiaryId": "bene_d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1",
  "amount": "49985.00",
  "asset": "USD",
  "method": "WIRE"
}
'
{
  "object": "transaction",
  "transactionId": "txn_d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1",
  "type": "FIAT_PAYOUT",
  "status": "LOCKED",
  "accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "beneficiaryId": "bene_d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1",
  "amount": "49985.00",
  "asset": "USD",
  "method": "WIRE",
  "bank": {
    "bankName": "JPMorgan Chase",
    "swiftCode": "CHASUS33",
    "accountNumber": "123456789",
    "iban": null
  },
  "fee": {
    "fixed": "50.00",
    "bps": 0,
    "bpsAmount": "0.00",
    "total": "50.00",
    "asset": "USD"
  },
  "createdAt": "2025-03-15T14:32:00.000Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.nxos.io/llms.txt

Use this file to discover all available pages before exploring further.

Headers

​
Authorization
string
required

Bearer token. Format: Bearer <api_key>

​
Idempotency-Key
string

Unique key per logical operation. UUID v4 recommended. Max 255 characters.

Body

application/json

Request body for initiating a fiat payout.

​
accountId
string
required

Source account to debit.

​
beneficiaryId
string
required

Bank beneficiary to pay out to.

​
amount
string
required

Payout amount in major units (e.g. "10000.00").

​
asset
string
required

Asset code (e.g. USD, EUR).

​
method
string
required

Transfer method (e.g. WIRE, SEPA).

​
expectedFeeSchedule
object

Optional pin against fee drift. Echo the schedule returned by GET /v1/fees/fiat-payout to guarantee we charge exactly what you quoted. If the schedule has changed since the quote, we return 409 fee_schedule_drifted and the client should refresh + retry. Omit to accept whatever the current schedule says.

​
description
string

Optional description.

​
tags
string[]

Free-form tags (max 20 tags, each up to 100 characters).

​
metadata
object

Arbitrary metadata (max 50 keys, max 4 KB serialized).

Response

The request has succeeded.

A fiat payout transaction in LOCKED state, awaiting provider execution.

​
object
enum<string>
required

Object type. Always transaction.

Available options:
transaction
​
transactionId
string
required

Unique transaction identifier.

​
type
enum<string>
required

Transaction type. Always FIAT_PAYOUT.

Available options:
FIAT_PAYOUT
​
status
enum<string>
required

Transaction status. LOCKED after initiation.

Available options:
LOCKED
​
accountId
string
required

Source account.

​
beneficiaryId
string
required

Target beneficiary.

​
amount
string
required

Payout amount in major units.

​
asset
string
required

Asset code.

​
method
string
required

Transfer method.

​
bank
object
required

Snapshot of bank details at time of payout.

​
fee
object
required

Fee breakdown for this transaction. Always populated; every component is zero when no fee applies. amount is what the beneficiary receives; the user's account is debited amount + fee.total.

Example:
{
  "fixed": "50.00",
  "bps": 0,
  "bpsAmount": "0.00",
  "total": "50.00",
  "asset": "USD"
}
​
createdAt
string
required

When the transaction was created.