Status Cashout

GET https://api.somossimpay.com.br/v2/finance/status-cashout

Retrieves the status and details of a cashout transaction. You can query by transaction ID, EndToEndId (e2e_id), or idempotency key. This endpoint provides comprehensive information about the transaction including status, amounts, recipient details, and timestamps.

Endpoint

GET /status-cashout

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
id	Integer	Transaction ID. Only one parameter (id, e2e_id, or idempotency_key) should be provided.	conditional	123456
e2e_id	String	EndToEndId of the transaction. Only one parameter (id, e2e_id, or idempotency_key) should be provided.	conditional	E60701190202301011200123456789012
idempotency_key	UUID	Idempotency key used when creating the transaction. Only one parameter should be provided.	conditional	550e8400-e29b-41d4-a716-446655440000

Important: Exactly one of the three parameters must be provided. If none or multiple parameters are provided, the API will return a 400 error.

Request Examples

Query by transaction ID:

HTTP

GET /status-cashout?id=123456
Authorization: Bearer <access_token>

Query by EndToEndId:

HTTP

GET /status-cashout?e2e_id=E60701190202301011200123456789012
Authorization: Bearer <access_token>

Query by idempotency key:

HTTP

GET /status-cashout?idempotency_key=550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <access_token>

Response

Success Response (200 OK)

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": "PROCESSING",
  "tag": "payment-reference-123",
  "e2e_id": "E60701190202301011200123456789012",
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-01T12:01:00Z"
}

Response Fields

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
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 Parameter Provided

JSON

{
  "detail": "Either 'id', 'e2e_id' or 'idempotency_key' parameter is required"
}

400 Bad Request - Multiple Parameters Provided

JSON

{
  "detail": "Only one parameter should be provided: 'id', 'e2e_id' or 'idempotency_key'"
}

400 Bad Request - Transaction Not Found

JSON

{
  "detail": "Transaction not found"
}

401 Unauthorized

JSON

{
  "detail": "Invalid or expired token"
}

Business Rules

1. Parameter Exclusivity: Only one query parameter (id, e2e_id, or idempotency_key) can be used per request
2. Company Scope: Users can only query transactions belonging to their company
3. Authentication: Requires valid Bearer token with Cashout.READ permission
4. Audience Support: Available for both WEB and API audiences

Use Cases

• Transaction Tracking: Monitor the status of cashout operations
• Reconciliation: Match transactions using idempotency keys
• Customer Support: Look up transaction details using EndToEndId
• Webhook Verification: Confirm transaction status after webhook notifications

Related Endpoints

• POST Create Cashout - Create a new cashout transaction
• POST Approve Cashout - Approve a pending cashout
• GET Status Cashout by Tag - Query multiple transactions by tag