curl --request POST \
--url https://api.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/beneficiaries/international \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Grace Hopper",
"account": {
"type": "iban",
"iban": "FR7630006000011234567890189",
"bic": "AGRIFRPP"
},
"currency": "USD",
"debtorViban": "LU280019400644750000",
"isCorporate": false,
"confirmation": {
"method": "totp",
"totp": "123456",
"accessToken": "eyJraWQiOi..."
}
}
'import requests
url = "https://api.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/beneficiaries/international"
payload = {
"name": "Grace Hopper",
"account": {
"type": "iban",
"iban": "FR7630006000011234567890189",
"bic": "AGRIFRPP"
},
"currency": "USD",
"debtorViban": "LU280019400644750000",
"isCorporate": False,
"confirmation": {
"method": "totp",
"totp": "123456",
"accessToken": "eyJraWQiOi..."
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Grace Hopper',
account: {type: 'iban', iban: 'FR7630006000011234567890189', bic: 'AGRIFRPP'},
currency: 'USD',
debtorViban: 'LU280019400644750000',
isCorporate: false,
confirmation: {method: 'totp', totp: '123456', accessToken: 'eyJraWQiOi...'}
})
};
fetch('https://api.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/beneficiaries/international', 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.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/beneficiaries/international",
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([
'name' => 'Grace Hopper',
'account' => [
'type' => 'iban',
'iban' => 'FR7630006000011234567890189',
'bic' => 'AGRIFRPP'
],
'currency' => 'USD',
'debtorViban' => 'LU280019400644750000',
'isCorporate' => false,
'confirmation' => [
'method' => 'totp',
'totp' => '123456',
'accessToken' => 'eyJraWQiOi...'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/beneficiaries/international"
payload := strings.NewReader("{\n \"name\": \"Grace Hopper\",\n \"account\": {\n \"type\": \"iban\",\n \"iban\": \"FR7630006000011234567890189\",\n \"bic\": \"AGRIFRPP\"\n },\n \"currency\": \"USD\",\n \"debtorViban\": \"LU280019400644750000\",\n \"isCorporate\": false,\n \"confirmation\": {\n \"method\": \"totp\",\n \"totp\": \"123456\",\n \"accessToken\": \"eyJraWQiOi...\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
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.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/beneficiaries/international")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Grace Hopper\",\n \"account\": {\n \"type\": \"iban\",\n \"iban\": \"FR7630006000011234567890189\",\n \"bic\": \"AGRIFRPP\"\n },\n \"currency\": \"USD\",\n \"debtorViban\": \"LU280019400644750000\",\n \"isCorporate\": false,\n \"confirmation\": {\n \"method\": \"totp\",\n \"totp\": \"123456\",\n \"accessToken\": \"eyJraWQiOi...\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/beneficiaries/international")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Grace Hopper\",\n \"account\": {\n \"type\": \"iban\",\n \"iban\": \"FR7630006000011234567890189\",\n \"bic\": \"AGRIFRPP\"\n },\n \"currency\": \"USD\",\n \"debtorViban\": \"LU280019400644750000\",\n \"isCorporate\": false,\n \"confirmation\": {\n \"method\": \"totp\",\n \"totp\": \"123456\",\n \"accessToken\": \"eyJraWQiOi...\"\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "International beneficiary created successfully",
"data": {
"id": "ben_4b8e1c9d",
"beneficiaryId": "ben_4b8e1c9d",
"customerId": "cust_3f9a2b7e",
"accountId": "acc_7c1d8e4a",
"name": "Grace Hopper",
"account": {
"type": "iban",
"iban": "FR7630006000011234567890189",
"bic": "AGRIFRPP"
},
"iban": "FR7630006000011234567890189",
"bic": "AGRIFRPP",
"type": "INTERNATIONAL_BENEFICIARY",
"accountType": "CONSUMER",
"isCorporate": false,
"currency": "USD"
}
}International beneficiary
Add a payee for cross-border (FX) payments.
curl --request POST \
--url https://api.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/beneficiaries/international \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Grace Hopper",
"account": {
"type": "iban",
"iban": "FR7630006000011234567890189",
"bic": "AGRIFRPP"
},
"currency": "USD",
"debtorViban": "LU280019400644750000",
"isCorporate": false,
"confirmation": {
"method": "totp",
"totp": "123456",
"accessToken": "eyJraWQiOi..."
}
}
'import requests
url = "https://api.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/beneficiaries/international"
payload = {
"name": "Grace Hopper",
"account": {
"type": "iban",
"iban": "FR7630006000011234567890189",
"bic": "AGRIFRPP"
},
"currency": "USD",
"debtorViban": "LU280019400644750000",
"isCorporate": False,
"confirmation": {
"method": "totp",
"totp": "123456",
"accessToken": "eyJraWQiOi..."
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Grace Hopper',
account: {type: 'iban', iban: 'FR7630006000011234567890189', bic: 'AGRIFRPP'},
currency: 'USD',
debtorViban: 'LU280019400644750000',
isCorporate: false,
confirmation: {method: 'totp', totp: '123456', accessToken: 'eyJraWQiOi...'}
})
};
fetch('https://api.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/beneficiaries/international', 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.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/beneficiaries/international",
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([
'name' => 'Grace Hopper',
'account' => [
'type' => 'iban',
'iban' => 'FR7630006000011234567890189',
'bic' => 'AGRIFRPP'
],
'currency' => 'USD',
'debtorViban' => 'LU280019400644750000',
'isCorporate' => false,
'confirmation' => [
'method' => 'totp',
'totp' => '123456',
'accessToken' => 'eyJraWQiOi...'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/beneficiaries/international"
payload := strings.NewReader("{\n \"name\": \"Grace Hopper\",\n \"account\": {\n \"type\": \"iban\",\n \"iban\": \"FR7630006000011234567890189\",\n \"bic\": \"AGRIFRPP\"\n },\n \"currency\": \"USD\",\n \"debtorViban\": \"LU280019400644750000\",\n \"isCorporate\": false,\n \"confirmation\": {\n \"method\": \"totp\",\n \"totp\": \"123456\",\n \"accessToken\": \"eyJraWQiOi...\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
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.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/beneficiaries/international")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Grace Hopper\",\n \"account\": {\n \"type\": \"iban\",\n \"iban\": \"FR7630006000011234567890189\",\n \"bic\": \"AGRIFRPP\"\n },\n \"currency\": \"USD\",\n \"debtorViban\": \"LU280019400644750000\",\n \"isCorporate\": false,\n \"confirmation\": {\n \"method\": \"totp\",\n \"totp\": \"123456\",\n \"accessToken\": \"eyJraWQiOi...\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/beneficiaries/international")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Grace Hopper\",\n \"account\": {\n \"type\": \"iban\",\n \"iban\": \"FR7630006000011234567890189\",\n \"bic\": \"AGRIFRPP\"\n },\n \"currency\": \"USD\",\n \"debtorViban\": \"LU280019400644750000\",\n \"isCorporate\": false,\n \"confirmation\": {\n \"method\": \"totp\",\n \"totp\": \"123456\",\n \"accessToken\": \"eyJraWQiOi...\"\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "International beneficiary created successfully",
"data": {
"id": "ben_4b8e1c9d",
"beneficiaryId": "ben_4b8e1c9d",
"customerId": "cust_3f9a2b7e",
"accountId": "acc_7c1d8e4a",
"name": "Grace Hopper",
"account": {
"type": "iban",
"iban": "FR7630006000011234567890189",
"bic": "AGRIFRPP"
},
"iban": "FR7630006000011234567890189",
"bic": "AGRIFRPP",
"type": "INTERNATIONAL_BENEFICIARY",
"accountType": "CONSUMER",
"isCorporate": false,
"currency": "USD"
}
}payments.international: true, and most programs don’t have them. Check before you
build this flow: on a program without them you can still save an international payee, but
every transfer to it is refused with 501 (not_available). To enable them,
contact the team.name.account: IBAN only (type: "iban"; aukaccount is rejected). The IBAN can be from any country but must pass its length and checksum check.bicandbankNameare optional and stored when sent.currency: the payee’s currency, a 3-letter ISO 4217 code. It isn’t checked against a list when you save the payee.debtorViban: a Luxembourg (LU) virtual IBAN. Take it from the funding account’svirtualIbansin List accounts. Only theLUprefix is checked here.address: optional, validated and stored when sent.- A
confirmationobject, as for a normal beneficiary (passkey, 2FA code, or PIN). Who may leave it out is on Step-up confirmation.
The response
The saved beneficiary is underdata. It carries the id both as id and as
beneficiaryId (same value; beneficiaryId is kept for older clients). Pass that value as
beneficiaryId when you make the transfer. An
international beneficiary has no status.
Errors to expect
| Status | Code | When |
|---|---|---|
400 | VALIDATION_ERROR | A field is missing or invalid, the IBAN fails its check, debtorViban doesn’t start with LU, the confirmation is incomplete, or the key was reused with different details. |
409 | ACCOUNT_NOT_ACTIVE | The account in the path is blocked, closed or pending. |
422 | SCA_* | The confirmation was refused. See Step-up confirmation. |
422 | ACCOUNT_NOT_FOUND | No such account for this customer. Unlike the local route, an unknown account is a 422, not a 404, and is checked after the confirmation. |
Retry safely
Send anIdempotency-Key header (a UUID) and reuse the same key if you
retry, so a lost response can’t add the same payee twice.
A retry with the same key returns the original payee when name, IBAN, BIC and currency
match; a different value in any of them is a 400. debtorViban, address,
isCorporate and the account in the path aren’t compared.
Authorizations
Headers
Optional. Makes the request retry-safe: a retry with the same key resolves to the same resource instead of creating a duplicate. Must be a UUID, and is scoped to the authenticated customer. Preferred over any idempotencyKey body field (a header value wins if both are sent). Optional today, but will be required in a future release — send one on every create now so a retry can never produce a duplicate.
Path Parameters
Body
The account this payee is linked to is the accountId in the path. Required in the body: name, an account object (must be type: "iban": international is IBAN-only), currency and debtorViban. A confirmation object is required too, except for the waivers on Step-up confirmation.
Required for an ordinary customer. Omit it only when the caller is waived: an SSO session on a program not ramped onto passkey-only step-up, or the sandbox demo account. A back-office operator is NOT waived and sends their own TOTP or passkey. A missing confirmation is a 422 SCA_MISSING. The full rule is on Step-up confirmation.
- Passkey
- 2FA code
- PIN
Show child attributes
Show child attributes