The Orenda API is one API. Some features are optional, and a few limits change from one
program to another. You don’t need to know anything about how a program is powered — you
just need to know what your program can do.
This page shows how to find that out. The rule is simple: ask the API, don’t assume.
If a feature isn’t listed here, it works the same for every program.
Optional features
Not every program has every feature. The safest way to check is to call the endpoint and
look at the result.
| Feature | How to tell if your program has it |
|---|
| International payments (and FX quotes) | Responds not available if your program isn’t eligible. Contact the team to enable it. |
| Batch payments | Enabled per program. If yours isn’t set up for it, the batch endpoint isn’t available to you. Contact the team to enable it. |
| Fee preview before sending | Call the fee endpoint. If it isn’t supported, you get 501 not_available. |
| Block / unblock an account | Not every program allows this. If yours doesn’t, the API returns a clear error instead of doing it. |
| PIN step-up | The pin confirmation method (request a PIN) is enabled per program. Programs without it reject method: "pin" with a 400 — use a passkey or 2FA code instead. |
Treat 501 not_available as “your program can’t do this.” It is not an outage or a
bug — it means the feature is turned off for your program. Handle it the same way you’d
handle a feature flag.
Limits and details that vary
A few values differ between programs. Read them from the data instead of hard-coding them.
| What | What you’ll see | How to handle it |
|---|
| Payment reference length | A maximum that is usually between 35 and 140 characters | Keep references within your program’s limit. If you’re not sure, stay short. |
| Currencies and rails | Varies by program | Call GET /v1/payments/currencies to get the real list. |
| Account details you receive | An IBAN, or a sort code and account number, or both | Read whichever fields are present on the account — don’t assume one format. |
| Payee details you send | An IBAN (sometimes with a BIC), or a sort code and account number | Send what the payee’s account uses. The API checks you’ve sent the right ones. |
| Beneficiary address | Required when you add a payee on some programs, optional on others | Send the payee’s address (line1, city, country) when your program requires it. If it’s required and you leave it out, the create is rejected. |
The payment reference length is the one most likely to trip you up. The field allows
up to 140 characters, but some programs accept fewer. If you go over your program’s limit,
the payment is rejected.
A good habit
Write your integration so it reacts to the data and the API’s responses, rather than
guessing in advance:
- Read the fields that are present, instead of expecting a fixed shape.
- Treat
501 not_available as “feature off for this program.”
- Use
GET /v1/payments/currencies for the live
currency list.
Do that, and the same code works for every program with no special cases.
Coming improvement. To make this fully self-serve, we plan to add a single
capabilities response you can read at the start — a simple list of what your program
supports and its limits — so you won’t need to discover features by trial. Until then, the
checks above are the way to find out.