POST
/
v1
/
customers
/
{customerId}
/
accounts
/
{accountId}
/
beneficiaries
/
international
Create an international beneficiary
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,
  "data": {
    "id": "ben_4b8e1c9d",
    "customerId": "cust_3f9a2b7e",
    "accountId": "acc_7c1d8e4a",
    "name": "Grace Hopper",
    "status": "ACTIVE"
  }
}
{
"success": false,
"code": "<string>",
"message": "<string>"
}
{
"success": false,
"code": "IDEMPOTENT_REQUEST_IN_PROGRESS",
"message": "A request with this Idempotency-Key is already in progress"
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string<uuid>

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.

Path Parameters

customerId
string
required

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).

accountId
string
required

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

application/json

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.

name
string
required

Required. The payee's name.

account
IBAN · object
required

The payee's IBAN details. International beneficiaries are IBAN-only — a uk account is rejected.

confirmation
Passkey · object
required

Step-up confirmation. Set method to passkey, totp, or pin and include that method's fields. pin is a program capability — see Program capabilities.

currency
string
required

Required. The payee's currency (ISO 4217), e.g. USD.

Required string length: 3
debtorViban
string
required

Required. The source virtual IBAN to pay from (must start with LU). Take it from the funding account's details (the account in the path).

Pattern: ^LU
address
object
idempotencyKey
string<uuid>

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; a key whose beneficiary is still being claimed returns 409.

Response

Created

success
boolean
Example:

true

data
object