Transactions

Given a user’s online banking credentials, the Transactions Service allows to gather transactions for a user’s account.

Depending on your use case, the service sends the requested transaction data either to your frontend or to a webhook endpoint.

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 transactions opt Strong Customer Authentication Bank-->>-User: Request authorization User->>+Bank: Authorize end Bank-->>-YAXI: Transcations YAXI-->>-User: Transactions opt Transfer authenticated transactions to backend User->>+Your Backend: Transactions Your Backend->>+Your Backend: Verify authenticity Your Backend-->>-User: OK end

Issue a service ticket

Use Transactions as a service identifier when issuing tickets. The service expects the following ticket data:

Issue a service ticket:

Python
Java
Node.js
Rust
PHP

ticket_id = str(uuid.uuid4())
ticket = issue_ticket(
    ticket_id,
    "Transactions",
    {
        "account": {
            "iban": "NL58YAXI1234567890",
            "currency": "EUR",
        },
        "range": {
            "from": "2019-01-13",
        },
    },
)

String ticketId = UUID.randomUUID().toString();
String ticket = issueTicket(
    ticketId,
    "Transactions",
    Map.of(
        "account", Map.of(
            "iban", "NL58YAXI1234567890",
            "currency", "EUR"
        ),
        "range", Map.of(
            "from", "2019-01-13"
        )
    )
);

let ticketId = uuidv4()
let ticket = issueTicket(
  ticketId,
  'Transactions',
  {
    account: { iban: 'NL58YAXI1234567890', currency: 'EUR' },
    range: { from: '2019-01-13' }
  }
)

let ticket_id = Uuid::new_v4().to_string();
let ticket = issue_ticket(
    &ticket_id,
    "Transactions",
    json!({
        "account": {
            "iban": "NL58YAXI1234567890",
            "currency": "EUR",
        },
        "range": {
            "from": "2019-01-13",
        },
    }),
)?;

$ticketId = uniqid();
$ticket = issueTicket(
    $ticketId,
    'Transactions',
    json_encode([
        'account' => [
            'id' => [
                'iban' => 'NL58YAXI1234567890',
            ],
            'currency' => 'EUR',
        ],
        'range' => [
            'from' => '2019-01-13',
        ],
    ])
);

Call the service

The service does not support any specific client arguments.

Call the service:

JavaScript
Kotlin
Rust

await client.transactions({
  credentials,
  ticket,
})

client.transactions(
    credentials,
    ticket = ticket,
)

client.transactions(
    credentials,
    None,
    ticket,
).await?;

Result

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

The resulting JWT contains the following data:

ISO 20022 external code sets are available at https://www.iso20022.org/catalogue-messages/additional-content-messages/external-code-sets.

Example result:

Result JWT
Decoded JWT header
Decoded JWT payload

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImFwaS1rZXktMjE0YWQ
2MDEtZmFlNS00NWY4LTllNDItYTFiNTdkNTA0MTRjIn0.eyJkYXRhIjp7ImRhdG
EiOlt7ImJvb2tpbmdEYXRlIjoiMjAyNC0wNS0wMiIsInZhbHVlRGF0ZSI6IjIwM
jQtMDUtMDIiLCJ0cmFuc2FjdGlvbkRhdGEiOiIyMDI0LTA1LTAxIiwic3RhdHVz
IjoiQm9va2VkIiwiZW5kVG9FbmRJZCI6Ijc4NTY0MyIsImFtb3VudCI6eyJjdXJ
yZW5jeSI6IkVVUiIsImFtb3VudCI6Ii0xOS45OSJ9LCJjcmVkaXRvciI6eyJuYW
1lIjoiQXdlc29tZVNob3AiLCJpYmFuIjoiTkwzMVlBWEkxMjM0NTY3ODkxIn0sI
mRlYnRvciI6eyJpYmFuIjoiTkw1OFlBWEkxMjM0NTY3ODkwIn0sInJlbWl0dGFu
Y2VJbmZvcm1hdGlvbiI6WyJBd2Vzb21lU2hvcCBZb3VyIHB1cmNoYXNlIiwiMjA
yNC0wNS0wMSBUaGFuayB5b3UiXX1dLCJ0aWNrZXRJZCI6IjgxNDJkYTM4LTNjM2
EtNGUzYi1hZDlhLTI5OWQ1NjFmNjMyOSIsInRpbWVzdGFtcCI6IjIwMjUtMDYtM
DFUMTE6MDE6MjYuNzcyNTk2MjMxWiJ9LCJleHAiOjI1NDA4MDgwMDB9.rw0RSrD
afcTiZICwpNZ-stxOQMY24Q0RYhcCtZlElyE

{
  "typ": "JWT",
  "alg": "HS256",
  "kid": "api-key-214ad601-fae5-45f8-9e42-a1b57d50414c"
}

{
  "data": {
    "data": [
      {
        "bookingDate": "2024-05-02",
        "valueDate": "2024-05-02",
        "transactionData": "2024-05-01",
        "status": "Booked",
        "endToEndId": "785643",
        "amount": {
          "currency": "EUR",
          "amount": "-19.99"
        },
        "creditor": {
          "name": "AwesomeShop",
          "iban": "NL31YAXI1234567891"
        },
        "debtor": {
          "iban": "NL58YAXI1234567890"
        },
        "remittanceInformation": [
          "AwesomeShop Your purchase",
          "2024-05-01 Thank you"
        ]
      }
    ],
    "ticketId": "8142da38-3c3a-4e3b-ad9a-299d561f6329",
    "timestamp": "2025-06-01T11:01:26.772596231Z"
  },
  "exp": 2540808000
}

Webhook

If you provide a webhook URL, YAXI sends the result JWT to that URL via an HTTP POST request, while the client on your frontend receives an empty result. This approach eliminates the need for your frontend to download large amounts of transaction data only to upload it to a backend for further processing or storage. We recommend using this approach unless you are only processing the transaction data locally on the frontend. You must handle the received data as a forwarded result, verifying its HMAC and ticket identifier.