viaBanking
Schedule a demo

Reference · v1

API Reference

REST API for AIS and PIS. One data model, any C2B account, one Bearer token.

Get sandbox access Schedule a demo

01 · Resources

Endpoints

Each resource works the same for every C2B account in the layer. Learn it once; it applies across every bank.

  • POST AUTH
    /v1/consents

    Consents

    Create a user consent. Send the customer to their bank once and reuse the token for AIS and PIS.

    Response fields

    id
    string · consent identifier
    status
    enum · pending | authorised | rejected | expired
    scopes
    string[] · ais, pis
    auth_url
    string · URL to redirect the user to
    expires_at
    string · ISO 8601 timestamp

    Errors

    • 400 invalid_request
    • 401 unauthenticated
    • 409 consent_conflict
    • 422 unsupported_bank
  • GET META
    /v1/banks

    Banks

    List the banks and EMIs available in the layer. Check live status before routing a call, and filter by country or capability.

    Response fields

    id
    string · bank identifier (use in /consents)
    name
    string · display name
    country
    string · ISO 3166-1 alpha-2
    capabilities
    string[] · ais, pis
    status
    enum · live | degraded | down

    Errors

    • 400 invalid_query
    • 401 unauthenticated
  • GET AIS
    /v1/accounts

    Accounts

    List linked accounts and pull balances and details in one call. One shape across every C2B account.

    Response fields

    id
    string · account identifier
    iban
    string · IBAN when available
    currency
    string · ISO 4217
    balance
    object · { amount, currency, as_of }
    holder
    object · { name, type }

    Errors

    • 401 unauthenticated
    • 403 consent_missing
    • 404 not_found
    • 410 consent_expired
  • GET AIS
    /v1/accounts/{id}/transactions

    Transactions

    Read a dated transaction feed with the same fields for every account. Cursor-paginated, up to 100 items per page.

    Response fields

    id
    string · transaction identifier
    booking_date
    string · ISO 8601 date
    amount
    object · { amount, currency }
    counterparty
    object · { name, iban }
    reference
    string · payer/remittance reference

    Errors

    • 401 unauthenticated
    • 403 consent_missing
    • 404 not_found
    • 429 rate_limited
  • POST PIS
    /v1/payments

    Payments

    Initiate an account-to-account payment. viaBanking orchestrates consent and login; you track one status field and one asynchronous webhook.

    Response fields

    id
    string · payment identifier
    status
    enum · initiated | pending | settled | failed | cancelled
    amount
    object · { amount, currency }
    debtor
    object · { iban, name }
    creditor
    object · { iban, name }
    auth_url
    string · URL to redirect payer for confirmation

    Errors

    • 400 invalid_request
    • 401 unauthenticated
    • 403 consent_missing
    • 409 duplicate_idempotency_key
    • 422 unsupported_scheme
  • GET META
    /v1/status

    Status

    Read platform and per-bank health in real time. Use it to drive smart retries and skip degraded routes.

    Response fields

    platform
    enum · operational | degraded | maintenance
    banks[].id
    string · bank identifier
    banks[].status
    enum · live | degraded | down
    banks[].updated_at
    string · ISO 8601 timestamp

    Errors

    • 401 unauthenticated

02 · Authentication

Bearer tokens

Every call sends a static API key in the Authorization header. Sandbox and live keys are separate secrets that never route to the same environment.

  • Header Authorization: Bearer <key>
  • Sandbox prefix sk_sandbox_…
  • Live prefix sk_live_…
  • Missing / invalid 401 unauthenticated
  • Rotation Roll from the dashboard; the old key stays valid for 24 h.
  • Scope A key covers AIS, PIS and META in its environment.

03 · Pagination

Cursor-based

List endpoints (/accounts/{id}/transactions, /banks) return a stable cursor. Iterate until next_cursor is null.

  • Query · limit Integer, default 25, max 100
  • Query · cursor Opaque string returned by the previous page
  • Response · data[] Array of items for the current page
  • Response · next_cursor string | null. When null, iteration is complete.
  • Ordering Newest first for transactions; alphabetical for banks.
  • Cursor lifetime Stable for 24 h; treat as opaque.

04 · Rate limits

Per-key quotas

Limits are per API key and refresh once per second. Every response echoes your remaining budget so you can shape traffic without probing.

  • Sandbox 30 req/s per key
  • Live · default 100 req/s per key
  • Live · scaled Higher tiers on request — talk to sales
  • Response header X-RateLimit-Remaining
  • Response header X-RateLimit-Reset (unix seconds)
  • Over limit 429 rate_limited + Retry-After

05 · Errors

One error envelope

Every 4xx and 5xx response uses the same JSON shape. Match on error.code, display error.message, log error.request_id.

Envelope fields

error.code
string · stable machine code (e.g. consent_missing)
error.message
string · human-readable description
error.request_id
string · echo this to support
error.doc_url
string · link to the relevant guide
error.retry_after
number · seconds, present on 429 and 5xx

Common codes

  • 400 invalid_request Malformed body, unknown field, or missing required parameter.
  • 401 unauthenticated Missing, malformed or revoked API key.
  • 403 consent_missing The consent token does not cover the requested scope.
  • 404 not_found The resource does not exist or is not visible to the current key.
  • 409 duplicate_idempotency_key Retry with a new Idempotency-Key or fetch the original result.
  • 410 consent_expired Consent has expired. Create a new consent and re-authorise the user.
  • 422 unsupported_bank The requested bank does not support this capability yet.
  • 429 rate_limited You hit the per-key rate limit. Respect Retry-After and back off.
  • 5xx bank_upstream A downstream bank failed. Retry with exponential backoff; check /v1/status.

06 · Webhooks

Asynchronous events

PIS settlement is asynchronous. Subscribe to webhooks to be notified when a payment actually credits the receiving account instead of polling.

  • Transport HTTPS POST, JSON body
  • Signature X-viaBanking-Signature (HMAC-SHA256)
  • Retry policy Exponential backoff up to 24 h on non-2xx
  • Acknowledge Return 2xx within 10 seconds

Event catalogue

  • payment.pending Payer confirmed at the bank but funds have not settled.
  • payment.settled Credit posted on the receiving account. Safe to release goods or credit.
  • payment.failed Bank rejected or refunded the payment. Do not release value.
  • payment.cancelled Payer cancelled before settlement, or the consent expired.
  • consent.revoked The user revoked consent. Stop AIS/PIS calls tied to this consent id.

07 · Conventions

Predictable by design

The same rules hold across every endpoint. No surprises per bank, so you write less defensive code.

  • Protocol REST over HTTPS
  • Format JSON in, JSON out
  • Auth Bearer token
  • Version Pinned at /v1/
  • Data model One shape, all accounts
  • Environments Sandbox + live keys

Free sandbox · No card needed

Make your first AIS call today.

Grab a sandbox key from the Quickstart, then come back to this reference for every field and status code.

Get sandbox access Schedule a demo