# Transactions

The Transactions API allows you to initiate transfers, query transaction history, retrieve specific transactions, look up bank details by IBAN, and download account statements.

{% hint style="warning" %}
You must include your **Bearer token** in the request header.
{% endhint %}

## Get transactions by Account

> Retrieves a paginated list of transactions for a specified account within a date range.

```json
{"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.2.0"},"tags":[{"name":"Transactions","description":"Services intended to process payments and view transaction history/statements."}],"servers":[{"url":"https://public-api.gurupay.eu","description":"Production API Server"},{"url":"https://public-api-dev.gurupay.eu","description":"Sandbox API Server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"Authentication using a Bearer token.","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"UUID":{"description":"Universally Unique Identifier (UUID) as defined by RFC 4122.","type":"string","format":"uuid","pattern":"^[a-zA-Z0-9]{8}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{12}$"},"perPage":{"description":"Number of items to return per page in a paginated response.","type":"integer","default":15,"maximum":100,"minimum":1},"page":{"description":"The current page number for paginated results.","type":"integer","default":1,"minimum":1},"API.Resources.TransactionStatementsResource":{"title":"Transaction Statement Resource","description":"Resource representing account details and associated transactions for a statement period.","required":["account","transactions"],"properties":{"account":{"description":"Basic details of the account associated with the statement.","required":["uuid"],"properties":{"uuid":{"description":"The unique identifier of the account.","type":"string","format":"uuid"}},"type":"object"},"transactions":{"description":"A list of transactions included in this statement.","type":"array","items":{"$ref":"#/components/schemas/API.Resources.TransactionResource"}}},"type":"object"},"API.Resources.TransactionResource":{"title":"Transaction Resource","description":"Detailed information about a financial transaction.","properties":{"uuid":{"description":"Unique identifier for the transaction.","type":"string","format":"uuid"},"parent_transaction_uuid":{"description":"UUID of the parent transaction.","type":"string","format":"uuid","nullable":true},"status":{"description":"Current processing status of the transaction.","type":"string","enum":["created","pending","processed","canceled","rejected"]},"aml_status":{"description":"**DEPRECATED:** This field is scheduled for removal on August 4th, 2025. It is already deprecated in the Sandbox environment. Anti-Money Laundering (AML) check status of the transaction.","type":"string","enum":["rejected","approved","error","canceled","pending"],"deprecated":true},"operation_date":{"description":"Date of the transaction operation (YYYY-MM-DD).","type":"string","format":"date"},"operation_date_time":{"description":"Date and time of the transaction operation (ISO 8601 format).","type":"string","format":"date-time"},"operation_date_unix":{"description":"Date and time of the transaction operation as a Unix timestamp (seconds since epoch).","type":"integer","format":"int64"},"amount":{"description":"Transaction amount.","type":"number","format":"float"},"currency":{"description":"Currency code (ISO 4217).","type":"string","format":"ISO 4217"},"payment_type":{"description":"Type of payment rails used.","type":"string","enum":["SEPA","SWIFT","FX","INTERNAL"]},"transaction_type":{"description":"Type of financial transaction, such as payment, return, adjustment, or fee.","type":"string","enum":["payment","return","adjustment","fee"]},"payment_urgency":{"description":"Urgency level of the payment.","type":"string","enum":["NORMAL","URGENT"],"nullable":true},"payment_details":{"description":"Remittance information or payment details provided by the payer.","type":"string","nullable":true},"payment_code":{"description":"Optional payment code associated with the transaction.","type":"string","nullable":true},"end_to_end_ident":{"description":"End-to-end identifier for tracking the payment across systems.","type":"string","nullable":true},"direction":{"description":"Direction of the transaction relative to the account holder.","type":"string","enum":["CREDIT","DEBIT"]},"document_number":{"description":"Reference number of an associated document, if any.","type":"string","nullable":true},"created_at":{"description":"Timestamp when the transaction record was created in the system (Unix timestamp).","type":"integer","format":"int64"},"payer":{"description":"Details of the transaction payer.","required":["name","iban"],"properties":{"name":{"description":"Payer's full name.","type":"string"},"iban":{"description":"Payer's International Bank Account Number.","type":"string"},"address":{"description":"Payer's address.","type":"string","nullable":true},"country_code":{"description":"Payer's country code (ISO 3166-1 alpha-2).","type":"string","format":"ISO 3166-1 alpha-2","nullable":true},"agency_id":{"description":"Identifier of the payer's bank/agent (e.g., BIC/SWIFT code).","type":"string","nullable":true},"agency_name":{"description":"Name of the payer's bank/agent.","type":"string","nullable":true},"agency_address":{"description":"Address of the payer's bank/agent.","type":"string","nullable":true},"ultimate":{"description":"Details of the ultimate debtor, if different from the payer.","properties":{"name":{"description":"Ultimate debtor's name.","type":"string"}},"type":"object","nullable":true}},"type":"object"},"recipient":{"description":"Details of the transaction recipient.","required":["name","iban"],"properties":{"name":{"description":"Recipient's full name.","type":"string"},"iban":{"description":"Recipient's International Bank Account Number.","type":"string"},"address":{"description":"Recipient's address.","type":"string","nullable":true},"country_code":{"description":"Recipient's country code (ISO 3166-1 alpha-2).","type":"string","format":"ISO 3166-1 alpha-2","nullable":true},"agency_id":{"description":"Identifier of the recipient's bank/agent (e.g., BIC/SWIFT code).","type":"string","nullable":true},"agency_name":{"description":"Name of the recipient's bank/agent.","type":"string","nullable":true},"agency_address":{"description":"Address of the recipient's bank/agent.","type":"string","nullable":true},"ultimate":{"description":"Details of the ultimate creditor, if different from the recipient.","properties":{"name":{"description":"Ultimate creditor's name.","type":"string"}},"type":"object","nullable":true}},"type":"object"},"verification_of_payee":{"description":"Verification of the payee match status.","type":"string","enum":["MATCH","CLOSE_MATCH","NO_MATCH","CANNOT_VERIFY"]}},"type":"object"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"},"ValidationResponse":{"title":"Validation Error Response","description":"Standard response format for validation errors (HTTP 422).","required":["status","status_code","message","errors"],"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"description":"An object containing validation errors. Keys are field names, values are arrays of error messages for that field.","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object"}}},"paths":{"/api/v1/transactions":{"get":{"tags":["Transactions"],"summary":"Get transactions by Account","description":"Retrieves a paginated list of transactions for a specified account within a date range.","operationId":"API.Transactions.Get","parameters":[{"name":"account_uuid","in":"query","description":"The UUID of the account to retrieve transactions for.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"date_from","in":"query","description":"Start date for the filter period (YYYY-MM-DD).","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"date_to","in":"query","description":"End date for the filter period (YYYY-MM-DD).","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"per_page","in":"query","description":"Number of transactions to return per page.","required":false,"schema":{"$ref":"#/components/schemas/perPage"}},{"name":"page","in":"query","description":"The page number to retrieve.","required":false,"schema":{"$ref":"#/components/schemas/page"}},{"name":"direction","in":"query","description":"Sort direction for the transaction list.","required":false,"schema":{"type":"string","default":"desc","enum":["asc","desc"]}},{"name":"sort","in":"query","description":"Field to sort the transaction list by.","required":false,"schema":{"type":"string","default":"created_at","enum":["created_at","operation_date"]}}],"responses":{"200":{"description":"A paginated list of transactions matching the criteria.","headers":{"X-RateLimit-Limit":{"description":"The maximum number of requests allowed per minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"The number of requests remaining in the current window.","schema":{"type":"integer"}},"X-Api-Total":{"description":"Total number of records matching the filter criteria.","schema":{"type":"integer"}},"X-Api-Per-Page":{"description":"Number of records returned on the current page.","schema":{"type":"integer"}},"X-Api-Has-More-Pages":{"description":"Indicates if there are more pages available.","schema":{"type":"boolean"}},"X-Api-Has-Has-Page":{"description":"The current page number being returned.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.TransactionStatementsResource"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}}
```

