Balances

Given a user’s online banking credentials, the Balances Service allows to gather balances for a user’s accounts.

sequenceDiagram actor User participant YAXI participant Your Backend participant Bank User->>+Your Backend: Ticket request Your Backend-->>User: Ticket with ID and accounts rect rgb(243, 243, 243) note right of User: Encrypted and verified channel User->>+YAXI: Ticket YAXI->>+YAXI: Verify authenticity YAXI-->>-User: Bank login form User->>+YAXI: Send login credentials end YAXI->>+Bank: Get balances opt Strong Customer Authentication Bank-->>-User: Request authorization User->>+Bank: Authorize end Bank-->>-YAXI: Balances YAXI-->>-User: Balances opt Transfer authenticated balances to backend User->>+Your Backend: Balances Your Backend->>+Your Backend: Verify authenticity Your Backend-->>-User: OK end

Issue a service ticket backend

Use Balances as a service identifier when issuing tickets. The service does not accept any ticket data.

Issue a service ticket:

  • Python

  • Java

  • Node.js

  • Rust

  • PHP

ticket_id = str(uuid.uuid4())
ticket = issue_ticket(ticket_id, "Balances", None)
String ticketId = UUID.randomUUID().toString();
String ticket = issueTicket(ticketId, "Balances", null);
let ticketId = uuidv4()
let ticket = issueTicket(ticketId, 'Balances', null)
let ticket_id = Uuid::new_v4().to_string();
let ticket = issue_ticket(&ticket_id, "Balances", ())?;
$ticketId = uniqid();
$ticket = issueTicket($ticketId, 'Balances', null);

Call the service frontend

The client accepts the following arguments:

  • Accounts to gather balances for.

    This could be provided by the user, known from a previous transaction, or gathered from the accounts service.

Call the service:

  • JavaScript

  • Kotlin

  • Rust

await client.balances({
  credentials,
  ticket,
  accounts: [
    {
      iban: "NL58YAXI1234567890",
      currency: "EUR"
    }
  ]
})
client.balances(
    credentials,
    ticket = ticket,
    accounts = listOf(
        AccountReference(
            AccountIdentifier.Iban("NL58YAXI1234567890"),
            currency = "EUR",
        )
    ),
)
client.balances(
    credentials,
    None,
    ticket,
    [
        AccountReference {
            id: AccountIdentifier::Iban("NL58YAXI1234567890".to_string()),
            currency: Some("EUR".to_string()),
        }
    ]
).await?;

Result frontend backend

Process the resulting balances in your frontend or forward them to your backend system that can verify their authenticity.

The resulting JWT contains the following data:

Example result:

  • Result JWT

  • Decoded JWT header

  • Decoded JWT payload

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImFwaS1rZXktMjE0YWQ
2MDEtZmFlNS00NWY4LTllNDItYTFiNTdkNTA0MTRjIn0.eyJkYXRhIjp7ImRhdG
EiOlt7ImJhbGFuY2VzIjpbeyJhY2NvdW50Ijp7ImliYW4iOiJOTDU4WUFYSTEyM
zQ1Njc4OTAifSwiYmFsYW5jZXMiOlt7ImFtb3VudCI6IjgwLjAwIiwiY3VycmVu
Y3kiOiJFVVIiLCJiYWxhbmNlVHlwZSI6IkJvb2tlZCJ9LHsiYW1vdW50IjoiNzA
uMDAiLCJjdXJyZW5jeSI6IkVVUiIsImJhbGFuY2VUeXBlIjoiRXhwZWN0ZWQifV
19XX1dLCJ0aWNrZXRJZCI6IjgxNDJkYTM4LTNjM2EtNGUzYi1hZDlhLTI5OWQ1N
jFmNjMyOSIsInRpbWVzdGFtcCI6IjIwMjUtMDYtMDFUMTE6MDE6MjYuNzcyNTk2
MjMxWiJ9LCJleHAiOjI1NDA4MDgwMDB9.mYgYNZYKrcKne5Bx0m63aC22Jv9emM
G2pJDrRd8YLrk
{
  "typ": "JWT",
  "alg": "HS256",
  "kid": "api-key-214ad601-fae5-45f8-9e42-a1b57d50414c"
}
{
  "data": {
    "data": [
      {
        "balances": [
          {
            "account": {
              "iban": "NL58YAXI1234567890"
            },
            "balances": [
              {
                "amount": "80.00",
                "currency": "EUR",
                "balanceType": "Booked"
              },
              {
                "amount": "70.00",
                "currency": "EUR",
                "balanceType": "Expected"
              }
            ]
          }
        ]
      }
    ],
    "ticketId": "8142da38-3c3a-4e3b-ad9a-299d561f6329",
    "timestamp": "2025-06-01T11:01:26.772596231Z"
  },
  "exp": 2540808000
}