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"
}
Adds a payee for cross-border payments. You’ll use it with an international transfer. Send the payee’s bank details as an account object (IBAN-only here — international is type: "iban"; a uk account is rejected), their currency, and a Luxembourg (LU) debtorViban — take the debtorViban from the funding account’s virtualIbans in List accounts. Like a normal beneficiary, this needs a step-up confirmation — include a confirmation object (passkey, 2FA code, or PIN on programs that support it).
International payments are an optional feature. If your program isn’t eligible, this responds with not available. To enable them, contact the team.

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