Correct beneficiary details

POST

transactions

{transactionId}

beneficiary-details

cURL

curl --request POST \
  --url https://api.nxos.io/v1/transactions/{transactionId}/beneficiary-details \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "iban": "GB82WEST12345698765432"
}
'

import requests

url = "https://api.nxos.io/v1/transactions/{transactionId}/beneficiary-details"

payload = { "iban": "GB82WEST12345698765432" }
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({iban: 'GB82WEST12345698765432'})
};

fetch('https://api.nxos.io/v1/transactions/{transactionId}/beneficiary-details', 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/{transactionId}/beneficiary-details",
  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([
    'iban' => 'GB82WEST12345698765432'
  ]),
  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/{transactionId}/beneficiary-details"

	payload := strings.NewReader("{\n  \"iban\": \"GB82WEST12345698765432\"\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/{transactionId}/beneficiary-details")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"iban\": \"GB82WEST12345698765432\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nxos.io/v1/transactions/{transactionId}/beneficiary-details")

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  \"iban\": \"GB82WEST12345698765432\"\n}"

response = http.request(request)
puts response.read_body

{
  "object": "transaction",
  "transactionId": "<string>",
  "accountId": "<string>",
  "status": "EXPECTED",
  "description": "<string>",
  "tags": [
    "<string>"
  ],
  "amount": "<string>",
  "asset": "<string>",
  "fee": {
    "fixed": "50.00",
    "bps": 0,
    "bpsAmount": "0.00",
    "total": "50.00",
    "asset": "USD"
  },
  "requiredActions": [
    {
      "type": "invoice",
      "holdId": "<string>"
    }
  ],
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "type": "CRYPTO_PAYIN",
  "details": {
    "chainName": "<string>",
    "chainTransactionId": "<string>",
    "fromAddress": "<string>",
    "toAddress": "<string>",
    "blockHeight": 123,
    "blockTimestamp": "<string>"
  }
}

Headers

Authorization

string

required

Bearer token. Format: Bearer <api_key>

Idempotency-Key

string

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

Path Parameters

transactionId

string

required

Transaction identifier.

Body

application/json

The corrected beneficiary details. Send the fields listed in the beneficiary_details required action; any other field is ignored. The beneficiary is updated for this payout and every later one.

iban

string

IBAN, spaces allowed. Checked against its checksum.

Maximum string length: 64

accountNumber

string

Account number, letters and digits, up to 34.

Maximum string length: 64

swiftCode

string

SWIFT / BIC, 8 or 11 characters.

Maximum string length: 32

bankName

string

The recipient's bank name.

Maximum string length: 140

firstName

string

For an individual beneficiary, with lastName, when beneficiaryName is asked.

Maximum string length: 140

lastName

string

For an individual beneficiary, with firstName, when beneficiaryName is asked.

Maximum string length: 140

businessName

string

For a business beneficiary, when beneficiaryName is asked.

Maximum string length: 140

addressLine1

string

The recipient's street address.

Maximum string length: 140

city

string

The recipient's city.

Maximum string length: 140

country

string

The recipient's country, ISO 3166-1 alpha-2.

Maximum string length: 2

Response

The request has succeeded.

A transaction, discriminated by type. Use the type field to narrow the details payload — each variant has a different shape. The envelope (status, amount, asset, fee, timestamps) is uniform across variants.

Variants:

CRYPTO_PAYIN → details is TransactionCryptoPayinDetails
CRYPTO_PAYOUT → details is TransactionCryptoPayoutDetails
FIAT_PAYIN → details is TransactionFiatPayinDetails
FIAT_PAYOUT → details is TransactionFiatPayoutDetails
TRADE → details is TransactionTradeDetails
TRANSFER → details is TransactionTransferDetails
NXOSNET_TRANSFER → details is TransactionNxosnetTransferDetails
CREDIT_ADJUSTMENT → details is TransactionCreditAdjustmentDetails
COMMISSION → details is TransactionCommissionDetails
DEBIT_ADJUSTMENT → details is TransactionDebitAdjustmentDetails

