Status Cashout by Tag

GET https://api.somossimpay.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

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