Get started

Quickstart

Silora connects you once to multiple global payment networks. This walkthrough goes from a sandbox key to a settled payment, in the order a real integration is built. Every call here works against https://api.sandbox.silorapay.ai/v1.

Before you start

A sandbox API key pair from the Client Portal, API keys screen. The key id goes in X-Silora-Key; the secret never leaves your server and is used only to sign.
One HTTPS endpoint that can receive webhooks. Settlement arrives there, not on the POST response.
The corridor you intend to serve — a {fromCountry}-{toCountry} pair such as US-IN.

The shape of an integration

1
Ask the corridor what it wants
GET /corridors/{pair}/requirements returns the conditional field schema for that corridor. Build your payload from the answer instead of from guesswork. See Corridor requirements.
2
Store the payee once
POST /beneficiaries removes the largest and most error-prone part of the payment body from every subsequent call.
3
Confirm the account before you pay it
POST /beneficiaries/{id}/validate is Confirmation of Payee. It is the single largest lever on your AC03 rejection rate.
4
Quote
POST /payments/quote resolves provider, FX and fees and creates nothing. Optional, and worth doing whenever a human will see a number before approving.
5
Create the payment
POST /payments returns 202 Accepted with a uetr. Acceptance is not execution.
6
Receive the outcome
A payment.settled or payment.failed webhook delivers the terminal state. See Webhooks.

Call 1 — what does this corridor demand?

curl -G 'https://api.sandbox.silorapay.ai/v1/corridors/US-IN/requirements' \
  --data-urlencode 'currency=USD' \
  --data-urlencode 'amount=24500' \
  --data-urlencode 'creditorType=ORGA' \
  -H "X-Silora-Key: $SILORA_KEY_ID" \
  -H "X-Silora-Timestamp: $TS" \
  -H "X-Silora-Signature: $SIG"

Requirements are threshold-dependent, so pass the amount you intend to send.

Call 2 — store the payee

POST /v1/beneficiaries
Idempotency-Key: 8f1b2c9e-4a10-4e5b-9d33-77a2e1c0b415

{
  "reference": "MERIDIAN-TEXTILES",
  "type": "ORGA",
  "name": "Meridian Textiles Pvt Ltd",
  "address": {
    "streetName": "Trade Centre", "buildingNumber": "402",
    "postCode": "400051", "townName": "Mumbai",
    "countrySubDivision": "Maharashtra", "country": "IN"
  },
  "identification": { "taxId": "AAACM1234F" },
  "account": { "scheme": "IN_ACCOUNT", "id": "50100234567890", "currency": "INR" },
  "agent": {
    "clearingSystem": "INIFSC", "clearingSystemMemberId": "HDFC0000123",
    "bic": "HDFCINBBXXX", "name": "HDFC Bank", "country": "IN"
  },
  "metadata": { "supplierCode": "SUP-4471", "costCentre": "CC-EMEA-07" }
}

Account numbers are masked on every read. corridors is derived from the account and agent, so you know immediately which pairs this payee can be used on.

Call 3 — Confirmation of Payee

curl -X POST 'https://api.sandbox.silorapay.ai/v1/beneficiaries/ben_01J8M4TQ7X2K9/validate' \
  -H "X-Silora-Key: $SILORA_KEY_ID" \
  -H "X-Silora-Timestamp: $TS" \
  -H "X-Silora-Signature: $SIG" \
  -H 'Content-Type: application/json' \
  -d '{ "amount": { "currency": "USD", "value": "24500.00" } }'

Call 4 — create the payment

With a stored beneficiary the body collapses to identity, amount and the corridor-specific fields. Everything the beneficiary already holds is resolved server-side.

import { randomUUID } from 'node:crypto';
import { sign } from './silora-signer';

const PATH = '/payments';
const payload = JSON.stringify({
  endToEndId: 'INV-2026-4471',
  provider: 'AUTO',
  instructedAmount: { currency: 'USD', value: '24500.00' },
  debtorAccount: { scheme: 'US_ACCOUNT', id: '8901234567' },
  beneficiaryId: 'ben_01J8M4TQ7X2K9',
  purpose: 'P0103',
  remittanceInformation: { unstructured: ['Invoice INV-2026-4471'] },
  requestedExecutionDate: '2026-08-22',
  metadata: { costCentre: 'CC-EMEA-07', poNumber: 'PO-88213' },
});

const { timestamp, signature } = sign({
  secret: process.env.SILORA_KEY_SECRET!,
  method: 'POST',
  path: PATH,
  body: payload,
});

const response = await fetch('https://api.sandbox.silorapay.ai/v1' + PATH, {
  method: 'POST',
  headers: {
    'X-Silora-Key': process.env.SILORA_KEY_ID!,
    'X-Silora-Timestamp': timestamp,
    'X-Silora-Signature': signature,
    'Idempotency-Key': randomUUID(),
    'Content-Type': 'application/vnd.silora.simple+json',
  },
  body: payload,
});

const accepted = await response.json();
console.log(response.status, accepted.uetr);   // 202 7a9c1e02-...

Call 5 — receive the outcome

Register an endpoint once, then let Silora push. Subscribe to the three terminal events at minimum: payment.settled, payment.failed, payment.returned.

POST /v1/webhooks/endpoints

{
  "url": "https://treasury.example.com/hooks/silora",
  "events": ["payment.settled", "payment.failed", "payment.returned"],
  "description": "Treasury settlement feed"
}

The endpoint registration response returns a secret once. Store it; it is the HMAC key for verifying every delivery.

What to build next

Authentication — signing, clock skew and key rotation.
Corridor requirements — how to stop guessing what a corridor needs.
Webhooks — verification, idempotency and the recovery path when your endpoint is down.
Errors — the ISO reason codes, and how a validation failure points at the rule it broke.