object

enum<string>

required

Object type. Always transaction.

Available options:

transaction

transactionId

string

required

Unique transaction identifier.

accountId

string

required

Account this transaction belongs to. Always one of your organization's accounts (the listing query enforces ownership).

status

enum<string>

required

Current status. See TransactionStatus for transitions.

Available options:

EXPECTED,

ACTION_REQUIRED,

LOCKED,

COMPLETED,

DECLINED,

REFUNDED

description

string | null

required

Optional human-readable description.

tags

string[]

required

Free-form tags set at create time (e.g. ["crypto_payout", "ethereum_mainnet"]).

amount

string | null

required

Primary amount in major units. For most types this is the amount the customer's account moved by. For TRADE this is null — trades have two distinct assets in play; see details.from and details.to instead.

asset

string | null

required

Asset code of the primary amount. Null for TRADE — see details.from / details.to.

fee

object

required

Service-fee breakdown. Always populated; every component is zero when no service fee applied. Note: trade spread fees are NOT here — they live in details.spread on TRADE transactions.

Show child attributes

Example:

{
  "fixed": "50.00",
  "bps": 0,
  "bpsAmount": "0.00",
  "total": "50.00",
  "asset": "USD"
}

requiredActions

(Document · object | Beneficiary details · object)[]

required

What you must still provide. While status is ACTION_REQUIRED: the documents to upload. On a LOCKED fiat payout waiting for corrected details: one beneficiary_details action with the fields to correct. Empty otherwise.

Something you must provide before the transaction can go on: a document for a held transaction, or the beneficiary details of a payout waiting to be sent.

Document
Beneficiary details

Show child attributes

createdAt

string

required

When the transaction was created (platform clock).

updatedAt

string

required

When the transaction was last updated.

type

enum<string>

required

Available options:

CRYPTO_PAYIN

details

object

required

Crypto deposit details — the on-chain receipt that funded the account.

Show child attributes

cURL

curl --request POST \
  --url https://api.nxos.io/v1/transactions/{transactionId}/beneficiary-details \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "iban": "GB82WEST12345698765432"
}
'

import requests

url = "https://api.nxos.io/v1/transactions/{transactionId}/beneficiary-details"

payload = { "iban": "GB82WEST12345698765432" }
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({iban: 'GB82WEST12345698765432'})
};

fetch('https://api.nxos.io/v1/transactions/{transactionId}/beneficiary-details', 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/{transactionId}/beneficiary-details",
  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([
    'iban' => 'GB82WEST12345698765432'
  ]),
  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/{transactionId}/beneficiary-details"

	payload := strings.NewReader("{\n  \"iban\": \"GB82WEST12345698765432\"\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/{transactionId}/beneficiary-details")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"iban\": \"GB82WEST12345698765432\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nxos.io/v1/transactions/{transactionId}/beneficiary-details")

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  \"iban\": \"GB82WEST12345698765432\"\n}"

response = http.request(request)
puts response.read_body

{
  "object": "transaction",
  "transactionId": "<string>",
  "accountId": "<string>",
  "status": "EXPECTED",
  "description": "<string>",
  "tags": [
    "<string>"
  ],
  "amount": "<string>",
  "asset": "<string>",
  "fee": {
    "fixed": "50.00",
    "bps": 0,
    "bpsAmount": "0.00",
    "total": "50.00",
    "asset": "USD"
  },
  "requiredActions": [
    {
      "type": "invoice",
      "holdId": "<string>"
    }
  ],
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "type": "CRYPTO_PAYIN",
  "details": {
    "chainName": "<string>",
    "chainTransactionId": "<string>",
    "fromAddress": "<string>",
    "toAddress": "<string>",
    "blockHeight": 123,
    "blockTimestamp": "<string>"
  }
}

Overview

Setup

Move money

Track

Broker

Referrals

Testing

Correct beneficiary details

Headers

Path Parameters

Body

Response