Decide mode

You hold the licences, the provider contracts and the compliance duties, and you may not want payments or personal data passing through anyone else. In Decide mode Unirail never sees either: your backend asks for a routing decision with metadata only, calls the chosen provider itself, and reports the outcome.

import { createUnirail, maskAccount } from "@unirail/sdk";

const unirail = createUnirail({ apiKey: process.env.UNIRAIL_SECRET_KEY! });

const decision = await unirail.routeDecisions.create({
  operation: "banking.pis.single",
  amount: { value: "5000", asset: "iso4217:GBP" },
  payer: { country: "GB", scheme: "scan", accountRef: await maskAccount(payer.payto, process.env.UNIRAIL_FINGERPRINT_KEY!) },
  payee: { country: "GB", scheme: "scan" },
});

if (decision.status === "routed") {
  // decision.rail, decision.estimatedCost, decision.eta, decision.alternatives…
}

What you sendCopy Anchor Link

Every field is metadata. The request is strict: an unknown field (a name, an account number, an email) is refused with invalid_request rather than ignored.

Account fingerprintsCopy Anchor Link

accountRef lets Unirail recognise "this account again" without knowing the account. Compute it in your backend with a key only you hold:

const accountRef = await maskAccount("payto://scan/040004/12345678", process.env.UNIRAIL_FINGERPRINT_KEY!);
// "fp_…": HMAC-SHA256 of the canonical payto URI, base64url

Use 32 or more random characters from your own secrets manager and never send the key anywhere. The same account typed differently (spacing, case, a receiver name or BIC in the URI) gives the same ref; without the key nobody can work back to the account, and refs from two platforms can't be matched.

What comes backCopy Anchor Link

Calling the provider yourselfCopy Anchor Link

@unirail/executor runs Unirail's provider adapters inside your backend, with credentials from your own environment or vault, and does the masking and reporting for you:

import { createExecutor } from "@unirail/executor";

const executor = createExecutor({
  unirail,
  credentials: { plaid: () => ({ CLIENT_ID: env.PLAID_CLIENT_ID, SECRET: env.PLAID_SECRET }) },
  connections: { plaid: { providerEnvironment: "production", config: { clientName: "Acme" }, webhookUrl: "https://api.acme.com/hooks/plaid" } },
  fingerprintKey: env.UNIRAIL_FINGERPRINT_KEY,
});

const started = await executor.pay({
  paymentId: payment.id, // your id: the provider idempotency key derives from it
  amount: { value: "5000", asset: "iso4217:GBP" },
  payer: { country: "GB", payto: payerPayto, name: payerName },
  payee: { country: "GB", payto: payeePayto, name: payeeName },
  returnUri: "https://app.acme.com/paid",
});
// started.nextAction: usually a redirect to the payer's bank. When they come back:
const done = await executor.refresh(started.payment, { returnParams, input });

Names and payto URIs stay in your process; Unirail receives the scheme and the fingerprint. executor.link and executor.verify work the same way for linking accounts and identity checks.

Reporting outcomesCopy Anchor Link

If you call providers without the executor, report each final status so reliability and deal usage stay current:

await unirail.outcomes.create(
  { decision: decision.id, rail: decision.rail, status: "succeeded", latencyMs: 4200 },
  { context: { idempotencyKey: `outcome:${decision.id}:succeeded` } },
);

status is succeeded, failed or cancelled; add providerFee if you know what the provider charged and failureCode (a short code such as rejected, never the provider's message) on failures. Reporting the same status for the same decision twice returns the first record.

Running the decision engine yourselfCopy Anchor Link

The engine is a package, @unirail/router. If you'd rather not send even the metadata, run it in your own infrastructure against your environment's routing snapshot:

import { createRouter } from "@unirail/router";

let snapshot = await unirail.routingSnapshot.get({});
let router = createRouter(snapshot);
const decision = await router.decide({ operation: "banking.pis.single", amount, payer, payee });

The snapshot holds your routing policy, your connections' declared capabilities, your active deals with this month's usage, and reliability from your outcomes. It contains no credentials and nothing about your users. Refetch it after refreshAfter (a minute); version changes only when its content does. Unirail never sees these decisions, so outcomes for them include context: { operation, country }.