How payment routing works with Unirail
In Decide mode, the default for regulated platforms, your backend asks Unirail which provider should handle a payment and gets a decision with the cost, ETA and reasons. Your backend then calls that provider with your own credentials and reports the outcome to Unirail for future decisions. In this mode Unirail never sees names, account numbers or credentials. The money goes from bank to bank.
-
Your app
Each payment, bank link or identity check starts in your app and goes to your backend. You can bind the user's approval to the decision's id and digest.
Decide Nothing about your users leaves your platform from here.
Execute Your app's requests reach Unirail through your backend.
-
@unirail/sdk in your backend
The SDK gives you createUnirail({ apiKey }) for your secret key, maskAccount to fingerprint accounts with your own HMAC key and webhooks.verify for signed events.
Decide Sends masked metadata to POST /v1/route_decisions and gets the decision back.
Execute Sends the full request (link sessions, route quotes, payment intents) to Unirail's API.
-
The decision engine
The engine rules out providers that can't do the job and gives a reason for each. It prices the rest under your contracts and ranks them by cost, ETA and success likelihood.
Decide It runs at Unirail. By arrangement you can run it as @unirail/router in your own infrastructure to keep even masked metadata on your side.
Execute It runs at Unirail. Unirail then calls the provider itself.
Ask about self-hosting the engine -
@unirail/executor and your vault
@unirail/executor runs the same provider adapters Unirail uses inside your own process, with credentials from your Infisical vault.
Decide Your backend calls the provider and reports the status, latency and cost as a masked outcome.
Execute The executor isn't used. Unirail reads the credential from your vault over OIDC and keeps it in memory for up to five minutes.
How credentials stay in your vault -
The providers
Unirail can route to Plaid, Yapily and Enable Banking today. Another 23 are listed with sourced coverage for comparison only. Your platform keeps its own contract with each provider.
Decide Your backend calls them directly. The money goes from bank to bank.
Execute Unirail's API calls them for you. The money still goes from bank to bank.
Browse providers and coverage
Crosses into Unirail
- Masked metadata: operation, countries, currency, amount or band, bank ids, scheme names, account fingerprints
- Masked outcomes: status, latency, cost
Comes back
- The decision
Stays with you
- Provider credentials, names and account numbers
- The call to the provider
Crosses into Unirail
- The full request: link sessions, route quotes, payment intents
- Each credential, read from your vault over OIDC and cached in memory for up to five minutes
Comes back
- Results and webhook events signed per Standard Webhooks
Stays with you
- Your vault and your provider contracts. Unirail never writes credentials to disk or a database.
The whole stack
The four steps of a Decide mode request
The same four steps run for every payment, bank link and identity check in Decide mode.
-
Ask for a decision
POST /v1/route_decisionsYour backend sends masked metadata about the operation. The decision names the provider and rail, the cost under your contracts, the ETA, the success likelihood, ranked alternatives, the options ruled out with reasons, the policy version and a digest.
-
Call the provider
@unirail/executorYour backend calls the chosen provider with credentials from your vault, using Unirail's adapters inside your own process. The money goes straight from the payer's bank to the payee's bank.
-
Report the outcome
POST /v1/outcomesYour backend reports the decision id, the provider it used, the status and the latency. The call is idempotent on decision and status. A retry never records the same outcome twice.
-
Update the routing data
GET /v1/routing_snapshotUnirail turns outcomes into a success rate for each provider, operation and bank and into contract usage for the billing period. The next decision uses both. A self-hosted engine reads them from the snapshot.
How decisions rank providers The v1 API reference How contract usage prices each decision
Decide mode and Execute via Unirail
Both modes use the same control plane, capability catalogue and cost model. You can start with Decide and move single flows to Execute later.
| Question | Decide Default for regulated platforms | Execute via Unirail |
|---|---|---|
| What Unirail receives | The operation, countries, currency, amount or amount band, bank ids, payto scheme names and account fingerprints. Names, account numbers, emails and addresses stay with you. | The full request for link sessions, route quotes and payment intents. |
| Who calls the provider | Your backend, through @unirail/executor. It runs Unirail's adapters in your process with credentials from your own vault. | Unirail's API, reading the credential from your vault over OIDC federation and holding it in memory only. |
| Provider credentials | They never leave your platform. | Cached in Unirail's memory for up to five minutes and never written to disk or a database. |
| Outcomes | Your backend reports masked outcomes (status, latency, cost). They update success rates and contract usage. | Unirail records them directly. |
Decide mode in detail Security and credential handling Run the engine in your own network
Questions about how it works
Does Unirail hold or move funds?
No, and it isn't the regulated party either. Your platform keeps its own licences, its contracts with PISPs, aggregators and KYC/AML vendors and its own compliance duties for KYC, AML, sanctions and record keeping.
What does Unirail see about a payment?
In Decide mode it sees the operation, countries, currency, amount or amount band, bank ids, payto scheme names and the account fingerprints you compute with your own key. Names, account numbers, emails and addresses stay with you. In Execute via Unirail it receives the full request for link sessions, route quotes and payment intents, because it makes the provider call for you.
Where do my provider credentials live?
They live in your own vault. In Decide mode they never leave your platform, because @unirail/executor reads them inside your own process. For Execute via Unirail, you give an Infisical machine identity read-only access to one folder and have it trust Unirail's OIDC issuer. Unirail exchanges a short-lived token, reads the credential and keeps it in memory for up to five minutes. It never writes it to disk or a database. If you revoke the grant, new reads will stop. Values already in memory expire within five minutes.
Can I self-host the decision engine?
Yes, by arrangement with us. @unirail/router then runs in your infrastructure against GET /v1/routing_snapshot. Unirail acts only as the control plane. The snapshot holds no credentials and nothing about a person. It's versioned by content hash and tells your router to refresh after 60 seconds.
Can I use both modes?
Yes, you can run some flows in Decide mode and others through Execute via Unirail. A flow can move from one mode to the other later.
What happens if my backend stops reporting outcomes?
Decisions will keep working from the last success rates Unirail saw for each provider, operation and bank. Those rates and your contract usage stop updating until outcomes arrive again. Costs and rankings will then be based on old data.
Which providers can Unirail route to today?
Unirail routes to Plaid, Yapily and Enable Banking today. The catalogue lists 23 more with their coverage by country and a source for each claim, for comparison only.
Try Unirail in test mode
Request early access and we'll set up your test environment, or talk to us about your providers and volumes.