## Create a new transaction

> Create a new transaction

```json
{"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.2.0"},"tags":[{"name":"Transactions","description":"Services intended to process payments and view transaction history/statements."}],"servers":[{"url":"https://public-api.gurupay.eu","description":"Production API Server"},{"url":"https://public-api-dev.gurupay.eu","description":"Sandbox API Server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"Authentication using a Bearer token.","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"UUID":{"description":"Universally Unique Identifier (UUID) as defined by RFC 4122.","type":"string","format":"uuid","pattern":"^[a-zA-Z0-9]{8}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{12}$"},"XRequestId":{"description":"A unique identifier for the request. This header can be used for tracking and idempotency control, ensuring the same request is not processed multiple times.","type":"string","format":"uuid"},"API.Requests.StoreTransaction":{"title":"Store Transaction Request","description":"Data required to initiate a new transaction.","required":["account_uuid","amount","recipient"],"properties":{"account_uuid":{"description":"The UUID of the source account for the transaction.","type":"string","format":"uuid"},"amount":{"description":"The monetary amount of the transaction. Must be greater than 0 and have a maximum of two decimal places.","type":"number","format":"float","minimum":0,"exclusiveMinimum":true},"payer":{"description":"Optional details of the transaction payer.","properties":{"ultimate":{"description":"Ultimate Payer details, if different from the immediate payer.","properties":{"name":{"description":"The ultimate payer's name. Required via validation rules if 'payer.ultimate' object is provided.","type":"string","maxLength":70,"nullable":true}},"type":"object","nullable":true}},"type":"object","nullable":true},"recipient":{"description":"Details of the transaction beneficiary (recipient).","required":["name","iban"],"properties":{"name":{"description":"The full name of the beneficiary.","type":"string","maxLength":70},"iban":{"description":"The beneficiary's International Bank Account Number (IBAN). Must be valid.","type":"string"},"address":{"description":"The beneficiary's full address.","type":"string","maxLength":140,"nullable":true},"country_code":{"description":"The beneficiary's country code (ISO 3166-1 alpha-2). Required for SWIFT. Required for SEPA when address is set","type":"string","maxLength":2,"minLength":2,"nullable":true},"ultimate":{"description":"Ultimate Beneficiary details, if different from the immediate beneficiary.","properties":{"name":{"description":"The ultimate beneficiary's name. Required via validation rules if 'recipient.ultimate' object is provided.","type":"string","maxLength":70,"nullable":true}},"type":"object","nullable":true},"bank":{"description":"Details of the beneficiary's bank.","properties":{"bic":{"description":"SWIFT code of the beneficiary's bank (BIC). Required for SWIFT payments.","type":"string","maxLength":11,"minLength":11,"nullable":true},"name":{"description":"Name of the beneficiary's bank. Required for SWIFT payments.","type":"string","maxLength":140,"nullable":true},"address":{"description":"Address of the beneficiary's bank. Required for SWIFT payments.","type":"string","maxLength":140,"nullable":true},"country_code":{"description":"Country code of the beneficiary's bank (ISO 3166-1 alpha-2).","type":"string","maxLength":2,"minLength":2,"nullable":true}},"type":"object","nullable":true}},"type":"object"},"payment_details":{"description":"Unstructured payment details or remittance information. Mandatory via validation rules if 'payment_code' is not provided.","type":"string","maxLength":140,"nullable":true},"payment_code":{"description":"Structured payment code (e.g., Purpose Code). Mandatory via validation rules if 'payment_details' is not provided.","type":"string","maxLength":35,"nullable":true},"end_to_end_ident":{"description":"Optional End-to-End payment identifier for tracking.","type":"string","maxLength":35,"nullable":true},"payment_type":{"description":"Indicates the type of payment. If not specified, SEPA will be selected by default. Accepted values: swift, sepa.","type":"string","enum":["SWIFT","SEPA"],"nullable":true}},"type":"object"},"API.Resources.TransactionResource":{"title":"Transaction Resource","description":"Detailed information about a financial transaction.","properties":{"uuid":{"description":"Unique identifier for the transaction.","type":"string","format":"uuid"},"parent_transaction_uuid":{"description":"UUID of the parent transaction.","type":"string","format":"uuid","nullable":true},"status":{"description":"Current processing status of the transaction.","type":"string","enum":["created","pending","processed","canceled","rejected"]},"aml_status":{"description":"**DEPRECATED:** This field is scheduled for removal on August 4th, 2025. It is already deprecated in the Sandbox environment. Anti-Money Laundering (AML) check status of the transaction.","type":"string","enum":["rejected","approved","error","canceled","pending"],"deprecated":true},"operation_date":{"description":"Date of the transaction operation (YYYY-MM-DD).","type":"string","format":"date"},"operation_date_time":{"description":"Date and time of the transaction operation (ISO 8601 format).","type":"string","format":"date-time"},"operation_date_unix":{"description":"Date and time of the transaction operation as a Unix timestamp (seconds since epoch).","type":"integer","format":"int64"},"amount":{"description":"Transaction amount.","type":"number","format":"float"},"currency":{"description":"Currency code (ISO 4217).","type":"string","format":"ISO 4217"},"payment_type":{"description":"Type of payment rails used.","type":"string","enum":["SEPA","SWIFT","FX","INTERNAL"]},"transaction_type":{"description":"Type of financial transaction, such as payment, return, adjustment, or fee.","type":"string","enum":["payment","return","adjustment","fee"]},"payment_urgency":{"description":"Urgency level of the payment.","type":"string","enum":["NORMAL","URGENT"],"nullable":true},"payment_details":{"description":"Remittance information or payment details provided by the payer.","type":"string","nullable":true},"payment_code":{"description":"Optional payment code associated with the transaction.","type":"string","nullable":true},"end_to_end_ident":{"description":"End-to-end identifier for tracking the payment across systems.","type":"string","nullable":true},"direction":{"description":"Direction of the transaction relative to the account holder.","type":"string","enum":["CREDIT","DEBIT"]},"document_number":{"description":"Reference number of an associated document, if any.","type":"string","nullable":true},"created_at":{"description":"Timestamp when the transaction record was created in the system (Unix timestamp).","type":"integer","format":"int64"},"payer":{"description":"Details of the transaction payer.","required":["name","iban"],"properties":{"name":{"description":"Payer's full name.","type":"string"},"iban":{"description":"Payer's International Bank Account Number.","type":"string"},"address":{"description":"Payer's address.","type":"string","nullable":true},"country_code":{"description":"Payer's country code (ISO 3166-1 alpha-2).","type":"string","format":"ISO 3166-1 alpha-2","nullable":true},"agency_id":{"description":"Identifier of the payer's bank/agent (e.g., BIC/SWIFT code).","type":"string","nullable":true},"agency_name":{"description":"Name of the payer's bank/agent.","type":"string","nullable":true},"agency_address":{"description":"Address of the payer's bank/agent.","type":"string","nullable":true},"ultimate":{"description":"Details of the ultimate debtor, if different from the payer.","properties":{"name":{"description":"Ultimate debtor's name.","type":"string"}},"type":"object","nullable":true}},"type":"object"},"recipient":{"description":"Details of the transaction recipient.","required":["name","iban"],"properties":{"name":{"description":"Recipient's full name.","type":"string"},"iban":{"description":"Recipient's International Bank Account Number.","type":"string"},"address":{"description":"Recipient's address.","type":"string","nullable":true},"country_code":{"description":"Recipient's country code (ISO 3166-1 alpha-2).","type":"string","format":"ISO 3166-1 alpha-2","nullable":true},"agency_id":{"description":"Identifier of the recipient's bank/agent (e.g., BIC/SWIFT code).","type":"string","nullable":true},"agency_name":{"description":"Name of the recipient's bank/agent.","type":"string","nullable":true},"agency_address":{"description":"Address of the recipient's bank/agent.","type":"string","nullable":true},"ultimate":{"description":"Details of the ultimate creditor, if different from the recipient.","properties":{"name":{"description":"Ultimate creditor's name.","type":"string"}},"type":"object","nullable":true}},"type":"object"},"verification_of_payee":{"description":"Verification of the payee match status.","type":"string","enum":["MATCH","CLOSE_MATCH","NO_MATCH","CANNOT_VERIFY"]}},"type":"object"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"},"ValidationResponse":{"title":"Validation Error Response","description":"Standard response format for validation errors (HTTP 422).","required":["status","status_code","message","errors"],"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"description":"An object containing validation errors. Keys are field names, values are arrays of error messages for that field.","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object"}}},"paths":{"/api/v1/transactions":{"post":{"tags":["Transactions"],"summary":"Create a new transaction","description":"Create a new transaction","operationId":"API.Transactions.Store","parameters":[{"name":"account_uuid","in":"query","description":"The account's UUID from which the transaction originates","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"X-Request-ID","in":"header","description":"A unique identifier for the request to ensure idempotency (optional)","required":false,"schema":{"$ref":"#/components/schemas/XRequestId"}}],"requestBody":{"description":"Transaction details necessary to create a transaction","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Requests.StoreTransaction"}}}},"responses":{"201":{"description":"Transaction Created Successfully. Returns the Transaction Resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.TransactionResource"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}}
```

