Create a Treasury beneficiary

curl --request POST \
  --url https://api.sandbox.wayex.com/v1/treasury/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "destination": {
    "type": "bank_account",
    "bsb": "<string>",
    "accountNumber": "<string>",
    "accountName": "<string>"
  },
  "type": "individual",
  "firstName": "<string>",
  "lastName": "<string>",
  "dateOfBirth": "<string>",
  "address": "<string>",
  "partyContext": {},
  "externalReference": "<string>"
}
'

import requests

url = "https://api.sandbox.wayex.com/v1/treasury/beneficiaries"

payload = {
    "destination": {
        "type": "bank_account",
        "bsb": "<string>",
        "accountNumber": "<string>",
        "accountName": "<string>"
    },
    "type": "individual",
    "firstName": "<string>",
    "lastName": "<string>",
    "dateOfBirth": "<string>",
    "address": "<string>",
    "partyContext": {},
    "externalReference": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    destination: {
      type: 'bank_account',
      bsb: '<string>',
      accountNumber: '<string>',
      accountName: '<string>'
    },
    type: 'individual',
    firstName: '<string>',
    lastName: '<string>',
    dateOfBirth: '<string>',
    address: '<string>',
    partyContext: {},
    externalReference: '<string>'
  })
};

fetch('https://api.sandbox.wayex.com/v1/treasury/beneficiaries', 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.sandbox.wayex.com/v1/treasury/beneficiaries",
  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([
    'destination' => [
        'type' => 'bank_account',
        'bsb' => '<string>',
        'accountNumber' => '<string>',
        'accountName' => '<string>'
    ],
    'type' => 'individual',
    'firstName' => '<string>',
    'lastName' => '<string>',
    'dateOfBirth' => '<string>',
    'address' => '<string>',
    'partyContext' => [
        
    ],
    'externalReference' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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.sandbox.wayex.com/v1/treasury/beneficiaries"

	payload := strings.NewReader("{\n  \"destination\": {\n    \"type\": \"bank_account\",\n    \"bsb\": \"<string>\",\n    \"accountNumber\": \"<string>\",\n    \"accountName\": \"<string>\"\n  },\n  \"type\": \"individual\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"dateOfBirth\": \"<string>\",\n  \"address\": \"<string>\",\n  \"partyContext\": {},\n  \"externalReference\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	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.sandbox.wayex.com/v1/treasury/beneficiaries")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"destination\": {\n    \"type\": \"bank_account\",\n    \"bsb\": \"<string>\",\n    \"accountNumber\": \"<string>\",\n    \"accountName\": \"<string>\"\n  },\n  \"type\": \"individual\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"dateOfBirth\": \"<string>\",\n  \"address\": \"<string>\",\n  \"partyContext\": {},\n  \"externalReference\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.wayex.com/v1/treasury/beneficiaries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"destination\": {\n    \"type\": \"bank_account\",\n    \"bsb\": \"<string>\",\n    \"accountNumber\": \"<string>\",\n    \"accountName\": \"<string>\"\n  },\n  \"type\": \"individual\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"dateOfBirth\": \"<string>\",\n  \"address\": \"<string>\",\n  \"partyContext\": {},\n  \"externalReference\": \"<string>\"\n}"

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

{
  "id": "<string>",
  "clientId": "<string>",
  "externalReference": "<string>",
  "destination": {
    "type": "bank_account",
    "bsb": "<string>",
    "accountNumber": "<string>",
    "accountName": "<string>"
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "type": "individual",
  "firstName": "<string>",
  "lastName": "<string>",
  "dateOfBirth": "<string>",
  "address": "<string>",
  "partyContext": {},
  "deactivatedAt": "2023-11-07T05:31:56Z"
}

POST

treasury

beneficiaries

Create a Treasury beneficiary

curl --request POST \
  --url https://api.sandbox.wayex.com/v1/treasury/beneficiaries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "destination": {
    "type": "bank_account",
    "bsb": "<string>",
    "accountNumber": "<string>",
    "accountName": "<string>"
  },
  "type": "individual",
  "firstName": "<string>",
  "lastName": "<string>",
  "dateOfBirth": "<string>",
  "address": "<string>",
  "partyContext": {},
  "externalReference": "<string>"
}
'

import requests

url = "https://api.sandbox.wayex.com/v1/treasury/beneficiaries"

payload = {
    "destination": {
        "type": "bank_account",
        "bsb": "<string>",
        "accountNumber": "<string>",
        "accountName": "<string>"
    },
    "type": "individual",
    "firstName": "<string>",
    "lastName": "<string>",
    "dateOfBirth": "<string>",
    "address": "<string>",
    "partyContext": {},
    "externalReference": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    destination: {
      type: 'bank_account',
      bsb: '<string>',
      accountNumber: '<string>',
      accountName: '<string>'
    },
    type: 'individual',
    firstName: '<string>',
    lastName: '<string>',
    dateOfBirth: '<string>',
    address: '<string>',
    partyContext: {},
    externalReference: '<string>'
  })
};

