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",
"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",
"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',
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',
'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 \"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 \"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 \"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"
},
"iban": "FR7630006000011234567890189",
"type": "INTERNATIONAL_BENEFICIARY",
"accountType": "CONSUMER",
"currency": "USD"
}
}Create an international beneficiary
Saves a payee for cross-border (FX) payments. IBAN only; a uk account is rejected. Also send the payee’s currency and a Luxembourg (LU) debtorViban, taken from the funding account’s virtualIbans in List accounts. Needs the same confirmation and Idempotency-Key as a normal beneficiary.
International payments are optional: when program.payments.international in capabilities is false, this returns 403. The response carries the id as both id and beneficiaryId; use beneficiaryId on the transfer.
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",
"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",
"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',
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',
'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 \"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 \"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 \"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"
},
"iban": "FR7630006000011234567890189",
"type": "INTERNATIONAL_BENEFICIARY",
"accountType": "CONSUMER",
"currency": "USD"
}
}Authorizations
The user's access_token from authentication. The program and environment come from the token.
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
The customer's id. It's the customerId from the signed-in user's application (the onboarding response, also returned on the customer's accounts).
The id of the account the beneficiary is linked to. A customer can hold several accounts (for example one per currency); a beneficiary belongs to one of them. Take the accountId of the account the payment will be sent from, from the customer's account list.
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, debtorViban, and a confirmation object.
Required. The payee's name.
The payee's IBAN details. International beneficiaries are IBAN-only: a uk account is rejected.
Show child attributes
Show child attributes
Required. The payee's currency (ISO 4217), e.g. USD.
3Required. The source virtual IBAN to pay from (must start with LU). Take it from the funding account's details (the account in the path).
^LURequired 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.
- Passkey
- 2FA code
- PIN
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Optional. Idempotency key for retry-safety. The Idempotency-Key header is preferred and overrides this field. Reusing a key with different core parameters returns 400.
Optional. true if the payee is a business, false (default) for an individual. The accountType you see on the beneficiary is derived from this.