Initiate fiat payout
Initiate a fiat payout from an account to a bank beneficiary. Funds are debited and locked immediately. The transaction enters LOCKED status and awaits provider execution.
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",
"purpose": "SUPP"
}
'import requests
url = "https://api.nxos.io/v1/transactions/fiat-payouts"
payload = {
"accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"beneficiaryId": "bene_d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1",
"amount": "49985.00",
"asset": "USD",
"method": "WIRE",
"purpose": "SUPP"
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
accountId: 'acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
beneficiaryId: 'bene_d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1',
amount: '49985.00',
asset: 'USD',
method: 'WIRE',
purpose: 'SUPP'
})
};
fetch('https://api.nxos.io/v1/transactions/fiat-payouts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nxos.io/v1/transactions/fiat-payouts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'accountId' => 'acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
'beneficiaryId' => 'bene_d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1',
'amount' => '49985.00',
'asset' => 'USD',
'method' => 'WIRE',
'purpose' => 'SUPP'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.nxos.io/v1/transactions/fiat-payouts"
payload := strings.NewReader("{\n \"accountId\": \"acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n \"beneficiaryId\": \"bene_d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1\",\n \"amount\": \"49985.00\",\n \"asset\": \"USD\",\n \"method\": \"WIRE\",\n \"purpose\": \"SUPP\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.nxos.io/v1/transactions/fiat-payouts")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"accountId\": \"acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n \"beneficiaryId\": \"bene_d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1\",\n \"amount\": \"49985.00\",\n \"asset\": \"USD\",\n \"method\": \"WIRE\",\n \"purpose\": \"SUPP\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nxos.io/v1/transactions/fiat-payouts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"accountId\": \"acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n \"beneficiaryId\": \"bene_d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1\",\n \"amount\": \"49985.00\",\n \"asset\": \"USD\",\n \"method\": \"WIRE\",\n \"purpose\": \"SUPP\"\n}"
response = http.request(request)
puts response.read_body{
"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"
}{
"error": {
"code": "invalid_request",
"message": "The request body is malformed or missing required fields.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "missing_api_key",
"message": "No Authorization header provided.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "forbidden",
"message": "Your organization is not enabled for this action.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "not_found",
"message": "The requested resource was not found.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "quote_expired",
"message": "The quote has expired.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded: 1000 requests per minute. Retry in 23 seconds.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected server error occurred.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}Headers
Bearer token. Format: Bearer <api_key>
Unique key per logical operation. UUID v4 recommended. Max 255 characters.
Body
Request body for initiating a fiat payout.
Source account to debit.
Bank beneficiary to pay out to.
Payout amount in major units (e.g. "10000.00").
Asset code (e.g. USD, EUR).
Transfer method (e.g. WIRE, SEPA).
Why the money is moving. Reported to the central bank, and the code that reaches the bank is derived from this one, so send the value that describes the payment rather than a fixed default. Read the accepted values from Get fiat payout options rather than hardcoding them.
GDDS, SUPP, SCVE, GDSV, IVPT, TRAD, ADVA, BEXP, SUBS, REFU, AIRB, FERB, SALA, BONU, ALLW, COMM, COMP, PENS, DIVD, INTC, TREA, INVS, LOAN, LOAR, INTE, TAXS, GOVT, RENT, UBIL, INSU, ROYA, EDUC, CHAR, GIFT, FREX, OTHR 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.
Show child attributes
Show child attributes
Optional description.
Free-form tags (max 20 tags, each up to 100 characters).
Arbitrary metadata (max 50 keys, max 4 KB serialized).
Show child attributes
Show child attributes
Response
The request has succeeded.
A fiat payout transaction in LOCKED state, awaiting provider execution.
Object type. Always transaction.
transaction Unique transaction identifier.
Transaction type. Always FIAT_PAYOUT.
FIAT_PAYOUT Transaction status. LOCKED after initiation.
LOCKED Source account.
Target beneficiary.
Payout amount in major units.
Asset code.
Transfer method.
Snapshot of bank details at time of payout.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
{
"fixed": "50.00",
"bps": 0,
"bpsAmount": "0.00",
"total": "50.00",
"asset": "USD"
}
When the transaction was created.
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",
"purpose": "SUPP"
}
'import requests
url = "https://api.nxos.io/v1/transactions/fiat-payouts"
payload = {
"accountId": "acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"beneficiaryId": "bene_d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1",
"amount": "49985.00",
"asset": "USD",
"method": "WIRE",
"purpose": "SUPP"
}
headers = {
"Authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({
accountId: 'acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
beneficiaryId: 'bene_d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1',
amount: '49985.00',
asset: 'USD',
method: 'WIRE',
purpose: 'SUPP'
})
};
fetch('https://api.nxos.io/v1/transactions/fiat-payouts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nxos.io/v1/transactions/fiat-payouts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'accountId' => 'acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4',
'beneficiaryId' => 'bene_d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1',
'amount' => '49985.00',
'asset' => 'USD',
'method' => 'WIRE',
'purpose' => 'SUPP'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.nxos.io/v1/transactions/fiat-payouts"
payload := strings.NewReader("{\n \"accountId\": \"acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n \"beneficiaryId\": \"bene_d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1\",\n \"amount\": \"49985.00\",\n \"asset\": \"USD\",\n \"method\": \"WIRE\",\n \"purpose\": \"SUPP\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<authorization>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.nxos.io/v1/transactions/fiat-payouts")
.header("Authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"accountId\": \"acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n \"beneficiaryId\": \"bene_d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1\",\n \"amount\": \"49985.00\",\n \"asset\": \"USD\",\n \"method\": \"WIRE\",\n \"purpose\": \"SUPP\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nxos.io/v1/transactions/fiat-payouts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"accountId\": \"acct_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4\",\n \"beneficiaryId\": \"bene_d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1\",\n \"amount\": \"49985.00\",\n \"asset\": \"USD\",\n \"method\": \"WIRE\",\n \"purpose\": \"SUPP\"\n}"
response = http.request(request)
puts response.read_body{
"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"
}{
"error": {
"code": "invalid_request",
"message": "The request body is malformed or missing required fields.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "missing_api_key",
"message": "No Authorization header provided.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "forbidden",
"message": "Your organization is not enabled for this action.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "not_found",
"message": "The requested resource was not found.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "quote_expired",
"message": "The quote has expired.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded: 1000 requests per minute. Retry in 23 seconds.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected server error occurred.",
"requestId": "req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}
}