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.

GEThttps://api.somossimpay.com.br/v2/finance/status-cashout/tag

curl --request GET \
  --url 'https://api.somossimpay.com.br/v2/finance/status-cashout/tag' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "worked": false,
  "detail": "tag: Field required",
  "message": "tag: Field required",
  "data": {
    "type": "missing",
    "loc": [
      "query",
      "tag"
    ],
    "msg": "Field required",
    "input": null
  }
}'

Response200

[
  {
    "worked": true,
    "id": 123456,
    "transaction_id": 123456,
    "code_transaction": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "SUCCESS",
    "amount": 100.5,
    "fee": 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": "***.316.848-**",
    "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,
    "fee": 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": "***.316.848-**",
    "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
  }
]

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:

GET /status-cashout/tag?tag=payment-batch-001
Authorization: Bearer <access_token>

Query order payments:

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

Query invoice batch:

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:

[
  {
    "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": "***.316.848-**",
    "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": "***.316.848-**",
    "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:

[]

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.

{
  "worked": false,
  "detail": "tag: Field required",
  "message": "tag: Field required",
  "data": {
    "type": "missing",
    "loc": ["query", "tag"],
    "msg": "Field required",
    "input": null
  }
}

401 Unauthorized

{
  "worked": false,
  "detail": "Invalid or expired token",
  "message": "Invalid or expired token",
  "data": null
}

Business Rules

Tag Matching: Returns all transactions that have the exact tag value provided
Case Sensitivity: Tag comparison is case-sensitive
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
Authentication: Requires valid Bearer token with Cashout.READ permission
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

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

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

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

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

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

curl --request GET \
  --url 'https://api.somossimpay.com.br/v2/finance/status-cashout/tag' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "worked": false,
  "detail": "tag: Field required",
  "message": "tag: Field required",
  "data": {
    "type": "missing",
    "loc": [
      "query",
      "tag"
    ],
    "msg": "Field required",
    "input": null
  }
}'