--- updatedAt: 2026-08-24T02:58:13.000Z --- Fetch the complete documentation index at: https://adopay-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 [ { "worked": true, "id": 123456, "transaction_id": 123456, "code_transaction": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "SUCCESS", "amount": 100.5, "fee": 0.0, "key": "joao@example.com", "tag": "payment-batch-001", "from_accout": "123456", "recipient_instution": "60701190", "recipient_instution_name": "ITAU UNIBANCO S.A.", "recipient_account_id": "654321", "recipient_branch_id": "0001", "recipient_legal_id": "12345678900", "recipient_name": "João da Silva", "recipient_account_type": "CURRENT_ACCOUNT", "operationUuid": "E60701190202301011200123456789012", "idempotency_key": "550e8400-e29b-41d4-a716-446655440000", "erro_descriptor": null, "new_erro_descriptor": null }, { "worked": true, "id": 123457, "transaction_id": 123457, "code_transaction": "b2c3d4e5-f6a7-8901-bcde-fa2345678901", "status": "PROCESSING", "amount": 250.0, "fee": 0.0, "key": "+5511987654321", "tag": "payment-batch-001", "from_accout": "123456", "recipient_instution": "60701190", "recipient_instution_name": "ITAU UNIBANCO S.A.", "recipient_account_id": "789012", "recipient_branch_id": "0002", "recipient_legal_id": "98765432100", "recipient_name": "Maria Santos", "recipient_account_type": "CURRENT_ACCOUNT", "operationUuid": "E60701190202301011200234567890123", "idempotency_key": "660f9511-f3ac-52e5-b827-557766551111", "erro_descriptor": null, "new_erro_descriptor": null } ] ``` ### Empty Result (200 OK) When no transaction matches the tag — or when every matching transaction belongs to an account the authenticated user has no policy for — the endpoint returns an empty array: ```json [] ``` ### Response Fields Each transaction object in the array contains: | Field | Type | Nullable | Description | | :----------------------------- | :------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **worked** | Boolean | no | Always `true` on a successful response | | **id** | Integer | no | Unique transaction identifier | | **transaction\_id** | Integer | no | Transaction identifier. Currently returns the same value as `id` | | **code\_transaction** | String | yes | Internal UUID of the transaction | | **status** | String | no | Transaction status. One of: `NEW`, `APPROVED`, `CANCELED`, `CANCELLED`, `WAITING REPROCESSING`, `PROCESSING`, `SUCCESS`, `AWAITING BANK CONFIRMATION`, `ERROR`, `REFUNDED` | | **amount** | Number | no | Transaction amount, serialized as a float | | **fee** | Number | no | Transaction fee, serialized as a float. Currently always returns `0.0` for this endpoint | | **key** | String | yes | PIX key used in the transaction. `null` for manual transfers (PIX without key) | | **tag** | String | yes | Custom reference tag. Matches the `tag` query parameter | | **from\_accout** | String | no | Source account number. Returns the mirror account when the transaction belongs to one. Note: the field name is spelled `from_accout` in the API contract | | **recipient\_instution** | String | yes | ISPB code of the recipient's bank, as stored in the transaction. Note: the field name is spelled `recipient_instution` in the API contract | | **recipient\_instution\_name** | String | yes | Name of the recipient's bank, resolved from the ISPB register. `null` when the ISPB is empty or not found | | **recipient\_account\_id** | String | yes | Account number of the recipient | | **recipient\_branch\_id** | String | yes | Branch/agency of the recipient's account | | **recipient\_legal\_id** | String | yes | CPF or CNPJ of the recipient | | **recipient\_name** | String | yes | Name of the recipient | | **recipient\_account\_type** | String | yes | Type of the recipient's account. Values written by the platform: `CURRENT_ACCOUNT`, `SAVING_ACCOUNT`, `PAYMENT_ACCOUNT`, `Salary` | | **operationUuid** | String | yes | EndToEndId assigned by the payment system | | **idempotency\_key** | String | yes | Idempotency key persisted on the transaction (UUID as string) | | **erro\_descriptor** | String | yes | Error descriptor returned by the banking partner | | **new\_erro\_descriptor** | String | yes | Normalized error descriptor | ## Error Responses All errors are returned through the standard error envelope: ### 400 Bad Request - Missing Tag Parameter Returned by request validation when the `tag` query parameter is not sent. ```json { "worked": false, "detail": "tag: Field required", "message": "tag: Field required", "data": { "type": "missing", "loc": ["query", "tag"], "msg": "Field required", "input": null } } ``` ### 401 Unauthorized ```json { "worked": false, "detail": "Invalid or expired token", "message": "Invalid or expired token", "data": null } ``` ## Business Rules 1. **Tag Matching**: Returns all transactions that have the exact tag value provided 2. **Case Sensitivity**: Tag comparison is case-sensitive 3. **Account Policy**: Only transactions whose source account is covered by one of the user's policies are included in the array. Transactions outside the user's policies are silently omitted 4. **Authentication**: Requires valid Bearer token with Cashout.READ permission 5. **Empty Results**: Returns 200 OK with an empty array when no transaction matches the tag or when all matches are filtered out by the account policy check ## 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_cashout_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.adopay.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-internal": false } } }, "x-readme": { "explorer-enabled": false, "proxy-enabled": true, "samples-languages": [ "curl", "python", "javascript", "java", "go" ] } } ```