# Overview A short intro explaining what the API is for, who it's for, and what problems it solves. ## Welcome to the Guru Pay Public API UAB Guru Pay provides a developer-friendly REST API for integrating payment infrastructure into your applications and platforms. This documentation will guide you through the avialable endpoints, authentication mechanisms, and usage examples so you can seamlessly connect to Guru Pay's payment services. ## What You Can Do with the API * Access accounts information * Access customers information * Initiate and monitor payment transactions * Retrieve transaction history * Manage webhooks * Retrieve sent webhooks history {% hint style="warning" %} All endpoints described in this documentation are prefixed with /api/v1. {% endhint %} ## API Base URL ``` https://public-api.gurupay.eu ``` ## Sandbox API Base URL ``` https://public-api-dev.gurupay.eu ``` # System Status This page provides am overview of the current operational status of our internal systems. Updates are made as incidents occur or systems are scheduled for maintenance. ### βœ… System Overview | System | Description | Status | Notes | | -------------------- | ---------------------------- | --------- | ----------- | | **Internet Banking** | Internet banking application | 🟒 Online | Operational | | **Public API** | Public API system | 🟒 Online | Operational | | **Internal Systems** | Internal banking systems | 🟒 Online | Operational | *** ### πŸ”§ Current Issues * Currently we're not experiencing any issues. *** ### ℹ️ Legend * 🟒 **Online** – System is fully operational * 🟠 **Degraded** – System is functional but experiencing issues * πŸ”΄ **Offline** – System is currently unavailable * πŸ”§ **Maintenance** – System is undergoing scheduled maintenance *** # Changelog All notable changes to internal systems will be documented in this file. *** ### 2026-04-01 **Updates to the Create Virtual Account flow**\ \ We’ve updated the [Create Virtual Account](https://developers.gurupay.eu/api-reference/virtual-ibans#post-api-v1-customers-customer_uuid-accounts-open-virtual) flow to support compliance checks and document uploads.\ \ **What’s new:** * **New optional request field:** `company.industry_type` has been added as a new enum field in the Create Virtual Account request. * **Additional response fields:** The response now includes the metadata fields `uuid` and `status`. * **New response status:** When a request is submitted, the response now returns `201` with status `WAITING_FOR_APPROVAL`. * **Default approval behavior remains unchanged:** Virtual Account Creation requests are approved automatically by default. In some cases, additional compliance checks may be required, and the request may be placed in a review queue. The virtual account becomes available only after the process has been completed and confirmed by webhook. * **Webhook status updates:** Once Virtual Account creation or review is completed, the webhook sends the status `CREATED` or `REJECTED` * **New document upload endpoint:** A new endpoint has been added to support document uploads related to virtual accounts: `/api/v1/customers/{customer_uuid}/accounts/{account_uuid}/documents` ### 2025-11-19 #### Added We've introduced new a field in [Virtual IBANs](/api-reference/virtual-ibans) resource. * Introduced a new field: **`external_id`** (`string`) in the Virtual IBAN API response. * This identifier can be used to **track and correlate virtual IBANs** with external systems. * The value is a unique string (UUID format). * **Example:** `bbf12075-90a8-462f-bc73-7c10cec42147` ### 2025-11-18 #### Added We've introduced new API endpoints to streamline account statement management: * **GET Single Statement**: Retrieve a specific account statement by its identifier. * **GET List of Generated Statements**: Access a list of all available statements. * **POST Generate New Statement**: Create a new account statement. These endpoints improve the efficiency and flexibility of handling account statements. ### 2025-11-05 #### Added * Optional `balance_type` parameter to [Transactions](/api-reference/transactions#get-api-v1-transactions-statements) which determines how account balances are calculated (*settled* or *pending* transactions) ### 2025-10-15 #### Added A new parameter has been introduced to show the result of payee verification. Before queuing the transaction for processing, we perform the verification of payee and provide the outcome. * The [**Transaction**](/api-reference/transactions) **Create Response Resource** has been amended with a parameter **`verification_of_payee` .** * **Possible values:** * **`MATCH`** - the payee details fully match. * **`NO_MATCH`** - the payee details do not match. * **`CLOSE_MATCH`** - the payee details are similar but not identical. * **`CANNOT_VERIFY`** - the payee verification could not be completed. ### 2025-09-11 * Added Virtual IBANs section ### 2025-06-05 #### Deprecated * `aml_status` field in the [**Transactions**](/api-reference/transactions) resource has been deprecated. * ⚠️ This field will be **fully removed** from all API responses on **2025-08-04**. * Please update any integrations relying on this field before the removal date. **Enhancement to `status` field in the** [**Transactions**](/api-reference/transactions) **resource.** * ⚠️ **New statuses will be introduced on 2025-08-04,** released to production together with the removal of `aml_status`. * The `status` field now includes five possible values: * `created` (changable): Transaction is created; processing not yet started. * `pending` (changable): Transaction is currently being processed. * `processed` (final): Transaction has been successfully processed. * `canceled` (final): Transaction has been canceled. * `rejected` (final): Transaction has been rejected. * **Note:** Make sure your integration is prepared to handle these new `status` values. # Developer Dashboard The Guru Pay Developer Dashboard is your central hub for managing API access, subscriptions to webhooks, and customer relationships. It provides all the tools needed to securely integrate. [Guru Pay API Dashboard Link](https://public-api.gurupay.eu/) ## Getting access **Sandbox Access**\ To request access to the Sandbox environment, email from your authorized email address. Please include the email address where you'd like us to send the invitation. You will receive two test accounts with added balance which will allow you proceed with tests right away. **Production Access**\ To request Production access, email both and your account manager from your authorized email address. In your message, include: * The email address where the invitation should be sent * The IP addresses of your office and servers that need to be whitelisted If you need **our IP addresses** for whitelisting on your side, please reach out to our Client Care team. **User Information** More than one user can be added to your dashboard, however only one can be the Main one (admin rights) who will be able to set up Webhook URL and Token. ## Viewing Assigned Customers In the dashboard, you can view which customers are linked to your API user profile. This allows you to explore the customer-specific context and data available via the API. ### What you'll see Under API User information, the following is displayed: * **Name** and **Email** of the authenticated dashboard user. * **Dashboard user UUID** - your unique identifier within Guru Pay API. * **Customers UUID** together with **Customer Name** - the list of customers your API user is authorized to interact with.

API User Information

Each customer is shown with clickable link (blue text). Clicking on a customer will show: * A list of accounts to that customer

List of selected customer

{% hint style="info" %} You cannot assign or manage customers yourself. This is configured by Guru Pay. {% endhint %} ## API Token Management From the dashboard, you can: * Generate new API tokens (**Tokens -> Generate a new token**)

New token generation

* Revoke your existing tokens and see expiration

Existing token row & actions

{% hint style="warning" %} Keep your API keys secure and do not expose them in frontend code or public repositories. {% endhint %} ## Webhook Subscriptions You can subscribe to webhook events directly from the dashboard. ### Subscribe to webhook events You can subscribe to webhook events.

Webhook subscription settings

`Token` is being sent as HTTP header `X-Api-Token` with the webhook, so you could make the authentication mechanism of webhooks based on that. {% hint style="info" %} You can subscribe using only one endpoint. Multiple subscriptions are not allowed. {% endhint %}

Existing webhook setting view

