--- updatedAt: 2026-06-11T16:02:15.000Z --- Fetch the complete documentation index at: https://simpay-prod.readme.io/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version. # Status Cashout by Tag Retrieves a list of all cashout transactions associated with a specific tag. This endpoint is useful for querying multiple transactions grouped by a common reference, such as batch payments, invoice numbers, or order IDs. Returns an array of transaction details. ## Endpoint ``` GET /status-cashout/tag ``` ## Headers | Parameter | Type | Description | Required or Optional | Example | | :---------------- | :----- | :--------------------- | :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Authorization** | String | Bearer + Access\_token | required | Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo | ## Query Parameters | Parameter | Type | Description | Required | Example | | :-------- | :----- | :--------------------------------------------------------------- | :------- | :---------------- | | **tag** | String | Tag value to search for. Returns all transactions with this tag. | required | payment-batch-001 | ## Request Examples **Query by tag:** ```http GET /status-cashout/tag?tag=payment-batch-001 Authorization: Bearer ``` **Query order payments:** ```http GET /status-cashout/tag?tag=order-12345 Authorization: Bearer ``` **Query invoice batch:** ```http GET /status-cashout/tag?tag=invoice-2024-01 Authorization: Bearer ``` ## Response ### Success Response (200 OK) Returns an array of cashout transactions matching the tag: ```json [ { "id": 123456, "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "company_id": 100, "account_id": 789, "account_mirror_id": null, "source_account_branch": "0001", "source_account_number": "123456", "amount": 100.50, "recipient_name": "João da Silva", "recipient_legal_id": "12345678900", "recipient_institution": "60701190", "recipient_institution_name": "Itaú Unibanco S.A.", "recipient_branch": "0001", "recipient_account": "654321", "recipient_account_type": "CONTA_CORRENTE", "key": "joao@example.com", "key_type": "EMAIL", "status": "APPROVED", "tag": "payment-batch-001", "e2e_id": "E60701190202301011200123456789012", "idempotency_key": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2023-01-01T12:00:00Z", "updated_at": "2023-01-01T12:05:00Z" }, { "id": 123457, "uuid": "b2c3d4e5-f6g7-8901-bcde-fg2345678901", "company_id": 100, "account_id": 789, "account_mirror_id": null, "source_account_branch": "0001", "source_account_number": "123456", "amount": 250.00, "recipient_name": "Maria Santos", "recipient_legal_id": "98765432100", "recipient_institution": "60701190", "recipient_institution_name": "Itaú Unibanco S.A.", "recipient_branch": "0002", "recipient_account": "789012", "recipient_account_type": "CONTA_CORRENTE", "key": "+5511987654321", "key_type": "PHONE", "status": "PROCESSING", "tag": "payment-batch-001", "e2e_id": "E60701190202301011200234567890123", "idempotency_key": "660f9511-f3ac-52e5-b827-557766551111", "created_at": "2023-01-01T12:01:00Z", "updated_at": "2023-01-01T12:02:00Z" } ] ``` ### Response Fields Each transaction object in the array contains: | Field | Type | Description | | :------------------------------- | :------- | :------------------------------------------------------------------------------- | | **id** | Integer | Unique transaction identifier | | **uuid** | UUID | UUID of the transaction | | **company\_id** | Integer | Company identifier | | **account\_id** | Integer | Source account identifier | | **account\_mirror\_id** | Integer | Mirror account identifier (if applicable) | | **source\_account\_branch** | String | Branch identifier of the source account | | **source\_account\_number** | String | Account number of the source account | | **amount** | Decimal | Transaction amount | | **recipient\_name** | String | Name of the recipient | | **recipient\_legal\_id** | String | CPF or CNPJ of the recipient | | **recipient\_institution** | String | ISPB code of recipient's bank | | **recipient\_institution\_name** | String | Name of recipient's bank | | **recipient\_branch** | String | Branch/agency of recipient's account | | **recipient\_account** | String | Account number of the recipient | | **recipient\_account\_type** | String | Type of recipient's account (CONTA\_CORRENTE, CONTA\_POUPANCA, CONTA\_PAGAMENTO) | | **key** | String | PIX key used (if applicable) | | **key\_type** | String | Type of PIX key (EMAIL, PHONE, CPF, CNPJ, EVP) | | **status** | String | Transaction status (NEW, PROCESSING, APPROVED, REJECTED, CANCELED, ERROR) | | **tag** | String | Custom reference tag (will match the query parameter) | | **e2e\_id** | String | EndToEndId assigned by the payment system | | **idempotency\_key** | UUID | Idempotency key used when creating the transaction | | **created\_at** | DateTime | Timestamp when the transaction was created | | **updated\_at** | DateTime | Timestamp when the transaction was last updated | ## Error Responses ### 400 Bad Request - No Transactions Found ```json { "detail": "No transactions found" } ``` ### 400 Bad Request - Missing Tag Parameter ```json { "detail": "tag parameter is required" } ``` ### 401 Unauthorized ```json { "detail": "Invalid or expired token" } ``` ## Business Rules 1. **Tag Matching**: Returns all transactions that have the exact tag value provided 2. **Case Sensitivity**: Tag comparison is case-sensitive 3. **Company Scope**: Users can only query transactions belonging to their company 4. **Authentication**: Requires valid Bearer token with Cashout.READ permission 5. **Audience Support**: Available for both WEB and API audiences 6. **Empty Results**: Returns 400 error if no transactions are found with the given tag ## Use Cases * **Batch Payment Tracking**: Monitor all payments in a batch operation * **Order Management**: Track all cashouts related to a specific order * **Invoice Processing**: Query all payments for an invoice * **Reconciliation**: Match multiple transactions grouped by reference * **Reporting**: Generate reports for tagged transaction groups ## Examples ### Track Batch Payment Status ```http GET /status-cashout/tag?tag=payroll-2024-01 Authorization: Bearer ``` Use this to monitor all salary payments in a payroll batch. ### Monitor Order Payments ```http GET /status-cashout/tag?tag=order-ORD-2024-5678 Authorization: Bearer ``` Track multiple payments associated with a single order (e.g., split payments to multiple suppliers). ### Reconcile Monthly Invoice Payments ```http GET /status-cashout/tag?tag=invoice-202401 Authorization: Bearer ``` Query all cashouts related to January 2024 invoices for reconciliation purposes. ## Related Endpoints * [GET Status Cashout](get-status-cashout) - Query a single transaction by ID, e2e\_id, or idempotency\_key * [POST Create Cashout](create-cashout) - Create a cashout with a tag * [POST Approve Cashout](approve-cashout) - Approve a pending cashout # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "version": "3.0.0", "title": "Banking & PIX API", "description": "Complete API documentation for the banking and PIX payment platform." }, "servers": [ { "url": "https://api.somossimpay.com.br/" } ], "security": [], "tags": [ { "name": "Cashout-API", "description": "Cashout-API endpoints" } ], "paths": { "/v2/finance/status-cashout/tag": { "get": { "operationId": "get_cashout_status-cashout_tag", "summary": "Status Cashout by Tag", "description": "Retrieves a list of all cashout transactions associated with a specific tag. This endpoint is useful for querying multiple transactions grouped by a common reference, such as batch payments, invoice numbers, or order IDs. Returns an array of transaction details.", "tags": [ "Cashout-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } } } } }, "x-readme": { "explorer-enabled": false, "proxy-enabled": true, "samples-languages": [ "curl", "python", "javascript", "java", "go" ] } } ```