curl --request POST \
--url https://api.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/payments/international \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": "150.00",
"currency": "EUR",
"reference": "Invoice 1025",
"quoteId": "2a7c4e6f-8b1d-4c3e-9f0a-1b2c3d4e5f6a",
"beneficiaryId": "8c2f1b3e-4d5a-4f6b-9c7d-0e1f2a3b4c5d",
"debtorViban": "LU280019400644750000",
"purpose": "PP001",
"chargeBearer": "SHA"
}
'{
"success": true,
"data": {
"success": true,
"providerRequestId": "7a1d3c2e-5b4f-4e6a-9c8d-1f2a3b4c5d6e",
"status": "PendingProcessing"
}
}Create an international (FX) transfer
Sends money abroad using an FX quote. Get one from GET /v1/accounts/{accountId}/fx/quote and pass its quoteId here. debtorViban must be a Luxembourg (LU) virtual IBAN, taken from the funding account’s virtualIbans in List accounts.
International payments are optional per program: program.payments.international in GET /v1/capabilities says whether yours has them. Otherwise this returns 501 not_available.
Retries. Send an Idempotency-Key header and reuse it on every retry of the same transfer, including across the step-up below; the confirmation attempt is a retry of the same operation, not a new one. A retry must send the same parameters, quoteId included. A fresh quote is a new transfer and needs a new key; reusing the old key with a new quote is a 400.
Step-up for an inline payee. A payment to payee details sent inline (rather than a saved beneficiaryId) needs Strong Customer Authentication. The first call answers 428 SCA_REQUIRED with success: false and a challenge in data. Send the same body again with sca set to that challenge and a confirmation: { "method": "passkey", "passkeySession", "assertion" }, { "method": "totp", "totp", "accessToken" } (the access_token from sign-in), or { "method": "pin", "pin" } on programs with PIN step-up. program.beneficiaries.stepUpMethods in GET /v1/capabilities lists the methods your session may use. A saved beneficiaryId skips the step.
What a 200 carries. data is the provider’s acceptance: success, providerRequestId, and the provider’s status. When the payment is held for compliance review, data is { success, id, status: "PENDING_TM", message } instead, where id is the payment id. Follow either on List payment requests. A retry with the same Idempotency-Key returns the stored result, which also carries id and paymentId.
curl --request POST \
--url https://api.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/payments/international \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": "150.00",
"currency": "EUR",
"reference": "Invoice 1025",
"quoteId": "2a7c4e6f-8b1d-4c3e-9f0a-1b2c3d4e5f6a",
"beneficiaryId": "8c2f1b3e-4d5a-4f6b-9c7d-0e1f2a3b4c5d",
"debtorViban": "LU280019400644750000",
"purpose": "PP001",
"chargeBearer": "SHA"
}
'{
"success": true,
"data": {
"success": true,
"providerRequestId": "7a1d3c2e-5b4f-4e6a-9c8d-1f2a3b4c5d6e",
"status": "PendingProcessing"
}
}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
Customer identifier.
Account identifier. The account determines which optional features and limits apply.
Body
^\d+(\.\d{1,2})?$"100.00"
From GET /v1/accounts/{accountId}/fx/quote.
1"PP001"
Destination currency (ISO 4217).
3140Saved beneficiary. Provide this OR beneficiary.
Show child attributes
Show child attributes
Optional. When sent it must be an LU virtual IBAN: anything else is rejected with a 400.
^LUSHA, OUR, BEN Step-up confirmation (SCA step-2 only). Set method to passkey, totp, or pin and include that method's fields. pin is a program capability: see Program capabilities.
- Passkey
- 2FA code
- PIN
Show child attributes
Show child attributes
The challenge object from the 428 (hash, nonce, timestamp), echoed back verbatim. May instead be sent as confirmation.scaChallenge.
Optional. Idempotency key for retry-safety (parity with batch payments). The Idempotency-Key header is preferred and overrides this field. Reusing a key with different amount/accountId/beneficiaryId returns 400; a key whose payment is still being claimed returns 409.