### View webhook delivery logs and status The webhook delivery logs feature in the Guru Pay API dashboard helps you debug and monitor webhook events sent to your system. Every webhook event triggered by the Guru Pay API is logged with its delivery status. Each log entry contains: * Time * UUID * Status * Account * Transaction # API Concepts # Error Handling Guru Pay uses consistent and structured error responses to help you debug and recover from failed requests easily. ## Error Response Format All error responses follow the same JSON structure: ```json { "status": false, "status_code": 422, "message": "VALIDATION_ERROR", "errors": { "email": ["The email field is required."], "password": ["The password must be at least 8 characters."] } } ``` | Field | Type | Descriptio | | ------------ | --------------- | --------------------------------------------------------- | | status | boolean | Always `false` in case of an error. | | status\_code | integer | Standard HTTP status code | | message | string | Machine-readable error type or message. | | errors | array or object | Detailed error info (validation errors, system messages). | ## Common Error Types | HTTP Code | Message | Description | | --------- | ----------------------- | -------------------------------------------------------- | | 400 | INTERNAL\_SERVER\_ERROR | Unexpected. server-side or integration error. | | 401 | UNAUTHORIZED | Invalid or missing API token. | | 403 | NO\_PERMISSION | Authenticated but not authorized to access the resource. | | 404 | NOT\_FOUND | Resource or endpoint not found. | | 422 | VALIDATION\_ERROR | Request failed input validation. | | 429 | Too Many Attempts. | Rate limit exceeded. | | 500 | INTERNAL\_SERVER\_ERROR | Unhandled internal error. | {% hint style="info" %} **Important:** API responses 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 event and should be treated as the source of truth. More information about webhook events statuses can be found here: [Transaction Event | Documentation](/webhooks/events/transaction-event) {% endhint %} # Rate Limits To ensure fair use and protect system stability, Guru Pay enforces rate limiting on all Public API requests. ## Rate Limit Headers Each API response includes headers to help you monitor your usage in real time: | Header | Description | | ----------------------- | ------------------------------------------------------- | | `X-RateLimit-Limit` | The maximum number of requests allowed per minute. | | `X-RateLimit-Remaining` | THe number of remaining requests in the current window. | ## Current Limit * Limit: `500` requests per minute * Applies to: Each IP address This means your application can make up to **500 API requests per minute** from a single IP address. Requests exceeding this limit will be temporarily blocked. ## What Happens If You Go Over? If your application exceeds the limit: * You will receive an HTTP **429 Too Many Requests** response. * You must wait **at least 1 minute** before retrying. **Example 429 Error Response:** ```json { "status": false, "status_code": 429, "message": "Too Many Attempts.", "errors": [ "Too Many Attempts." ] } ``` # Pagination Guru Pay API endpoints that return lists of resources (e.g., transactions) support **pagination** to efficiently deliver large datasets in manageable chunks. {% hint style="info" %} Pagination metadata is included via **custom HTTP response headers**, not in the response body. {% endhint %} ## Headers | Header | Type | Description | | -------------------- | ------- | ---------------------------------------------------------------------------- | | X-Api-Total | integer | Total number of records. | | X-Api-Per-Page | integer | Number of records returned on the current page. | | X-Api-Has-More-Pages | integer | Returns `1` when additional pages are available. Otherwise, returns nothing. | | X-Api-Has-Has-Pages | integer | Returns last page number. | | X-Api-Page | integer | Current page number (starts from 1). | ## Example Response Headers ```http X-Api-Total: 60 X-Api-Per-Page: 20 X-Api-Has-More-Pages: 1 X-Api-Current-Page: 1 ``` ## Example Usage ```http GET /api/v1/transactions?page=1 Authorization: Bearer YOUR_API_TOKEN ``` ## Best Practices * Always check `X-Api-Has-More-Pages` before making another request. * Avoid hardcoding limits - respect the `X-Api-Per-Page` value in case the backend changes. {% hint style="warning" %} Please note that paginated results are limited to the first 10,000 matching records. If you reach this limit, refine your filters to narrow the result set. {% endhint %} # Filtering Guru Pay API endpoints (e.g., transactions api) allow you to filter results using query parameters. Filtering helps you retrieve only the relevant data for your use case (e.g., transactions within a specific date range or by type). ## Common Filter Parameters | Parameter | Type | Description | | ---------- | ---- | ------------------------------------------------------- | | date\_from | date | Start date for filtering results. Format: `YYYY-MM-DD`. | | date\_to | date | End date for filtering results. Format: `YYYY-MM-DD`. | ## Example Usage **Get all completed outgoing transactions in April 2025** ```http GET /api/v1/transactions ?date_from=2025-04-01 &date_to=2025-04-30 &type=outgoing &status=processed Authorization: Bearer YOUR_API_TOKEN ``` ## Behavior Notes * All filters are **case-sensitive** unless otherwise specified. * Combime multiple filters to narrow down results. * You may receive an HTTP 422 error if you pass invalid or unsupported filters to an endpoint. # Guides # Accounts and customers This page outlines how company accounts and user access are managed within the platform. **Company Account** At Guru Pay, we provide **dedicated accounts**, meaning all accounts are issued under your company's name.\ If you need to open additional accounts, please contact our Client Care team for assistance. #### Customers and User Access Each user with access to the Guru Pay dashboard can be assigned to multiple customers. For example, if you're part of an IT team managing a group of companies, you can oversee all associated customers using a single login. **Note:** * A single customer can have multiple users assigned. * However, only **one user** per customer will have **admin (Main user) rights**, which include permissions to set the Webhook URL and generate an API token. To add new users, please contact our Client Care team at .\ As an account administrator, you're responsible for keeping user access up to date and ensuring permissions remain accurate. # Error codes This page provides a comprehensive list of all possible error codes returned by the API, along with detailed explanations and recommended steps to resolve each issue. | HTTP Code | Message | Description | Action to Take | | --------- | ----------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------ | | 400 | INTERNAL\_SERVER\_ERROR | Unexpected server-side or integration error. | Contact client care team for further assistance. | | 401 | UNAUTHORIZED | Invalid or missing API token. | Contact your account manager or client care team for further assistance. | | 403 | NO\_PERMISSION | Authenticated but not authorized to access the resource. | Contact your account manager or client care team for further assistance. | | 404 | NOT\_FOUND | Resource or endpoint not found. | Check request URL to confirm the endoint you are using is correct. | | 422 | VALIDATION\_ERROR | Request failed input validation. | Validate whether you have entered information correctly. | | 429 | Too Many Attempts. | Rate limit exceeded. | Respect rate limits and try to complete transactions in few minutes. | | 500 | INTERNAL\_SERVER\_ERROR | Unhandled internal error. | Contact client care team for further assistance. | # Transactions This page details how transactions are structured and processed within the platform Transactions have several required fields, along with optional fields that can be added depending on your needs. All transactions that are submitted to Guru Pay are subject to regulatory and sanctions scanning prior to release. As transactions progress through workflow, status changes are automatically communicated through webhooks if configured, or through a manual [Get Transaction ](https://developers.gurupay.eu/api-reference/transactions)request. **Transaction type** All transaction flow is being sent as SEPA INSTANT, in case the beneficiary bank does not accept INSTANT payments, the transaction will be routed via SEPA CT. You will always see the type of transaction via endpoint `/api/v1/transactions/{uuid}` as `"payment_type"` **Cancel transaction** To cancel transaction, please promptly contact your account manager and Client Care team at . # Transaction statuses ⚠️ **Valid from 2025-08-04.** | `created` | transaction is initiated. | Changeable status | | ----------- | ------------------------------------------------------------ | ----------------- | | `pending` | transaction being processed within the system. | Changeable status | | `processed` | transaction released to beneficiary. | Final status | | `cancelled` | transaction was requested to be cancelled by you. | Final status | | `failed` | transaction could not be processed due to technical reasons. | Final status | # Authentication Welcome to the Guru Pay Public API. This section helps you authenticate and make your first successful API request. ## API Keys Guru Pay uses **API Key** authentication via the `Authorization` header. {% hint style="warning" %} Treat your API keys like passwords. Do not share or expose them in client-side code. {% endhint %} ## Header format ``` Authorization: Bearer YOUR_API_KEY ``` Replace `YOUR_API_KEY` with your actual API key, which you can obtain from your Guru Pay Public API dashboard. # Make Your First API Call Let’s make a simple call to fetch the currently authenticated user using your API token. This endpoint requires a valid Bearer token and returns information about your API user. {% hint style="info" %} πŸ“ Endpoint: `GET /api/v1/auth`\ πŸ›‘ Requires Authentication (Bearer token) {% endhint %} ## Request Headers | Header | Required | Example | | --------------- | -------- | ----------------------- | | `Authorization` | βœ… | `Bearer YOUR_API_TOKEN` | | `Accept` | βœ… | `application/json` | ## Example Code {% tabs %} {% tab title="cUrl" %} ```bash curl -X GET https://public-api-dev.gurupay.eu/api/v1/auth \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json" ``` {% endtab %} {% tab title="PHP" %} ```php $client = new \GuzzleHttp\Client(); $response = $client->request('GET', 'https://public-api-dev.gurupay.eu/api/v1/auth', [ 'headers' => [ 'Authorization' => 'Bearer YOUR_API_KEY', 'Accept' => 'application/json', ] ]); echo $response->getBody(); ``` {% endtab %} {% tab title="JavaScript" %} ```javascript fetch("https://public-api.gurupay.eu/api/v1/auth", { headers: { "Authorization": "Bearer YOUR_API_KEY", "Accept": "application/json" } }) .then(response => response.json()) .then(data => console.log(data)); ``` {% endtab %} {% tab title=".NET" %} ```csharp using System; using System.Net.Http; using System.Net.Http.Headers; using System.Threading.Tasks; class Program { static async Task Main() { var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_API_KEY"); client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json")); var response = await client.GetAsync("https://public-api-dev.gurupay.eu/api/v1/auth"); var content = await response.Content.ReadAsStringAsync(); Console.WriteLine(content); } } ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "io" "net/http" ) func main() { client := &http.Client{} req, err := http.NewRequest("GET", "https://public-api-dev.gurupay.eu/api/v1/auth", nil) if err != nil { panic(err) } req.Header.Add("Authorization", "Bearer YOUR_API_KEY") req.Header.Add("Accept", "application/json") res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} # Authentication This endpoint retrieves the authenticated user’s profile based on the API token provided in the request. Use this endpoint to verify the identity of the current user and fetch basic account details. {% hint style="warning" %} You must include your **Bearer token** in the request header. {% endhint %} ## GET /api/v1/auth > Returns data about the currently authenticated user ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Auth","description":"Authentication related endpoints."}],"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.UserResource":{"properties":{"uuid":{"description":"The unique identifier of the user.","type":"string","format":"uuid"},"is_active":{"description":"Indicates if the user is active (0 for inactive, 1 for active).","type":"integer"},"name":{"description":"The full name of the user.","type":"string","maxLength":255},"email":{"description":"The email address of the user.","type":"string","format":"email","maxLength":255},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"}},"type":"object"},"Timestamp":{"description":"A Unix timestamp in seconds.","type":"integer","format":"int64"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"}}},"paths":{"/api/v1/auth":{"get":{"tags":["Auth"],"summary":"Returns data about the currently authenticated user","operationId":"API.Auth","responses":{"200":{"description":"Successfully retrieved User resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.UserResource"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}}}}}}} ``` # Accounts Guru Pay allows you to fetch account information for customers via two endpoints: * One for listing all accounts tied to a specific customer. * One for retrieving detailed data about a single account. {% hint style="warning" %} You must include your **Bearer token** in the request header. {% endhint %} ## Get Customer Accounts List > Retrieves a paginated list of accounts associated with the given customer UUID. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Accounts","description":"Services intended to work with customer accounts."}],"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.AccountResource":{"properties":{"uuid":{"description":"The unique identifier (UUID) of the account.","type":"string","format":"uuid"},"status":{"description":"The current status of the account.","type":"string","enum":["created","disabled"]},"customer_uuid":{"description":"The unique identifier (UUID) of the customer who owns this account.","type":"string","format":"uuid"},"account_name":{"description":"The name associated with the account.","type":"string","nullable":true},"account_number":{"description":"The unique account number.","type":"string"},"currency":{"description":"The currency code of the account","type":"string","enum":["EUR","GBP","USD"]},"opening_date":{"description":"The date when the account was opened (ISO 8601 format).","type":"string","format":"date"},"opening_date_unix":{"$ref":"#/components/schemas/Timestamp"},"balance":{"description":"The current ledger balance of the account.","type":"number","format":"float"},"balance_national":{"description":"The current ledger balance of the account in the national currency.","type":"number","format":"float"},"book_balance":{"description":"The available book balance of the account. **Not used**","type":"number","format":"float"},"book_balance_national":{"description":"The available book balance of the account in the national currency. **Not used**","type":"number","format":"float"},"available_balance":{"description":"The current available balance of the account.","type":"number","format":"float"},"available_balance_national":{"description":"The current available balance of the account in the national currency.","type":"number","format":"float"},"hold":{"description":"The total amount of funds currently on hold in the account's currency. **Not used**","type":"number","format":"float"},"cards_reserved_amount":{"description":"The total amount reserved for card transactions in the account's currency. **Not used**","type":"number","format":"float"},"cards_reserved_amount_national":{"description":"The total amount reserved for card transactions in the national currency. **Not used**","type":"number","format":"float"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"account_type":{"description":"The type of the account.","type":"string","enum":["current","virtual","virtual_parent"]},"virtual_account_holder":{"description":"Details of the virtual account holder, if applicable.","properties":{"name":{"description":"The name of the virtual account holder.","type":"string","nullable":true},"person_type":{"description":"The type of person (e.g., natural, company).","type":"string","nullable":true},"external_id":{"description":"The external ID provided when creating IBAN","type":"string","nullable":true},"citizenship":{"description":"The citizenship of the virtual account holder.","type":"string","nullable":true},"address":{"description":"The address of the virtual account holder.","type":"string","nullable":true},"parent_uuid":{"description":"The uuid of parent account","type":"string","nullable":true},"parent_iban":{"description":"The IBAN of the parent account.","type":"string","nullable":true}},"type":"object","nullable":true}},"type":"object"},"Timestamp":{"description":"A Unix timestamp in seconds.","type":"integer","format":"int64"},"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/customers/{customer_uuid}/accounts":{"get":{"tags":["Accounts"],"summary":"Get Customer Accounts List","description":"Retrieves a paginated list of accounts associated with the given customer UUID.","operationId":"API.Accounts.Get","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"per_page","in":"query","description":"The maximum number of accounts to return per page. Defaults to a predefined value (e.g., 15) if not specified.","required":false,"schema":{"$ref":"#/components/schemas/perPage"}},{"name":"page","in":"query","description":"The page number to retrieve, based on the per_page limit. Starts from 1. Defaults to 1 if not specified.","required":false,"schema":{"$ref":"#/components/schemas/page"}}],"responses":{"200":{"description":"Successful retrieval of customer accounts.","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":{"type":"array","items":{"$ref":"#/components/schemas/API.Resources.AccountResource"}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}} ``` ## Get Specific Account Details > Retrieves the full details for a single account identified by its UUID, scoped to a specific customer. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Accounts","description":"Services intended to work with customer accounts."}],"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.AccountResource":{"properties":{"uuid":{"description":"The unique identifier (UUID) of the account.","type":"string","format":"uuid"},"status":{"description":"The current status of the account.","type":"string","enum":["created","disabled"]},"customer_uuid":{"description":"The unique identifier (UUID) of the customer who owns this account.","type":"string","format":"uuid"},"account_name":{"description":"The name associated with the account.","type":"string","nullable":true},"account_number":{"description":"The unique account number.","type":"string"},"currency":{"description":"The currency code of the account","type":"string","enum":["EUR","GBP","USD"]},"opening_date":{"description":"The date when the account was opened (ISO 8601 format).","type":"string","format":"date"},"opening_date_unix":{"$ref":"#/components/schemas/Timestamp"},"balance":{"description":"The current ledger balance of the account.","type":"number","format":"float"},"balance_national":{"description":"The current ledger balance of the account in the national currency.","type":"number","format":"float"},"book_balance":{"description":"The available book balance of the account. **Not used**","type":"number","format":"float"},"book_balance_national":{"description":"The available book balance of the account in the national currency. **Not used**","type":"number","format":"float"},"available_balance":{"description":"The current available balance of the account.","type":"number","format":"float"},"available_balance_national":{"description":"The current available balance of the account in the national currency.","type":"number","format":"float"},"hold":{"description":"The total amount of funds currently on hold in the account's currency. **Not used**","type":"number","format":"float"},"cards_reserved_amount":{"description":"The total amount reserved for card transactions in the account's currency. **Not used**","type":"number","format":"float"},"cards_reserved_amount_national":{"description":"The total amount reserved for card transactions in the national currency. **Not used**","type":"number","format":"float"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"account_type":{"description":"The type of the account.","type":"string","enum":["current","virtual","virtual_parent"]},"virtual_account_holder":{"description":"Details of the virtual account holder, if applicable.","properties":{"name":{"description":"The name of the virtual account holder.","type":"string","nullable":true},"person_type":{"description":"The type of person (e.g., natural, company).","type":"string","nullable":true},"external_id":{"description":"The external ID provided when creating IBAN","type":"string","nullable":true},"citizenship":{"description":"The citizenship of the virtual account holder.","type":"string","nullable":true},"address":{"description":"The address of the virtual account holder.","type":"string","nullable":true},"parent_uuid":{"description":"The uuid of parent account","type":"string","nullable":true},"parent_iban":{"description":"The IBAN of the parent account.","type":"string","nullable":true}},"type":"object","nullable":true}},"type":"object"},"Timestamp":{"description":"A Unix timestamp in seconds.","type":"integer","format":"int64"},"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/customers/{customer_uuid}/accounts/{account_uuid}":{"get":{"tags":["Accounts"],"summary":"Get Specific Account Details","description":"Retrieves the full details for a single account identified by its UUID, scoped to a specific customer.","operationId":"API.Accounts.Show","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"account_uuid","in":"path","description":"The unique identifier (UUID) of the account to retrieve.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"200":{"description":"Successful retrieval of account details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.AccountResource"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}} ``` # Statements Manages generation and retrieval of account statement resources for a given customer. \ \ Use the **Generate** endpoint to create a statement asynchronously and receive its **UUID**.\ Once processing is complete, the **Get** endpoint can be used to fetch full details including a `file_url` for downloading the report. \ The List endpoint returns a paginated collection of statements for the specified customer and account. ## Get Account Statement Details > Retrieves the full details for a single account statement by its UUID, scoped to a specific customer. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"AccountsStatements","description":"AccountsStatements"}],"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.AccountStatementResource.Details":{"type":"object","allOf":[{"$ref":"#/components/schemas/API.Resources.AccountStatementResource.Base"},{"properties":{"original_name":{"type":"string"},"mime_type":{"type":"string"},"file_url":{"type":"string","format":"uri"}},"type":"object"}]},"API.Resources.AccountStatementResource.Base":{"properties":{"id":{"type":"integer"},"status":{"type":"string"},"type":{"type":"string"},"balance_type":{"type":"string"},"date_from":{"type":"string","format":"date"},"date_to":{"type":"string","format":"date"},"account_id":{"type":"integer"},"account_iban":{"type":"string"},"account_name":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"},"NotFoundResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"}}},"paths":{"/api/v1/customers/{customer_uuid}/accounts/{account_uuid}/statements/{account_statement_uuid}":{"get":{"tags":["AccountsStatements"],"summary":"Get Account Statement Details","description":"Retrieves the full details for a single account statement by its UUID, scoped to a specific customer.","operationId":"API.AccountStatements.Details","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"account_uuid","in":"path","description":"The unique identifier of the account.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"200":{"description":"Successful retrieval of single customer account statement.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/API.Resources.AccountStatementResource.Details"}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}}}}}}} ``` ## List Account Statements > Retrieves a paginated list of accounts statements with the given customer UUID and account ID. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"AccountsStatements","description":"AccountsStatements"}],"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.AccountStatementResource.Base":{"properties":{"id":{"type":"integer"},"status":{"type":"string"},"type":{"type":"string"},"balance_type":{"type":"string"},"date_from":{"type":"string","format":"date"},"date_to":{"type":"string","format":"date"},"account_id":{"type":"integer"},"account_iban":{"type":"string"},"account_name":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"},"NotFoundResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"}}},"paths":{"/api/v1/customers/{customer_uuid}/statements":{"get":{"tags":["AccountsStatements"],"summary":"List Account Statements","description":"Retrieves a paginated list of accounts statements with the given customer UUID and account ID.","operationId":"API.AccountStatements.List","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"account_uuid","in":"path","description":"The unique identifier of the account.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"200":{"description":"Successful retrieval of customer account statements.","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":{"type":"array","items":{"$ref":"#/components/schemas/API.Resources.AccountStatementResource.Base"}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}}}}}}} ``` ## Generate Account Statement > Generate account statement in async way ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"AccountsStatements","description":"AccountsStatements"}],"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.Requests.GenerateAccountStatement":{"title":"Generate Account Statement","description":"Data required to generate an account statement.","required":["type","balance_type","from","to"],"properties":{"type":{"description":"Type of report","type":"string","enum":["csv","pdf","xlsx","xml"]},"balance_type":{"description":"Indicates whether we use available balance or balance (legacy) way to calculate the balance","type":"string","enum":["available_balance","balance"]},"from":{"description":"Start date of the reporting period (YYYY-MM-DD)","type":"string","format":"date"},"to":{"description":"End date of the reporting period (YYYY-MM-DD)","type":"string","format":"date"}},"type":"object"},"API.Resources.IdResource":{"title":"ID Resource","description":"ID from newly created resource","properties":{"id":{"description":"The ID resource which has been created.","type":"string","format":"uuid"}},"type":"object"},"BadRequestResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{}}},"type":"object"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"},"NotFoundResponse":{"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/customers/{customer_uuid}/accounts/{account_uuid}/generate-statement":{"post":{"tags":["AccountsStatements"],"summary":"Generate Account Statement","description":"Generate account statement in async way","operationId":"API.AccountStatements.GenerateStatement","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"account_uuid","in":"path","description":"The unique identifier (UUID) of the account.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"requestBody":{"description":"Account details necessary to close a virtual account","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Requests.GenerateAccountStatement"}}}},"responses":{"201":{"description":"Generating account statement has been initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.IdResource"}}}},"400":{"description":"Max limit transactions per statement reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResponse"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}} ``` # Virtual IBANs ### Introduction A Virtual IBAN (vIBAN) operate as routing identifiers within a two-tier account structure, where master IBANs maintain actual balances while virtual IBANs serve as payment reception endpoints. Incoming payments directed to virtual IBANs are automatically routed to the associated master IBAN. The virtual IBAN reference and associated metadata are preserved throughout the transaction flow and appear in master account statements. Virtual IBANs maintain zero balances and function exclusively for payment reception and routing. To subscribe to the vIBAN product, contact GuruPay client care team at . ### Core Concepts GuruPay implements vIBANs using a two-tier account structure: ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Virtual IBAN A β”‚ Customer ── Virtual IBAN B β”œβ”€β”€β–Ί Master IBAN (real balance) β”‚ Virtual IBAN C β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` * **Master IBAN**\ Holds the actual virtual accounts balance. * **Virtual IBANs**\ Hold *no balance*, serve as routing endpoints, and forward all funds to the master IBAN. All metadata (vIBAN reference, owner information, etc.) is preserved in master account statements. ### vIBAN Capabilities | Feature / Capability | Supported | Notes | | ----------------------------------- | --------- | ------------------------------------------------------------------------ | | Receive payments | βœ” | Payments routed automatically to master IBAN with metadata preserved. | | Send payments β€œfrom” a vIBAN | βœ” | Funds deducted from master IBAN; recipient sees vIBAN sender info. | | Zero-balance vIBAN model | βœ” | vIBANs never hold funds; all balances reside in master account. | | Webhook-based asynchronous creation | βœ” | 201 returned immediately; webhook sent when vIBAN becomes active. | | Echo Service (Sandbox-only) | βœ” | Requires SEPA Instant **only for testing**, not a production capability. | ### Virtual IBAN Creation Before creating vIBANs, you need to identify your master IBAN's UUID. Use the following endpoint to retrieve a list of all accounts. **Endpoint** ``` GET /api/v1/customers/{customer_uuid}/accounts ``` In the response, look for: * `"account_type": "virtual_parent"` * This account’s `"uuid"` is your **master\_account\_uuid.** {% hint style="info" %} More information about retrieving account details can be found in our [Accounts | Documentation](https://developers.gurupay.eu/api-reference/accounts) {% endhint %} vIBAN creation is **asynchronous**: 1. API returns `201 Created` immediately with a status `WAITING_FOR_APPROVAL`. 2. Requests are approved automatically by default. In some cases, additional compliance checks may be required, and the request may be placed in a review queue. 3. Once virtual account creation or review is completed, the webhook sends the final status `CREATED` or `REJECTED` 4. When the new virtual account is created, the webhook will contain new vIBAN details. {% content-ref url="/pages/odVIQK6RkDj7TsZzLSNR" %} [Account Event](/webhooks/events/account-event) {% endcontent-ref %} {% hint style="warning" %} **Important:** Set up webhook handling to receive the account creation confirmation. {% endhint %} ## Create virtual account > Create new virtual account ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Accounts","description":"Services intended to work with customer accounts."}],"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.Requests.CreateVirtualAccount":{"title":"Create virtual account request","description":"Data required to create a new virtual account.","required":["master_account_uuid","person_type","address"],"properties":{"master_account_uuid":{"description":"The UUID of the master account.","type":"string","format":"uuid"},"person_type":{"description":"Person legal type: legal or natural","type":"string","enum":["legal","natural"]},"external_id":{"description":"External ID to be used to track virtual IBAN","type":"string","maxLength":70},"person":{"description":"Person details. Required if person type is natural","properties":{"first_name":{"description":"Account holder name.","type":"string","maxLength":35},"last_name":{"description":"Account holder last name.","type":"string","maxLength":35},"date_of_birth":{"description":"Account holder date of birth.","type":"string"},"citizenship":{"description":"Country code of citizenship","type":"string","maxLength":2,"minLength":2},"address":{"description":"Residency address details.","required":["line","city","country","postal_code"],"properties":{"line":{"description":"Address line.","type":"string","maxLength":70},"city":{"description":"City.","type":"string","maxLength":35},"country":{"description":"Country code.","type":"string","maxLength":2,"minLength":2},"postal_code":{"description":"Postal code.","type":"string","maxLength":16}},"type":"object"}},"type":"object"},"company":{"description":"Company details. Required if person type is legal","properties":{"company_name":{"description":"Company name.","type":"string","maxLength":70},"registration_code":{"description":"Company registration code","type":"string"},"industry_type":{"description":"Industry type identifier.","oneOf":[{"description":"Luxury Goods","type":"integer","enum":[1]},{"description":"Agriculture","type":"integer","enum":[2]},{"description":"Commerce","type":"integer","enum":[3]},{"description":"Construction & Real Estate","type":"integer","enum":[4]},{"description":"Financial & Professional Services","type":"integer","enum":[5]},{"description":"Hospitality & Tourism","type":"integer","enum":[6]},{"description":"Mining","type":"integer","enum":[7]},{"description":"Media, Marketing & IT","type":"integer","enum":[8]},{"description":"Oil & Gas","type":"integer","enum":[9]},{"description":"Postal & Telecommunications","type":"integer","enum":[10]},{"description":"Education & Public Service","type":"integer","enum":[11]},{"description":"Shipping & Logistics","type":"integer","enum":[12]},{"description":"Financial Activities","type":"integer","enum":[13]},{"description":"Gambling & Betting","type":"integer","enum":[14]},{"description":"Investment Dealers","type":"integer","enum":[15]},{"description":"Virtual Currency","type":"integer","enum":[16]},{"description":"Natural Person","type":"integer","enum":[17]},{"description":"Accumulation Account","type":"integer","enum":[18]},{"description":"Foundation / Trust","type":"integer","enum":[19]},{"description":"Holding Company","type":"integer","enum":[20]}]},"address":{"description":"Registration address details.","required":["line","city","country","postal_code"],"properties":{"line":{"description":"Address line.","type":"string","maxLength":70},"city":{"description":"City.","type":"string","maxLength":35},"country":{"description":"Country code.","type":"string","maxLength":2,"minLength":2},"postal_code":{"description":"Postal code.","type":"string","maxLength":16}},"type":"object"}},"type":"object"}},"type":"object"},"API.Resources.VirtualAccountCreateResponse":{"title":"Virtual Account Create Response","description":"Response returned after a virtual IBAN creation request is accepted by Public API.","required":["uuid","status"],"properties":{"uuid":{"description":"Public API UUID of the virtual account request. This UUID is later reused in webhook payloads and, after approval, becomes the Public API account UUID.","type":"string","format":"uuid"},"status":{"description":"Initial Public API status of the virtual account request.","type":"string","enum":["WAITING_FOR_APPROVAL","ACTIVE","REJECTED"]}},"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/customers/{customer_uuid}/accounts/open/virtual":{"post":{"tags":["Accounts"],"summary":"Create virtual account","description":"Create new virtual account","operationId":"API.Accounts.CreateVirtual","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"requestBody":{"description":"Account details necessary to create a virtual account","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Requests.CreateVirtualAccount"}}}},"responses":{"201":{"description":"Virtual account creation has been initiated. Returns the Public API UUID and initial request status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.VirtualAccountCreateResponse"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}} ``` ### Retrieve Virtual IBAN Details Retrieve full information about your newly created vIBAN so you can begin receiving payments, initiating outgoing transfers, and managing the account lifecycle. **Endpoint** ``` GET /api/v1/customers/{customer_uuid}/accounts ``` The response will list all your accounts. Look for: * `"account_type": "virtual"` * `"status": "created"` * `"iban"` β€” share with customers. * `"uuid"` β€” store for management. * `parent_uuid` β€” links to your master account. {% hint style="info" %} More information about retrieving account details can be found in our [Accounts | Documentation](https://developers.gurupay.eu/api-reference/accounts) {% endhint %} ### Receiving Payments Once your vIBAN is active, payments work automatically: 1. **Customer sends payment** to your vIBAN. 2. **GuruPay routes payment** to your master IBAN instantly. 3. **Balance** always shows 0.00 as funds route to your master IBAN balance. 4. **Transaction details** include vIBAN reference for easy identification. {% hint style="info" %} For more details regarding receiving payment, refer to [Webhook Messages | Documentation](https://developers.gurupay.eu/api-reference/webhook-messages) and [Transactions | Documentation](https://developers.gurupay.eu/getting-started/guides/transactions) {% endhint %} ### Sending Payments You can initiate outgoing payments directly from your vIBANs using the GuruPay API. When you send a payment from a vIBAN, the funds are deducted from your master account while the payment appears to originate from the vIBAN. **Endpoint** ``` POST /api/v1/transactions ``` **Payment Flow:** 1. You initiate a payment using vIBAN as the sender. 2. Funds are deducted from the linked master account balance. 3. Payment is sent with vIBAN owner information as the sender. 4. Recipient sees the vIBAN details (not your master account). {% hint style="info" %} The payment initiation process follows the same structure as standard payment initiation in the GuruPay API. Refer to the public API documentation for detailed endpoint specifications and request parameters. More information can be found at [Transactions | Documentation](https://developers.gurupay.eu/api-reference/transactions#post-api-v1-transactions) {% endhint %} **Key Parameters:** * **Sender Account:** Use your vIBAN UUID. * **Funds Source:** Automatically deducted from master account. * **Sender Information:** vIBAN owner details (as registered).
## Update virtual account > Fully updates the resource by replacing the existing data with the provided request body.\ > All required fields must be provided, as missing values may be overwritten or cleared. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Accounts","description":"Services intended to work with customer accounts."}],"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.Requests.UpdateVirtual":{"title":"Update virtual account metadata","description":"Data required to update a virtual account.","required":["virtual_account_uuid","person_type","address"],"properties":{"virtual_account_uuid":{"description":"The UUID of the virtual account to update.","type":"string","format":"uuid"},"person_type":{"description":"Person legal type: legal or natural","type":"string","enum":["legal","natural"]},"external_id":{"description":"External ID to be used to track virtual IBAN","type":"string","maxLength":70},"person":{"description":"Person details. Required if person type is natural","properties":{"first_name":{"description":"Account holder name.","type":"string","maxLength":35},"last_name":{"description":"Account holder last name.","type":"string","maxLength":35},"citizenship":{"description":"Country code of citizenship","type":"string","maxLength":2,"minLength":2},"address":{"description":"Residency address details.","required":["line","city","country","postal_code"],"properties":{"line":{"description":"Address line.","type":"string","maxLength":70},"building_number":{"description":"Building number.","type":"string","maxLength":16},"city":{"description":"City.","type":"string","maxLength":35},"country":{"description":"Country code.","type":"string","maxLength":2,"minLength":2},"postal_code":{"description":"Postal code.","type":"string","maxLength":16}},"type":"object"}},"type":"object"},"company":{"description":"Company details. Required if person type is legal","properties":{"company_name":{"description":"Company name.","type":"string","maxLength":70},"industry_type":{"description":"Industry type identifier.","oneOf":[{"description":"Luxury Goods","type":"integer","enum":[1]},{"description":"Agriculture","type":"integer","enum":[2]},{"description":"Commerce","type":"integer","enum":[3]},{"description":"Construction & Real Estate","type":"integer","enum":[4]},{"description":"Financial & Professional Services","type":"integer","enum":[5]},{"description":"Hospitality & Tourism","type":"integer","enum":[6]},{"description":"Mining","type":"integer","enum":[7]},{"description":"Media, Marketing & IT","type":"integer","enum":[8]},{"description":"Oil & Gas","type":"integer","enum":[9]},{"description":"Postal & Telecommunications","type":"integer","enum":[10]},{"description":"Education & Public Service","type":"integer","enum":[11]},{"description":"Shipping & Logistics","type":"integer","enum":[12]},{"description":"Financial Activities","type":"integer","enum":[13]},{"description":"Gambling & Betting","type":"integer","enum":[14]},{"description":"Investment Dealers","type":"integer","enum":[15]},{"description":"Virtual Currency","type":"integer","enum":[16]},{"description":"Natural Person","type":"integer","enum":[17]},{"description":"Accumulation Account","type":"integer","enum":[18]},{"description":"Foundation / Trust","type":"integer","enum":[19]},{"description":"Holding Company","type":"integer","enum":[20]}]},"address":{"description":"Registration address details.","required":["line","city","country","postal_code"],"properties":{"line":{"description":"Address line.","type":"string","maxLength":70},"building_number":{"description":"Building number.","type":"string","maxLength":16},"city":{"description":"City.","type":"string","maxLength":35},"country":{"description":"Country code.","type":"string","maxLength":2,"minLength":2},"postal_code":{"description":"Postal code.","type":"string","maxLength":16}},"type":"object"}},"type":"object"}},"type":"object"},"NotFoundResponse":{"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/customers/{customer_uuid}/accounts/update/virtual":{"put":{"tags":["Accounts"],"summary":"Update virtual account","description":"Fully updates the resource by replacing the existing data with the provided request body.\nAll required fields must be provided, as missing values may be overwritten or cleared.","operationId":"API.Accounts.UpdateVirtual","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"requestBody":{"description":"Account details necessary to update a virtual account","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Requests.UpdateVirtual"}}}},"responses":{"204":{"description":"Virtual account has been updated."},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}} ``` ### Blocking Virtual IBAN Blocking a virtual IBAN places it into a non-operational state. When a vIBAN is blocked, its status is set to `disabled`. Blocking applies as a full block, and all incoming and outgoing payments to the vIBAN are rejected, as the IBAN is blocked. Blocked vIBANs remain visible and are returned in GET IBAN details endpoints. ## Block virtual account > Block virtual account ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Accounts","description":"Services intended to work with customer accounts."}],"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.Requests.BlockVirtualAccount":{"title":"Block virtual account request","description":"Data required to block virtual account.","required":["master_account_uuid","name","person_type","address"],"properties":{"virtual_account_uuid":{"description":"The UUID of the virtual account.","type":"string","format":"uuid"}},"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"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"}}},"paths":{"/api/v1/customers/{customer_uuid}/accounts/block/virtual":{"post":{"tags":["Accounts"],"summary":"Block virtual account","description":"Block virtual account","operationId":"API.Accounts.BlockVirtual","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"requestBody":{"description":"Account details necessary to block a virtual account","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Requests.BlockVirtualAccount"}}}},"responses":{"200":{"description":"Block virtual account has been initiated."},"400":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}}}}}}} ``` ### Unblocking Virtual IBAN Unblocking a virtual IBAN returns it to an operational state. When a vIBAN is unblocked, its status is set to `created` .The vIBAN becomes fully operational, and all incoming and outgoing payment operations function normally. API users can only unblock vIBANs that they previously blocked themselves. vIBANs blocked by other parties cannot be unblocked via the API. ## Unblock a virtual account > Unblock a virtual account ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Accounts","description":"Services intended to work with customer accounts."}],"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.Requests.UnblockVirtualAccount":{"title":"Unblock virtual account request","description":"Data required to unblock virtual account.","required":["master_account_uuid","name","person_type","address"],"properties":{"virtual_account_uuid":{"description":"The UUID of the virtual account.","type":"string","format":"uuid"}},"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"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"}}},"paths":{"/api/v1/customers/{customer_uuid}/accounts/unblock/virtual":{"post":{"tags":["Accounts"],"summary":"Unblock a virtual account","description":"Unblock a virtual account","operationId":"API.Accounts.UnblockVirtual","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"requestBody":{"description":"Account details necessary to unblock a virtual account","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Requests.UnblockVirtualAccount"}}}},"responses":{"200":{"description":"Unblock virtual account has been initiated."},"400":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}}}}}}} ``` ### Closing Virtual IBAN When you request to close a vIBAN, the API immediately returns a **201 Accepted** response while the closure is processed asynchronously. Once closed, the vIBAN stops accepting incoming payments, and any future transfers to it will be rejected. The vIBAN cannot be reactivated, but all historical transaction data remains available for reporting and reconciliation. {% hint style="warning" %} **Warning:** Once closed, the vIBAN cannot be reactivated. Create a new one if needed. {% endhint %} ## Close virtual account > Close virtual account ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Accounts","description":"Services intended to work with customer accounts."}],"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.Requests.CloseVirtualAccount":{"title":"Close virtual account request","description":"Data required to close virtual account.","required":["master_account_uuid","name","person_type","address"],"properties":{"virtual_account_uuid":{"description":"The UUID of the virtual account.","type":"string","format":"uuid"}},"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/customers/{customer_uuid}/accounts/close/virtual":{"post":{"tags":["Accounts"],"summary":"Close virtual account","description":"Close virtual account","operationId":"API.Accounts.CloseVirtual","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"requestBody":{"description":"Account details necessary to close a virtual account","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Requests.CloseVirtualAccount"}}}},"responses":{"201":{"description":"Close virtual account has been initiated."},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}} ``` ## Upload virtual IBAN document > Upload virtual IBAN document ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Documents","description":"Documents"}],"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.Requests.UploadDocument":{"title":"Virtual Account upload document","description":"Data required to upload a document to a virtual account.","required":["type","file_name","attachment"],"properties":{"type":{"description":"Document type","type":"string","enum":["registration_document","vat_document","proof_of_ownership","proof_of_industry","identity_card","drivers_license","passport","residence_permit","proof_of_residence","proof_of_address","other"]},"description":{"description":"Description","type":"string"},"file_name":{"description":"Original filename","type":"string"},"attachment":{"required":["content"],"properties":{"content":{"description":"Base64 encoded file content","type":"string","format":"byte"},"page_type":{"description":"Page side of the document (required for identity_card and drivers_license)","type":"string","enum":["front","back"],"nullable":true}},"type":"object"}},"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"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"}}},"paths":{"/api/v1/customers/{customer_uuid}/accounts/{account_uuid}/documents":{"post":{"tags":["Documents"],"summary":"Upload virtual IBAN document","description":"Upload virtual IBAN document","operationId":"API.Documents.Upload","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"account_uuid","in":"path","description":"The unique identifier (UUID) of the virtual account.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"requestBody":{"description":"Document upload payload","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Requests.UploadDocument"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"404":{"description":"Virtual IBAN not found."},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}} ``` ### Verification of Payee (VoP) Support vIBANs are fully compatible with Verification of Payee checks. When your vIBAN is created, GuruPay registers it with the European Payments Council (EPC) database using dual ownership information: * **Your details** (as the account client). * **Virtual owner details** (as provided during creation). This dual registration ensures that when someone initiates a payment to your vIBAN, the VoP verification will return a `MATCH` response regardless of whether the sender uses: * Your company information. * The virtual owner information you specified. {% hint style="info" %} If sender details contain typos or misspellings of either ownership information, standard VoP matching rules apply and may result in partial matches or no matches. For complete VoP guidance, refer to the European Payments Council documentation: [Verification Of Payee](https://www.europeanpaymentscouncil.eu/what-we-do/other-schemes/verification-payee) and [EPC recommendations for the matching processes under the Verification Of Payee scheme rulebook](https://www.europeanpaymentscouncil.eu/document-library/other/epc-recommendations-matching-processes-under-verification-payee-scheme) {% endhint %} # Document Operations ### Introduction This section covers how to upload, list, retrieve, and delete documents associated with a virtual IBAN account. Use the the folowing endpoints when you need to: * upload and documents associated with a customer account * review which documents have already been submitted * retrieve details for a specific document * remove a document that was uploaded incorrectly or is no longer needed ## Upload virtual IBAN document > Upload virtual IBAN document ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Documents","description":"Documents"}],"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.Requests.UploadDocument":{"title":"Virtual Account upload document","description":"Data required to upload a document to a virtual account.","required":["type","file_name","attachment"],"properties":{"type":{"description":"Document type","type":"string","enum":["registration_document","vat_document","proof_of_ownership","proof_of_industry","identity_card","drivers_license","passport","residence_permit","proof_of_residence","proof_of_address","other"]},"description":{"description":"Description","type":"string"},"file_name":{"description":"Original filename","type":"string"},"attachment":{"required":["content"],"properties":{"content":{"description":"Base64 encoded file content","type":"string","format":"byte"},"page_type":{"description":"Page side of the document (required for identity_card and drivers_license)","type":"string","enum":["front","back"],"nullable":true}},"type":"object"}},"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"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"}}},"paths":{"/api/v1/customers/{customer_uuid}/accounts/{account_uuid}/documents":{"post":{"tags":["Documents"],"summary":"Upload virtual IBAN document","description":"Upload virtual IBAN document","operationId":"API.Documents.Upload","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"account_uuid","in":"path","description":"The unique identifier (UUID) of the virtual account.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"requestBody":{"description":"Document upload payload","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Requests.UploadDocument"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"404":{"description":"Virtual IBAN not found."},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}} ``` ## Get Documents List > Get a paginated list of documents associated with the given customer UUID and account ID. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Documents","description":"Documents"}],"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.DocumentResource":{"properties":{"uuid":{"description":"The unique identifier (UUID) of the document.","type":"string","format":"uuid"},"type":{"description":"The type of the document.","type":"string","enum":["registration_document","vat_document","proof_of_ownership","proof_of_industry","identity_card","drivers_license","passport","residence_permit","proof_of_residence","proof_of_address","other"]},"file_name":{"description":"The original filename of the uploaded document.","type":"string"},"description":{"description":"Description of the document.","type":"string"},"page_type":{"description":"Page side of the document (available for identity_card and drivers_license)","type":"string","enum":["front","back"],"nullable":true},"created_at":{"description":"The timestamp when the document was created.","type":"string","format":"date-time"},"status":{"description":"Status of the document","type":"string","enum":["pending","uploaded","rejected"]}},"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/customers/{customer_uuid}/accounts/{account_uuid}/documents":{"get":{"tags":["Documents"],"summary":"Get Documents List","description":"Get a paginated list of documents associated with the given customer UUID and account ID.","operationId":"API.Documents.List","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"account_uuid","in":"path","description":"The unique identifier (UUID) of the account.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"type","in":"query","description":"Optional document type filter.","required":false,"schema":{"type":"string","enum":["registration_document","vat_document","proof_of_ownership","proof_of_industry","identity_card","drivers_license","passport","residence_permit","proof_of_residence","proof_of_address","other"]}},{"name":"filename","in":"query","description":"Optional document filename filter.","required":false,"schema":{"type":"string"}},{"name":"per_page","in":"query","description":"Number of messages 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":"sort","in":"query","description":"Field to sort the documents list by.","required":false,"schema":{"type":"string","default":"created_at","enum":["id","original_name","type","created_at"]}},{"name":"direction","in":"query","description":"Sort direction for the message list.","required":false,"schema":{"type":"string","default":"desc","enum":["asc","desc"]}}],"responses":{"200":{"description":"Successful retrieval of documents.","headers":{"X-Total-Count":{"description":"Total number of records matching the filter criteria.","schema":{"type":"integer"}},"X-Offset":{"description":"Current pagination offset.","schema":{"type":"integer"}},"X-Limit":{"description":"Current pagination limit.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/API.Resources.DocumentResource"}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"404":{"description":"Document not found."},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}} ``` ## Get Document Details > Retrieves the details of a specific document by its UUID. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Documents","description":"Documents"}],"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.DocumentResource":{"properties":{"uuid":{"description":"The unique identifier (UUID) of the document.","type":"string","format":"uuid"},"type":{"description":"The type of the document.","type":"string","enum":["registration_document","vat_document","proof_of_ownership","proof_of_industry","identity_card","drivers_license","passport","residence_permit","proof_of_residence","proof_of_address","other"]},"file_name":{"description":"The original filename of the uploaded document.","type":"string"},"description":{"description":"Description of the document.","type":"string"},"page_type":{"description":"Page side of the document (available for identity_card and drivers_license)","type":"string","enum":["front","back"],"nullable":true},"created_at":{"description":"The timestamp when the document was created.","type":"string","format":"date-time"},"status":{"description":"Status of the document","type":"string","enum":["pending","uploaded","rejected"]}},"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/customers/{customer_uuid}/accounts/{account_uuid}/documents/{document_uuid}":{"get":{"tags":["Documents"],"summary":"Get Document Details","description":"Retrieves the details of a specific document by its UUID.","operationId":"API.Documents.Show","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"account_uuid","in":"path","description":"The unique identifier (UUID) of the account.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"document_uuid","in":"path","description":"The unique identifier (UUID) of the document to retrieve.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"200":{"description":"Successful retrieval of document details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.DocumentResource"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"404":{"description":"Document not found."},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}} ``` ## Delete Document > Deletes a specific document by its UUID. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Documents","description":"Documents"}],"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}$"},"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/customers/{customer_uuid}/accounts/{account_uuid}/documents/{document_uuid}":{"delete":{"tags":["Documents"],"summary":"Delete Document","description":"Deletes a specific document by its UUID.","operationId":"API.Documents.Destroy","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"account_uuid","in":"path","description":"The unique identifier (UUID) of the account.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"document_uuid","in":"path","description":"The unique identifier (UUID) of the document to delete.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"204":{"description":"Document successfully deleted."},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"404":{"description":"Document not found."},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}} ``` # Virtual IBAN balance reporting ## Introduction All customers subscribed to virtual IBANs product must report an actual balance of vIBAN on demand. To automate such queries customers must provide an API endpoint that will be called by GuruPay systems. GuruPay system will issue a `GET` HTTP request to provided URL. `Authorization` header will be sent with customer generated API token. Endpoint is expected to return vIBAN balance as an `integer` in cents. ## Expected response specification `GET` `https:///:iban` **Headers** | Name | Value | | ------------- | ------------------ | | Content-Type | `application/json` | | Authorization | `Bearer ` | **Path parameters** | Name | Type | Description | | ------ | ------ | --------------------- | | `iban` | string | vIBAN. e.g. LT0034001 | **Response** {% tabs %} {% tab title="200" %} ```json { "balance": 5500 } ``` {% endtab %} {% tab title="400" %} ```json { "error": "Invalid request" } ``` {% endtab %} {% endtabs %} # Customers The Customers API allows you to retrieve customer records linked to your integration via two endpoints: * One for retrieving details for a specific customer. * One for retrieving a paginated list of customers. {% hint style="warning" %} You must include your **Bearer token** in the request header. {% endhint %} ## Retrieve a paginated list of customers > Returns a list of customers, paginated according to the 'per\_page' and 'page' query parameters. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Customers","description":"Services intended to work with customer data."}],"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":{"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.CustomerResource":{"properties":{"uuid":{"description":"The customer's unique identifier.","type":"string","format":"uuid"},"identity_uuid":{"description":"The unique identifier of the associated identity","type":"string","format":"uuid"},"type":{"description":"The category of customer (e.g., individual, company).","type":"string","enum":["individual","company"]},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"name":{"description":"The full name of the customer.","type":"string","maxLength":255},"risk_country_code":{"description":"The country code indicating the customer's risk level. **Not used**","type":"null"},"registration_country_code":{"description":"The country code where the company is officially registered.","type":"string","maxLength":2,"nullable":true},"registration_address_line":{"description":"The main street address for the company's official registration.","type":"string","maxLength":255,"nullable":true},"registration_address_index":{"description":"The postal code or zip code for the company's official registration address.","type":"string","maxLength":20,"nullable":true},"post_address_country_code":{"description":"The country code where the company is physically located.","type":"string","maxLength":2,"nullable":true},"post_address_line":{"description":"The main street address for the company's physical location.","type":"string","maxLength":255,"nullable":true},"post_address_index":{"description":"The postal code or zip code for the company's physical location.","type":"string","maxLength":20,"nullable":true},"related_persons":{"description":"Information about individuals associated with this customer. **Not used**","type":"null"}},"type":"object"},"Timestamp":{"description":"A Unix timestamp in seconds.","type":"integer","format":"int64"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"}}},"paths":{"/api/v1/customers":{"get":{"tags":["Customers"],"summary":"Retrieve a paginated list of customers","description":"Returns a list of customers, paginated according to the 'per_page' and 'page' query parameters.","operationId":"API.Customers.Get","parameters":[{"parameter":"per_page","name":"per_page","in":"query","description":"Number of items to return per page","schema":{"$ref":"#/components/schemas/perPage"}},{"parameter":"page","name":"page","in":"query","description":"The page number to retrieve","schema":{"$ref":"#/components/schemas/page"}}],"responses":{"200":{"description":"A paginated array of customer resources","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":{"type":"array","items":{"$ref":"#/components/schemas/API.Resources.CustomerResource"}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}}}}}}} ``` ## Retrieve details for a specific customer > Returns comprehensive information about a customer identified by their unique UUID. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Customers","description":"Services intended to work with customer data."}],"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.CustomerResource":{"properties":{"uuid":{"description":"The customer's unique identifier.","type":"string","format":"uuid"},"identity_uuid":{"description":"The unique identifier of the associated identity","type":"string","format":"uuid"},"type":{"description":"The category of customer (e.g., individual, company).","type":"string","enum":["individual","company"]},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"name":{"description":"The full name of the customer.","type":"string","maxLength":255},"risk_country_code":{"description":"The country code indicating the customer's risk level. **Not used**","type":"null"},"registration_country_code":{"description":"The country code where the company is officially registered.","type":"string","maxLength":2,"nullable":true},"registration_address_line":{"description":"The main street address for the company's official registration.","type":"string","maxLength":255,"nullable":true},"registration_address_index":{"description":"The postal code or zip code for the company's official registration address.","type":"string","maxLength":20,"nullable":true},"post_address_country_code":{"description":"The country code where the company is physically located.","type":"string","maxLength":2,"nullable":true},"post_address_line":{"description":"The main street address for the company's physical location.","type":"string","maxLength":255,"nullable":true},"post_address_index":{"description":"The postal code or zip code for the company's physical location.","type":"string","maxLength":20,"nullable":true},"related_persons":{"description":"Information about individuals associated with this customer. **Not used**","type":"null"}},"type":"object"},"Timestamp":{"description":"A Unix timestamp in seconds.","type":"integer","format":"int64"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"},"NotFoundResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"}}},"paths":{"/api/v1/customers/{uuid}":{"get":{"tags":["Customers"],"summary":"Retrieve details for a specific customer","description":"Returns comprehensive information about a customer identified by their unique UUID.","operationId":"API.Customers.Show","parameters":[{"parameter":"uuid","name":"uuid","in":"path","description":"The unique identifier (UUID) of the customer to retrieve.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"200":{"description":"Detailed information about the requested customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.CustomerResource"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}}}}}}} ``` # 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.3.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.3.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) {% 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.3.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.3.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 %} # Webhooks Webhooks allow your system to receive real-time notifications from Guru Pay when specific events occur (transaction processing completed, new transaction is created, etc.). You can manage your webhook configuration using the following endpoints. {% hint style="warning" %} You must include your **Bearer token** in the request header. {% endhint %} ## Create webhook configuration > Creates a new webhook configuration for the authenticated user. The same webhook configuration is used for outbound account, transaction, and virtual IBAN status-change events. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Webhooks","description":"Managing webhook configurations."}],"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.Requests.CreateWebhookRequest":{"title":"Create Webhook Request Body","description":"Data required to create a new webhook configuration.","required":["url","token"],"properties":{"url":{"description":"The target URL endpoint for the webhook messages.","type":"string","format":"url","maxLength":255},"token":{"description":"A secret token sent with webhook messages for verification (e.g., in an 'Authorization' or custom header). Min 16, Max 100 characters.","type":"string","format":"password","maxLength":100,"minLength":16},"name":{"description":"A user-friendly name for the webhook configuration.","type":"string","maxLength":255,"nullable":true},"description":{"description":"An optional description for the webhook configuration.","type":"string","maxLength":500,"nullable":true}},"type":"object"},"API.Resources.WebhookResource":{"title":"Webhook Resource","description":"Resource representing a configured webhook subscription.","properties":{"uuid":{"description":"Unique identifier for the webhook configuration.","type":"string","format":"uuid"},"is_active":{"description":"Indicates whether the webhook subscription is currently active and sending events.","type":"boolean"},"url":{"description":"The URL endpoint where webhook messages will be delivered.","type":"string","format":"url"},"token":{"description":"The secret token used to verify webhook authenticity. Usually masked or omitted in read operations for security.","type":"string"},"name":{"description":"A user-defined name for the webhook configuration.","type":"string","nullable":true},"description":{"description":"An optional description for the webhook configuration.","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/webhooks":{"post":{"tags":["Webhooks"],"summary":"Create webhook configuration","description":"Creates a new webhook configuration for the authenticated user. The same webhook configuration is used for outbound account, transaction, and virtual IBAN status-change events.","operationId":"API.Webhooks.Create","requestBody":{"description":"Webhook details necessary to create a transaction","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Requests.CreateWebhookRequest"}}}},"responses":{"201":{"description":"Webhook configuration created successfully. Returns the created resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.WebhookResource"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}} ``` ## Show current webhook configuration > Shows the webhook configuration associated with the authenticated account/user. This configuration is used for outbound account, transaction, and virtual IBAN status-change events. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Webhooks","description":"Managing webhook configurations."}],"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.WebhookResource":{"title":"Webhook Resource","description":"Resource representing a configured webhook subscription.","properties":{"uuid":{"description":"Unique identifier for the webhook configuration.","type":"string","format":"uuid"},"is_active":{"description":"Indicates whether the webhook subscription is currently active and sending events.","type":"boolean"},"url":{"description":"The URL endpoint where webhook messages will be delivered.","type":"string","format":"url"},"token":{"description":"The secret token used to verify webhook authenticity. Usually masked or omitted in read operations for security.","type":"string"},"name":{"description":"A user-defined name for the webhook configuration.","type":"string","nullable":true},"description":{"description":"An optional description for the webhook configuration.","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"}}},"paths":{"/api/v1/webhooks":{"get":{"tags":["Webhooks"],"summary":"Show current webhook configuration","description":"Shows the webhook configuration associated with the authenticated account/user. This configuration is used for outbound account, transaction, and virtual IBAN status-change events.","operationId":"API.Webhooks.Show","responses":{"200":{"description":"Successfully retrieved the webhook configuration details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.WebhookResource"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}}}}}}} ``` ## Update current webhook configuration > Updates the webhook configuration associated with the authenticated user. The same webhook configuration is used for outbound account, transaction, and virtual IBAN status-change events. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"Webhooks","description":"Managing webhook configurations."}],"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.Requests.UpdateWebhookRequest":{"title":"Update Webhook Request Body","description":"Data required to update an existing webhook configuration. All fields are typically required for PUT/replace semantics, but PATCH might allow partial updates (adjust schema 'required' if using PATCH).","required":["is_active","url","token"],"properties":{"is_active":{"description":"Whether the webhook subscription should be active.","type":"boolean"},"url":{"description":"The target URL endpoint for the webhook messages.","type":"string","format":"url","maxLength":255},"token":{"description":"A secret token sent with webhook messages for verification. Min 16, Max 100 characters.","type":"string","format":"password","maxLength":100,"minLength":16},"name":{"description":"A user-friendly name for the webhook configuration.","type":"string","maxLength":255,"nullable":true},"description":{"description":"An optional description for the webhook configuration.","type":"string","maxLength":500,"nullable":true}},"type":"object"},"API.Resources.WebhookResource":{"title":"Webhook Resource","description":"Resource representing a configured webhook subscription.","properties":{"uuid":{"description":"Unique identifier for the webhook configuration.","type":"string","format":"uuid"},"is_active":{"description":"Indicates whether the webhook subscription is currently active and sending events.","type":"boolean"},"url":{"description":"The URL endpoint where webhook messages will be delivered.","type":"string","format":"url"},"token":{"description":"The secret token used to verify webhook authenticity. Usually masked or omitted in read operations for security.","type":"string"},"name":{"description":"A user-defined name for the webhook configuration.","type":"string","nullable":true},"description":{"description":"An optional description for the webhook configuration.","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/webhooks":{"put":{"tags":["Webhooks"],"summary":"Update current webhook configuration","description":"Updates the webhook configuration associated with the authenticated user. The same webhook configuration is used for outbound account, transaction, and virtual IBAN status-change events.","operationId":"API.Webhooks.Update","requestBody":{"description":"Webhook details necessary to update a transaction","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Requests.UpdateWebhookRequest"}}}},"responses":{"200":{"description":"Webhook configuration updated successfully. Returns the updated resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.WebhookResource"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}} ``` ### Response requirements for webhook services \ When GuruPay sends a webhook message to the configured `url`, the customer’s webhook service must respond with HTTP status code `202 Accepted`.\ Otherwise, the delivery attempt may be treated as unsuccessful, and the webhook message will be retried until a successful `202 Accepted` response is received. # Webhook Messages The Webhook Messages API allows you to inspect and manage individual webhook delivery attempts. This is useful for debugging webhook issues. {% hint style="warning" %} You must include your **Bearer token** in the request header. {% endhint %} ## Get Webhook Messages > Retrieves a paginated list of webhook messages, optionally filtered by date range and status. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"WebhookMessages","description":"Viewing and managing webhook delivery messages/logs."}],"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":{"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.WebhookMessageResource":{"title":"Webhook Message Resource","description":"Resource representing the data structure of a webhook message.","properties":{"uuid":{"description":"Unique identifier for the webhook message.","type":"string","format":"uuid"},"created_at":{"description":"Timestamp when the webhook message was created.","type":"integer","format":"int64"},"status":{"description":"Delivery status of the webhook message.","type":"string","enum":["delivered","processing","error","retry"]},"account_uuid":{"description":"UUID of the account associated with the event that triggered the webhook.","type":"string","format":"uuid","nullable":true},"account":{"oneOf":[{"$ref":"#/components/schemas/API.Resources.AccountSimpleResource"}],"nullable":true,"description":"Simplified details of the account associated with the event. Included based on webhook configuration."},"transaction":{"oneOf":[{"$ref":"#/components/schemas/API.Resources.TransactionResource"}],"nullable":true,"description":"Details of the transaction associated with the event. Included for transaction-related webhooks."}},"type":"object"},"API.Resources.AccountSimpleResource":{"title":"Account Simple Resource","description":"Simplified resource representing key account details like UUID, number, currency, and balances.","required":["uuid","account_number","currency","balance","available_balance"],"properties":{"uuid":{"description":"Unique identifier for the account.","type":"string","format":"uuid"},"account_number":{"description":"The unique account number.","type":"string"},"currency":{"description":"The currency code of the account","type":"string","enum":["EUR","GBP","USD"]},"balance":{"description":"The current ledger balance of the account.","type":"number","format":"float"},"balance_national":{"description":"The current ledger balance of the account in the national currency.","type":"number","format":"float"},"book_balance":{"description":"The available book balance of the account. **Not used**","type":"number","format":"float"},"book_balance_national":{"description":"The available book balance of the account in the national currency. **Not used**","type":"number","format":"float"},"available_balance":{"description":"The current available balance of the account.","type":"number","format":"float"},"available_balance_national":{"description":"The current available balance of the account in the national currency.","type":"number","format":"float"},"hold":{"description":"The total amount of funds currently on hold in the account's currency. **Not used**","type":"number","format":"float"},"cards_reserved_amount":{"description":"The total amount reserved for card transactions in the account's currency. **Not used**","type":"number","format":"float"},"cards_reserved_amount_national":{"description":"The total amount reserved for card transactions in the national currency. **Not used**","type":"number","format":"float"}},"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"}}},"paths":{"/api/v1/webhooks_messages":{"get":{"tags":["WebhookMessages"],"summary":"Get Webhook Messages","description":"Retrieves a paginated list of webhook messages, optionally filtered by date range and status.","operationId":"API.WebhooksMessages.Get","parameters":[{"name":"date_from","in":"query","description":"Filter messages created from this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"date_to","in":"query","description":"Filter messages created up to this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"per_page","in":"query","description":"Number of messages 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 message list.","required":false,"schema":{"type":"string","default":"desc","enum":["asc","desc"]}},{"name":"sort","in":"query","description":"Field to sort the message list by.","required":false,"schema":{"type":"string","default":"created_at","enum":["created_at"]}},{"name":"status","in":"query","description":"Filter messages by their delivery status.","required":false,"schema":{"type":"string","enum":["processing","delivered","error","retry"]}}],"responses":{"200":{"description":"A paginated list of webhook messages.","headers":{"X-Api-Total":{"description":"Total number of webhook messages matching the filter criteria.","schema":{"type":"integer"}},"X-Api-Per-Page":{"description":"Number of messages returned on the current page.","schema":{"type":"integer"}},"X-Api-Current-Page":{"description":"The current page number being returned.","schema":{"type":"integer"}},"X-Api-Has-More-Pages":{"description":"Indicates if there are more pages available.","schema":{"type":"boolean"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/API.Resources.WebhookMessageResource"}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}}}}}}} ``` ## Get Webhook message by UUID > Retrieves the details of a specific webhook message by its UUID. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"WebhookMessages","description":"Viewing and managing webhook delivery messages/logs."}],"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.WebhookMessageResource":{"title":"Webhook Message Resource","description":"Resource representing the data structure of a webhook message.","properties":{"uuid":{"description":"Unique identifier for the webhook message.","type":"string","format":"uuid"},"created_at":{"description":"Timestamp when the webhook message was created.","type":"integer","format":"int64"},"status":{"description":"Delivery status of the webhook message.","type":"string","enum":["delivered","processing","error","retry"]},"account_uuid":{"description":"UUID of the account associated with the event that triggered the webhook.","type":"string","format":"uuid","nullable":true},"account":{"oneOf":[{"$ref":"#/components/schemas/API.Resources.AccountSimpleResource"}],"nullable":true,"description":"Simplified details of the account associated with the event. Included based on webhook configuration."},"transaction":{"oneOf":[{"$ref":"#/components/schemas/API.Resources.TransactionResource"}],"nullable":true,"description":"Details of the transaction associated with the event. Included for transaction-related webhooks."}},"type":"object"},"API.Resources.AccountSimpleResource":{"title":"Account Simple Resource","description":"Simplified resource representing key account details like UUID, number, currency, and balances.","required":["uuid","account_number","currency","balance","available_balance"],"properties":{"uuid":{"description":"Unique identifier for the account.","type":"string","format":"uuid"},"account_number":{"description":"The unique account number.","type":"string"},"currency":{"description":"The currency code of the account","type":"string","enum":["EUR","GBP","USD"]},"balance":{"description":"The current ledger balance of the account.","type":"number","format":"float"},"balance_national":{"description":"The current ledger balance of the account in the national currency.","type":"number","format":"float"},"book_balance":{"description":"The available book balance of the account. **Not used**","type":"number","format":"float"},"book_balance_national":{"description":"The available book balance of the account in the national currency. **Not used**","type":"number","format":"float"},"available_balance":{"description":"The current available balance of the account.","type":"number","format":"float"},"available_balance_national":{"description":"The current available balance of the account in the national currency.","type":"number","format":"float"},"hold":{"description":"The total amount of funds currently on hold in the account's currency. **Not used**","type":"number","format":"float"},"cards_reserved_amount":{"description":"The total amount reserved for card transactions in the account's currency. **Not used**","type":"number","format":"float"},"cards_reserved_amount_national":{"description":"The total amount reserved for card transactions in the national currency. **Not used**","type":"number","format":"float"}},"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/webhooks_messages/{uuid}":{"get":{"tags":["WebhookMessages"],"summary":"Get Webhook message by UUID","description":"Retrieves the details of a specific webhook message by its UUID.","operationId":"API.WebhooksMessages.Show","parameters":[{"name":"uuid","in":"path","description":"The UUID of the Webhook Message to retrieve.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"200":{"description":"Successfully retrieved the webhook message details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.WebhookMessageResource"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}} ``` ## Update webhook message status > Allows updating the status of a specific webhook message. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"WebhookMessages","description":"Viewing and managing webhook delivery messages/logs."}],"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.WebhookMessageResource":{"title":"Webhook Message Resource","description":"Resource representing the data structure of a webhook message.","properties":{"uuid":{"description":"Unique identifier for the webhook message.","type":"string","format":"uuid"},"created_at":{"description":"Timestamp when the webhook message was created.","type":"integer","format":"int64"},"status":{"description":"Delivery status of the webhook message.","type":"string","enum":["delivered","processing","error","retry"]},"account_uuid":{"description":"UUID of the account associated with the event that triggered the webhook.","type":"string","format":"uuid","nullable":true},"account":{"oneOf":[{"$ref":"#/components/schemas/API.Resources.AccountSimpleResource"}],"nullable":true,"description":"Simplified details of the account associated with the event. Included based on webhook configuration."},"transaction":{"oneOf":[{"$ref":"#/components/schemas/API.Resources.TransactionResource"}],"nullable":true,"description":"Details of the transaction associated with the event. Included for transaction-related webhooks."}},"type":"object"},"API.Resources.AccountSimpleResource":{"title":"Account Simple Resource","description":"Simplified resource representing key account details like UUID, number, currency, and balances.","required":["uuid","account_number","currency","balance","available_balance"],"properties":{"uuid":{"description":"Unique identifier for the account.","type":"string","format":"uuid"},"account_number":{"description":"The unique account number.","type":"string"},"currency":{"description":"The currency code of the account","type":"string","enum":["EUR","GBP","USD"]},"balance":{"description":"The current ledger balance of the account.","type":"number","format":"float"},"balance_national":{"description":"The current ledger balance of the account in the national currency.","type":"number","format":"float"},"book_balance":{"description":"The available book balance of the account. **Not used**","type":"number","format":"float"},"book_balance_national":{"description":"The available book balance of the account in the national currency. **Not used**","type":"number","format":"float"},"available_balance":{"description":"The current available balance of the account.","type":"number","format":"float"},"available_balance_national":{"description":"The current available balance of the account in the national currency.","type":"number","format":"float"},"hold":{"description":"The total amount of funds currently on hold in the account's currency. **Not used**","type":"number","format":"float"},"cards_reserved_amount":{"description":"The total amount reserved for card transactions in the account's currency. **Not used**","type":"number","format":"float"},"cards_reserved_amount_national":{"description":"The total amount reserved for card transactions in the national currency. **Not used**","type":"number","format":"float"}},"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/webhooks_messages/{uuid}":{"patch":{"tags":["WebhookMessages"],"summary":"Update webhook message status","description":"Allows updating the status of a specific webhook message.","operationId":"API.WebhooksMessages.Update","parameters":[{"name":"uuid","in":"path","description":"The UUID of the Webhook Message to update.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"status","in":"query","description":"The new status to set for the webhook message.","required":true,"schema":{"type":"string","enum":["processing","delivered","error","retry"]}}],"responses":{"200":{"description":"Webhook message status updated successfully. Returns the updated resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.WebhookMessageResource"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}} ``` # Health check The Ping API is a lightweight health check endpoint. It allows you to verify that the Guru Pay API is reachable and operational. This endpoint does not require authentication and typically used for: * Basic uptime monitoring. * Early-stage integration testing. ## Ping API > A simple endpoint to check if the API is responsive. ```json {"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.3.0"},"tags":[{"name":"API","description":"General API information and utilities."}],"servers":[{"url":"https://public-api.gurupay.eu","description":"Production API Server"},{"url":"https://public-api-dev.gurupay.eu","description":"Sandbox API Server"}],"security":[],"paths":{"/api/v1/ping":{"get":{"tags":["API"],"summary":"Ping API","description":"A simple endpoint to check if the API is responsive.","operationId":"API.Util.Ping","responses":{"200":{"description":"Successful response indicating the API is up.","content":{"application/json":{"schema":{"properties":{"status":{"type":"string"}},"type":"object"}}}}}}}}} ``` # Echo Service ## Introduction The Echo Service is a sandbox-only testing feature that automatically returns payments to the sender. When a payment is sent with a specific reference format, the service echoes the original amount back as multiple return payments. This functionality is intended for integration testing and validation and is available only in the sandbox environment using approved test accounts. ### How It Works When you include a payment reference in the format `TEST`, the Echo Service: * Detects the reference pattern * Processes the payment in the sandbox environment * Returns the original amount to the sender * Splits the returned amount into equal parts based on the number specified **Example behavior:** * Sending €100 with `TEST4` returns **4 payments of €25** each * Sending €75 with `TEST3` returns **3 payments of €25** each ### Prerequisites Before using the Echo Service, ensure that: * You are operating in the sandbox environment * vThe destination account is enabled for Echo Service testing * The payment method is SEPA Instant (SEPA INST) {% hint style="info" %} **Important:** The Echo Service currently supports SEPA Instant payments only. {% endhint %} ### How to Use 1. In the payment reference / purpose field, enter: `TEST` * `` must be an integer between 1 and 10. * Use uppercase letters only. * Do not include spaces. Example: `TEST5` 2. Send the payment to one of the approved Echo Service IBANs. 3. The system will automatically return the original amount, split into equal payments according to the specified number. ### Approved IBANs The following accounts are enabled for Echo Service testing: | IBAN | BIC | | ------------------------ | ----------- | | **LT613240010000000004** | TRLULT21XXX | | **LT323982800000000004** | NSPYLT22XXX | Payments sent to other accounts will not trigger the Echo Service. ### Rules and Limits The Echo Service enforces the following rules and constraints: | Reference format | Must exactly match `TEST` | Valid: `TEST7` Β· Invalid: `TEST 7`, `test7`, `TEST11` | | ------------------- | --------------------------------------- | ----------------------------------------------------- | | Allowed range | `` must be between **1 and 10** | Values outside this range are rejected | | Account restriction | Only approved accounts are supported | Payments to other accounts are ignored | | Payment scheme | SEPA Instant only | Other SEPA schemes are not supported | | Amount splitting | Amount must be evenly divisible | €0.01 cannot be split into multiple parts | | Case sensitivity | Uppercase only | `TEST5` is valid, `test5` is not | | Formatting | No spaces or extra characters | Reference must contain only `TEST` | ### Troubleshooting If the Echo Service does not return payments as expected, verify the following: 1. Confirm the reference strictly follows `TEST` 2. Ensure uppercase letters and no spaces 3. Confirm the IBAN is listed in the approved Echo Service accounts 4. Ensure the amount can be evenly divided by the specified number 5. Confirm the payment is sent as **SEPA Instant** {% hint style="info" %} **Notes:** * The Echo Service is not available in production. * Intended strictly for testing and validation purposes. {% endhint %} # Events # Transaction Event Guru Pay sends a Transaction Webhook when a transaction changes state in the system. This allows your application to stay up-to-date with real-time status changes such as `created`, `processed`, `failed` or `rejected` . ## When It's Triggered This webhook is triggered when: * A transaction reaches a new lifecycle stage (e.g. Transaction is processed, transaction got rejected). * The transaction is inbound or outbound for an account assigned to your integration. * The webhook configuration is active for the recipient account. ## Event Structure ```json { "uuid": "be017d83-7d0e-447a-b682-3516e0dfafa0", "status": "created", "parent_transaction_uuid": null, "operation_date": "2025-05-28", "operation_date_time": "2025-05-28 11:04:44", "operation_date_unix": 1748430284, "amount": 2.22, "currency": "EUR", "payment_type": "INTERNAL", "transaction_type": "payment", "payment_urgency": "NORMAL", "payment_details": "2.22", "payment_code": null, "end_to_end_ident": "c0e26c0dc450445cbf1f52243d13b654", "direction": "DEBIT", "document_number": "TRNS_ZYQOXVY9ZU40OMDLC8CB2ICR", "created_at": 1748430284, "payer": { "name": "SERVICES UAB", "iban": "LT583400010000025717", "address": "Basanaviciaus Str. 1", "country_code": "LT", "agency_id": null, "agency_name": null, "agency_address": null, "agency_country": null, "ultimate": [] }, "recipient": { "name": "Benificiary name", "iban": "LT133400015000032274", "address": "Address 1", "country_code": "AU", "agency_id": null, "agency_name": null, "agency_address": null, "agency_country": null, "ultimate": [] } } ``` ## Event Types | Type | Description | | ---------------- | --------------------------------------------------------- | | status.created | A new transaction has been recorded. | | status.processed | A transaction has been completed successfully. | | status.failed | A transaction was rejected by AML or compliance. | | status.rejected | A transanction failed due to technical or business rules. | # Account Event ## Account Event Guru Pay sends an Account Webhook when an account changes state in the system. This allows your application to listent to account events like when a new account is created or closed. ## Virtual IBANs Currently Guru Pay application will send account events only to customers who are using Virtual IBAN product. With the later system updates, after public communication account webhooks will be enabled for all customers. ### When It's Triggered This webhook is triggered when: * A new Virtual IBAN is opened for a customer * Virtual IBAN is closed * The webhook configuration is active for the recipient account. ### Event Structure ```json { "type": "account", "event": "account.created", "created_at": 1757604022, "account": { "uuid": "7c004b54-3f62-4cb0-8ee1-16fc436ba39d", "status": "created", "customer_uuid": "6fe8a48e-82a1-4410-a18f-b2686b77f6d7", "account_name": "Account name", "account_number": "LT383400015000111111", "currency": "EUR", "opening_date": "2025-09-11", "opening_date_unix": 1757548800, "balance": 0, "balance_national": 0, "book_balance": 0, "book_balance_national": 0, "available_balance": 0, "available_balance_national": 0, "hold": 0, "cards_reserved_amount": 0, "cards_reserved_amount_national": 0, "created_at": 1757604019, "updated_at": 1757604019, "account_type": "virtual", "virtual_account_holder": { "name": "Virtual IBAN holder name", "person_type": "natural|legal", "citizenship": "LT", "registrationCode": "12345", "address": { "line": "Address line", "city": "Vilnius", "country": "LT", "postalCode": "111222" } } } } ``` ### Event Types | Type | Description | | --------------- | ----------------------------------------- | | account.created | New account was created and IBAN assigned | | account.closed | Account was closed | # Webhook statuses Available statuses for sent webhooks. Every webhook sent by the Guru Pay system has an associated delivery status that reflects the current state of the delivery attempt. These statuses help developers monitor and debug webhook itnegrations directly from the Developer Dashboard.

Flow of webhook statuses

## Statuses Explained | Status | Description | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | processing | The wehook has ben generated and is currently being processed for delivery. | | retry | The previous delivery attempt failed (e.g., network issue or non-2xx response). The system will automatically retry. | | delivered | The webhook has successfully delivered and acknowledged by your server with a `2xx` HTTP response. | | error | All retry attempts failed. The webhook is marked as failed and will not be retried automatically. You should contact us in order to retry it. |