{% hint style="info" %}
**Important:** API error responses during transaction creation reflect only the technical outcome of a request and do not represent the final business state of a payment. The authoritative and final payment status is delivered through the webhook events and should be treated as the source of truth.

More information about webhook event statuses can be found here: [Transaction Event | Documentation](https://developers.gurupay.eu/webhooks/events/transaction-event)

More information about error handling can be found here: [Error Handling | Documentation](/getting-started/api-concepts/error-handling.md)
{% endhint %}

## Get specific transaction by UUID

> Retrieves the details of a specific transaction by its UUID, scoped to an account.

```json
{"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.2.0"},"tags":[{"name":"Transactions","description":"Services intended to process payments and view transaction history/statements."}],"servers":[{"url":"https://public-api.gurupay.eu","description":"Production API Server"},{"url":"https://public-api-dev.gurupay.eu","description":"Sandbox API Server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"Authentication using a Bearer token.","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"UUID":{"description":"Universally Unique Identifier (UUID) as defined by RFC 4122.","type":"string","format":"uuid","pattern":"^[a-zA-Z0-9]{8}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{12}$"},"API.Resources.TransactionResource":{"title":"Transaction Resource","description":"Detailed information about a financial transaction.","properties":{"uuid":{"description":"Unique identifier for the transaction.","type":"string","format":"uuid"},"parent_transaction_uuid":{"description":"UUID of the parent transaction.","type":"string","format":"uuid","nullable":true},"status":{"description":"Current processing status of the transaction.","type":"string","enum":["created","pending","processed","canceled","rejected"]},"aml_status":{"description":"**DEPRECATED:** This field is scheduled for removal on August 4th, 2025. It is already deprecated in the Sandbox environment. Anti-Money Laundering (AML) check status of the transaction.","type":"string","enum":["rejected","approved","error","canceled","pending"],"deprecated":true},"operation_date":{"description":"Date of the transaction operation (YYYY-MM-DD).","type":"string","format":"date"},"operation_date_time":{"description":"Date and time of the transaction operation (ISO 8601 format).","type":"string","format":"date-time"},"operation_date_unix":{"description":"Date and time of the transaction operation as a Unix timestamp (seconds since epoch).","type":"integer","format":"int64"},"amount":{"description":"Transaction amount.","type":"number","format":"float"},"currency":{"description":"Currency code (ISO 4217).","type":"string","format":"ISO 4217"},"payment_type":{"description":"Type of payment rails used.","type":"string","enum":["SEPA","SWIFT","FX","INTERNAL"]},"transaction_type":{"description":"Type of financial transaction, such as payment, return, adjustment, or fee.","type":"string","enum":["payment","return","adjustment","fee"]},"payment_urgency":{"description":"Urgency level of the payment.","type":"string","enum":["NORMAL","URGENT"],"nullable":true},"payment_details":{"description":"Remittance information or payment details provided by the payer.","type":"string","nullable":true},"payment_code":{"description":"Optional payment code associated with the transaction.","type":"string","nullable":true},"end_to_end_ident":{"description":"End-to-end identifier for tracking the payment across systems.","type":"string","nullable":true},"direction":{"description":"Direction of the transaction relative to the account holder.","type":"string","enum":["CREDIT","DEBIT"]},"document_number":{"description":"Reference number of an associated document, if any.","type":"string","nullable":true},"created_at":{"description":"Timestamp when the transaction record was created in the system (Unix timestamp).","type":"integer","format":"int64"},"payer":{"description":"Details of the transaction payer.","required":["name","iban"],"properties":{"name":{"description":"Payer's full name.","type":"string"},"iban":{"description":"Payer's International Bank Account Number.","type":"string"},"address":{"description":"Payer's address.","type":"string","nullable":true},"country_code":{"description":"Payer's country code (ISO 3166-1 alpha-2).","type":"string","format":"ISO 3166-1 alpha-2","nullable":true},"agency_id":{"description":"Identifier of the payer's bank/agent (e.g., BIC/SWIFT code).","type":"string","nullable":true},"agency_name":{"description":"Name of the payer's bank/agent.","type":"string","nullable":true},"agency_address":{"description":"Address of the payer's bank/agent.","type":"string","nullable":true},"ultimate":{"description":"Details of the ultimate debtor, if different from the payer.","properties":{"name":{"description":"Ultimate debtor's name.","type":"string"}},"type":"object","nullable":true}},"type":"object"},"recipient":{"description":"Details of the transaction recipient.","required":["name","iban"],"properties":{"name":{"description":"Recipient's full name.","type":"string"},"iban":{"description":"Recipient's International Bank Account Number.","type":"string"},"address":{"description":"Recipient's address.","type":"string","nullable":true},"country_code":{"description":"Recipient's country code (ISO 3166-1 alpha-2).","type":"string","format":"ISO 3166-1 alpha-2","nullable":true},"agency_id":{"description":"Identifier of the recipient's bank/agent (e.g., BIC/SWIFT code).","type":"string","nullable":true},"agency_name":{"description":"Name of the recipient's bank/agent.","type":"string","nullable":true},"agency_address":{"description":"Address of the recipient's bank/agent.","type":"string","nullable":true},"ultimate":{"description":"Details of the ultimate creditor, if different from the recipient.","properties":{"name":{"description":"Ultimate creditor's name.","type":"string"}},"type":"object","nullable":true}},"type":"object"},"verification_of_payee":{"description":"Verification of the payee match status.","type":"string","enum":["MATCH","CLOSE_MATCH","NO_MATCH","CANNOT_VERIFY"]}},"type":"object"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"},"ValidationResponse":{"title":"Validation Error Response","description":"Standard response format for validation errors (HTTP 422).","required":["status","status_code","message","errors"],"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"description":"An object containing validation errors. Keys are field names, values are arrays of error messages for that field.","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object"}}},"paths":{"/api/v1/transactions/{uuid}":{"get":{"tags":["Transactions"],"summary":"Get specific transaction by UUID","description":"Retrieves the details of a specific transaction by its UUID, scoped to an account.","operationId":"API.Transactions.Show","parameters":[{"name":"account_uuid","in":"query","description":"The UUID of the account the transaction belongs to.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"uuid","in":"path","description":"The UUID of the transaction to retrieve.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"200":{"description":"Successful retrieval of the transaction details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.TransactionResource"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}}
```

## Get bank details by IBAN

> Retrieves bank details (like BIC, bank name) based on a provided IBAN.

```json
{"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.2.0"},"tags":[{"name":"Transactions","description":"Services intended to process payments and view transaction history/statements."}],"servers":[{"url":"https://public-api.gurupay.eu","description":"Production API Server"},{"url":"https://public-api-dev.gurupay.eu","description":"Sandbox API Server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"Authentication using a Bearer token.","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"API.Resources.IbanResource":{"title":"IBAN Details Resource","description":"Resource representing bank details derived from an IBAN.","properties":{"iban":{"description":"The IBAN that was looked up.","type":"string"},"is_valid":{"description":"Indicates if the provided IBAN format is considered valid.","type":"boolean"},"bank_bic":{"description":"The Bank Identifier Code (BIC/SWIFT) associated with the IBAN.","type":"string","nullable":true},"bank_name":{"description":"The name of the bank associated with the IBAN.","type":"string","nullable":true}},"type":"object"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"},"ValidationResponse":{"title":"Validation Error Response","description":"Standard response format for validation errors (HTTP 422).","required":["status","status_code","message","errors"],"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"description":"An object containing validation errors. Keys are field names, values are arrays of error messages for that field.","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object"}}},"paths":{"/api/v1/transactions/iban-details":{"get":{"tags":["Transactions"],"summary":"Get bank details by IBAN","description":"Retrieves bank details (like BIC, bank name) based on a provided IBAN.","operationId":"API.Transactions.Iban","parameters":[{"name":"iban","in":"query","description":"The International Bank Account Number (IBAN) to look up.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved IBAN details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.IbanResource"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}}
```

{% hint style="danger" %}
Please note that the **`GET /api/v1/transactions/statements`** endpoint will be **removed and no longer supported after February 14, 2026**.

Use the Statements API to generate and download statements: [Statements | Documentation](https://developers.gurupay.eu/api-reference/statements)
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.gurupay.eu/api-reference/transactions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.