fetch('https://api.sandbox.wayex.com/v1/treasury/beneficiaries', 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.sandbox.wayex.com/v1/treasury/beneficiaries",
  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([
    'destination' => [
        'type' => 'bank_account',
        'bsb' => '<string>',
        'accountNumber' => '<string>',
        'accountName' => '<string>'
    ],
    'type' => 'individual',
    'firstName' => '<string>',
    'lastName' => '<string>',
    'dateOfBirth' => '<string>',
    'address' => '<string>',
    'partyContext' => [
        
    ],
    'externalReference' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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.sandbox.wayex.com/v1/treasury/beneficiaries"

	payload := strings.NewReader("{\n  \"destination\": {\n    \"type\": \"bank_account\",\n    \"bsb\": \"<string>\",\n    \"accountNumber\": \"<string>\",\n    \"accountName\": \"<string>\"\n  },\n  \"type\": \"individual\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"dateOfBirth\": \"<string>\",\n  \"address\": \"<string>\",\n  \"partyContext\": {},\n  \"externalReference\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	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.sandbox.wayex.com/v1/treasury/beneficiaries")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"destination\": {\n    \"type\": \"bank_account\",\n    \"bsb\": \"<string>\",\n    \"accountNumber\": \"<string>\",\n    \"accountName\": \"<string>\"\n  },\n  \"type\": \"individual\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"dateOfBirth\": \"<string>\",\n  \"address\": \"<string>\",\n  \"partyContext\": {},\n  \"externalReference\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.wayex.com/v1/treasury/beneficiaries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"destination\": {\n    \"type\": \"bank_account\",\n    \"bsb\": \"<string>\",\n    \"accountNumber\": \"<string>\",\n    \"accountName\": \"<string>\"\n  },\n  \"type\": \"individual\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"dateOfBirth\": \"<string>\",\n  \"address\": \"<string>\",\n  \"partyContext\": {},\n  \"externalReference\": \"<string>\"\n}"

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

{
  "id": "<string>",
  "clientId": "<string>",
  "externalReference": "<string>",
  "destination": {
    "type": "bank_account",
    "bsb": "<string>",
    "accountNumber": "<string>",
    "accountName": "<string>"
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "type": "individual",
  "firstName": "<string>",
  "lastName": "<string>",
  "dateOfBirth": "<string>",
  "address": "<string>",
  "partyContext": {},
  "deactivatedAt": "2023-11-07T05:31:56Z"
}

What this endpoint does

Creates a reusable individual or business recipient with BSB/account payout details and can validate optional Sumsub evidence in the same request.

When to use it

Create the beneficiary before the first payout. Supply externalReference only when your system already has a stable recipient identifier; otherwise Wayex generates one.

Before you call

Use a secret API key with treasury:write. Supply the required recipient and destination data. If a fresh end-client Sumsub share token is available or required by policy, send it in the input-only, single-use sumsub.shareToken field on this request.

Money and balance effect

This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money.

States and completion

Creation does not guarantee a payout will pass current policy. Evidence, screening, limits, and balance are checked when the payout is submitted.

Safe retries

Send a unique Idempotency-Key for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read Beneficiaries and payouts for the complete workflow.

Authorizations

Authorization

string

header

required

Send the same Wayex API key as Authorization: Bearer <key>.

Headers

Idempotency-Key

string

required

A unique key for this logical action. Reuse the same key and identical payload when retrying after an unknown response.

Required string length: 8 - 255

Body

application/json

Option 1
Option 2

destination

object

required

Show child attributes

type

enum<string>

required

Available options:

individual

firstName

string

required

Minimum string length: 1

lastName

string

required

Minimum string length: 1

dateOfBirth

string

required

address

string

required

Minimum string length: 1

partyContext

object

Show child attributes

externalReference

string

Required string length: 1 - 512

sumsub

object

Show child attributes

Response

201 - application/json

Option 1
Option 2

string

required

Minimum string length: 1

clientId

string

required

Minimum string length: 1

externalReference

string

required

Minimum string length: 1

destination

object

required

Show child attributes

status

enum<string>

required

Available options:

active,

inactive

createdAt

string<date-time>

required

updatedAt

string<date-time>

required

type

enum<string>

required

Available options:

individual

firstName

string

required

Minimum string length: 1

lastName

string

required

Minimum string length: 1

dateOfBirth

string

required

address

string

required

Minimum string length: 1

partyContext

object

Show child attributes

deactivatedAt

string<date-time>

Create a funding instrument Preview a payout

​What this endpoint does

​When to use it

​Before you call

​Money and balance effect

​States and completion

​Safe retries

Authorizations

Headers

Body

Response

What this endpoint does

When to use it

Before you call

Money and balance effect

States and completion

Safe retries