Status Cashout by Tag

GET https://api.adopay.com.br/v2/finance/status-cashout/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 <access_token>

Query order payments:

HTTP

GET /status-cashout/tag?tag=order-12345
Authorization: Bearer <access_token>

Query invoice batch:

HTTP

GET /status-cashout/tag?tag=invoice-2024-01
Authorization: Bearer <access_token>

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": "[email protected]",
    "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": "[phone]",
    "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 <access_token>

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 <access_token>

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 <access_token>

Query all cashouts related to January 2024 invoices for reconciliation purposes.

Related Endpoints

• GET Status Cashout - Query a single transaction by ID, e2e_id, or idempotency_key
• POST Create Cashout - Create a cashout with a tag
• POST Approve Cashout - Approve a pending cashout