> For the complete documentation index, see [llms.txt](https://developers.gurupay.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gurupay.eu/api-reference/transactions.md).

# 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.4.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","deprecated":true,"enum":["rejected","approved","error","canceled","pending"]},"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","nullable":true,"enum":["NORMAL","URGENT"]},"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":"Deprecated. Payer's address as a single line, built from the structured address fields. Use the structured fields instead.","type":"string","nullable":true,"deprecated":true},"country_code":{"description":"Payer's country code (ISO 3166-1 alpha-2).","type":"string","format":"ISO 3166-1 alpha-2","nullable":true},"street_name":{"description":"Payer's street name, without the building number.","type":"string","nullable":true},"building_number":{"description":"Payer's building number.","type":"string","nullable":true},"building_name":{"description":"Payer's building name.","type":"string","nullable":true},"post_code":{"description":"Payer's post code.","type":"string","nullable":true},"town_name":{"description":"Payer's town name.","type":"string","nullable":true},"country_sub_division":{"description":"Payer's state, region or province.","type":"string","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},"agency_country":{"description":"Country code of the payer's bank/agent (ISO 3166-1 alpha-2).","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":"Deprecated. Recipient's address as a single line, built from the structured address fields. Use the structured fields instead.","type":"string","nullable":true,"deprecated":true},"country_code":{"description":"Recipient's country code (ISO 3166-1 alpha-2).","type":"string","format":"ISO 3166-1 alpha-2","nullable":true},"street_name":{"description":"Recipient's street name, without the building number.","type":"string","nullable":true},"building_number":{"description":"Recipient's building number.","type":"string","nullable":true},"building_name":{"description":"Recipient's building name.","type":"string","nullable":true},"post_code":{"description":"Recipient's post code.","type":"string","nullable":true},"town_name":{"description":"Recipient's town name.","type":"string","nullable":true},"country_sub_division":{"description":"Recipient's state, region or province.","type":"string","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},"agency_country":{"description":"Country code of the recipient's bank/agent (ISO 3166-1 alpha-2).","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.\
> \
> \*\*SWIFT addresses from 13 November 2026\*\*\
> \
> Both \`recipient\` and \`recipient.bank\` must contain \`town\_name\` and \`country\_code\`. The other structured address fields are optional: \`street\_name\`, \`building\_number\`, \`building\_name\`, \`post\_code\` and \`country\_sub\_division\`.\
> \
> To migrate an existing SWIFT request:\
> 1\. Replace \`recipient.address\` with the separate structured address fields.\
> 2\. Replace \`recipient.bank.address\` in the same way.\
> 3\. Remove both old \`address\` fields entirely, including when structured fields are also supplied. Do not put the complete address into \`street\_name\`.\
> \
> The recipient bank's \`bic\` and \`name\` remain required for SWIFT. This change affects the request; the deprecated address strings in responses remain available.\
> \
> \*\*SEPA addresses\*\*\
> \
> SEPA continues to accept either format. A legacy recipient address uses \`address\` and \`country\_code\`; \`town\_name\` is not required. Addresses may be omitted. Providing only \`country\_code\` for the recipient or recipient bank does not require \`town\_name\`. Providing any non-empty structured component (\`town\_name\`, \`street\_name\`, \`building\_number\`, \`building\_name\`, \`post\_code\` or \`country\_sub\_division\`) requires both \`town\_name\` and \`country\_code\`. The recipient bank is optional; a legacy bank address does not require \`country\_code\`. If legacy text and structured components are supplied together, the structured address requirements also apply.\
> \
> Select the SWIFT or SEPA request example below and replace \`account\_uuid\` with your own account UUID. The SWIFT example shows the format required from 13 November 2026. See the 422 examples for missing address fields and rejected SWIFT address lines.

```json
{"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.4.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","nullable":true,"maxLength":70}},"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":"Free-text address line of the beneficiary. From 13 November 2026, omit this field for SWIFT payments and send town_name and country_code with optional structured fields instead. It is rejected even when structured fields are also supplied. SEPA continues to accept this field.","type":"string","nullable":true,"deprecated":true,"maxLength":140},"country_code":{"description":"Country of the beneficiary (ISO 3166-1 alpha-2). Mandatory whenever any address element is provided.","type":"string","nullable":true,"maxLength":2,"minLength":2},"town_name":{"description":"Town name of the beneficiary. Required for a structured address; not required for SEPA with no address, country_code only, or a free-text address.","type":"string","nullable":true,"maxLength":35},"street_name":{"description":"Street name, without the building number.","type":"string","nullable":true,"maxLength":70},"building_number":{"description":"Building number.","type":"string","nullable":true,"maxLength":16},"building_name":{"description":"Building name.","type":"string","nullable":true,"maxLength":35},"post_code":{"description":"Post code.","type":"string","nullable":true,"maxLength":16},"country_sub_division":{"description":"State, region or province.","type":"string","nullable":true,"maxLength":35},"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","nullable":true,"maxLength":70}},"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","nullable":true,"maxLength":11,"minLength":11},"name":{"description":"Name of the beneficiary's bank. Required for SWIFT payments.","type":"string","nullable":true,"maxLength":140},"address":{"description":"Free-text address line of the beneficiary's bank. From 13 November 2026, omit this field for SWIFT payments and send town_name and country_code with optional structured fields instead. It is rejected even when structured fields are also supplied. SEPA continues to accept this field.","type":"string","nullable":true,"deprecated":true,"maxLength":140},"country_code":{"description":"Country of the beneficiary's bank (ISO 3166-1 alpha-2). Required for SWIFT payments and whenever a structured bank address is provided.","type":"string","nullable":true,"maxLength":2,"minLength":2},"town_name":{"description":"Town name of the beneficiary's bank. Required for a structured address; not required for SEPA with no bank address, bank country_code only, or a free-text bank address.","type":"string","nullable":true,"maxLength":35},"street_name":{"description":"Street name, without the building number.","type":"string","nullable":true,"maxLength":70},"building_number":{"description":"Building number.","type":"string","nullable":true,"maxLength":16},"building_name":{"description":"Building name.","type":"string","nullable":true,"maxLength":35},"post_code":{"description":"Post code.","type":"string","nullable":true,"maxLength":16},"country_sub_division":{"description":"State, region or province.","type":"string","nullable":true,"maxLength":35}},"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","nullable":true,"maxLength":140},"payment_code":{"description":"Structured payment code (e.g., Purpose Code). Mandatory via validation rules if 'payment_details' is not provided.","type":"string","nullable":true,"maxLength":35},"end_to_end_ident":{"description":"Optional End-to-End payment identifier for tracking.","type":"string","nullable":true,"maxLength":35},"payment_type":{"description":"Indicates the type of payment. If not specified, SEPA will be selected by default. Accepted values: swift, sepa.","type":"string","nullable":true,"enum":["SWIFT","SEPA"]}},"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","deprecated":true,"enum":["rejected","approved","error","canceled","pending"]},"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","nullable":true,"enum":["NORMAL","URGENT"]},"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":"Deprecated. Payer's address as a single line, built from the structured address fields. Use the structured fields instead.","type":"string","nullable":true,"deprecated":true},"country_code":{"description":"Payer's country code (ISO 3166-1 alpha-2).","type":"string","format":"ISO 3166-1 alpha-2","nullable":true},"street_name":{"description":"Payer's street name, without the building number.","type":"string","nullable":true},"building_number":{"description":"Payer's building number.","type":"string","nullable":true},"building_name":{"description":"Payer's building name.","type":"string","nullable":true},"post_code":{"description":"Payer's post code.","type":"string","nullable":true},"town_name":{"description":"Payer's town name.","type":"string","nullable":true},"country_sub_division":{"description":"Payer's state, region or province.","type":"string","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},"agency_country":{"description":"Country code of the payer's bank/agent (ISO 3166-1 alpha-2).","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":"Deprecated. Recipient's address as a single line, built from the structured address fields. Use the structured fields instead.","type":"string","nullable":true,"deprecated":true},"country_code":{"description":"Recipient's country code (ISO 3166-1 alpha-2).","type":"string","format":"ISO 3166-1 alpha-2","nullable":true},"street_name":{"description":"Recipient's street name, without the building number.","type":"string","nullable":true},"building_number":{"description":"Recipient's building number.","type":"string","nullable":true},"building_name":{"description":"Recipient's building name.","type":"string","nullable":true},"post_code":{"description":"Recipient's post code.","type":"string","nullable":true},"town_name":{"description":"Recipient's town name.","type":"string","nullable":true},"country_sub_division":{"description":"Recipient's state, region or province.","type":"string","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},"agency_country":{"description":"Country code of the recipient's bank/agent (ISO 3166-1 alpha-2).","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.\n\n**SWIFT addresses from 13 November 2026**\n\nBoth `recipient` and `recipient.bank` must contain `town_name` and `country_code`. The other structured address fields are optional: `street_name`, `building_number`, `building_name`, `post_code` and `country_sub_division`.\n\nTo migrate an existing SWIFT request:\n1. Replace `recipient.address` with the separate structured address fields.\n2. Replace `recipient.bank.address` in the same way.\n3. Remove both old `address` fields entirely, including when structured fields are also supplied. Do not put the complete address into `street_name`.\n\nThe recipient bank's `bic` and `name` remain required for SWIFT. This change affects the request; the deprecated address strings in responses remain available.\n\n**SEPA addresses**\n\nSEPA continues to accept either format. A legacy recipient address uses `address` and `country_code`; `town_name` is not required. Addresses may be omitted. Providing only `country_code` for the recipient or recipient bank does not require `town_name`. Providing any non-empty structured component (`town_name`, `street_name`, `building_number`, `building_name`, `post_code` or `country_sub_division`) requires both `town_name` and `country_code`. The recipient bank is optional; a legacy bank address does not require `country_code`. If legacy text and structured components are supplied together, the structured address requirements also apply.\n\nSelect the SWIFT or SEPA request example below and replace `account_uuid` with your own account UUID. The SWIFT example shows the format required from 13 November 2026. See the 422 examples for missing address fields and rejected SWIFT address lines.","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":"Validation failed. Address errors identify the affected recipient or recipient bank field.","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](https://developers.gurupay.eu/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.4.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","deprecated":true,"enum":["rejected","approved","error","canceled","pending"]},"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","nullable":true,"enum":["NORMAL","URGENT"]},"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":"Deprecated. Payer's address as a single line, built from the structured address fields. Use the structured fields instead.","type":"string","nullable":true,"deprecated":true},"country_code":{"description":"Payer's country code (ISO 3166-1 alpha-2).","type":"string","format":"ISO 3166-1 alpha-2","nullable":true},"street_name":{"description":"Payer's street name, without the building number.","type":"string","nullable":true},"building_number":{"description":"Payer's building number.","type":"string","nullable":true},"building_name":{"description":"Payer's building name.","type":"string","nullable":true},"post_code":{"description":"Payer's post code.","type":"string","nullable":true},"town_name":{"description":"Payer's town name.","type":"string","nullable":true},"country_sub_division":{"description":"Payer's state, region or province.","type":"string","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},"agency_country":{"description":"Country code of the payer's bank/agent (ISO 3166-1 alpha-2).","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":"Deprecated. Recipient's address as a single line, built from the structured address fields. Use the structured fields instead.","type":"string","nullable":true,"deprecated":true},"country_code":{"description":"Recipient's country code (ISO 3166-1 alpha-2).","type":"string","format":"ISO 3166-1 alpha-2","nullable":true},"street_name":{"description":"Recipient's street name, without the building number.","type":"string","nullable":true},"building_number":{"description":"Recipient's building number.","type":"string","nullable":true},"building_name":{"description":"Recipient's building name.","type":"string","nullable":true},"post_code":{"description":"Recipient's post code.","type":"string","nullable":true},"town_name":{"description":"Recipient's town name.","type":"string","nullable":true},"country_sub_division":{"description":"Recipient's state, region or province.","type":"string","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},"agency_country":{"description":"Country code of the recipient's bank/agent (ISO 3166-1 alpha-2).","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.4.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 was **removed and no longer supported as of February 14, 2026**.

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
