Status Cashout

GET https://api.adopay.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 error descriptors.

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

{
  "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-reference-123",
  "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
}

Response Fields

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, PENDENT, 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 informed when the cashout was created
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. This is the value matched by the e2e_id query parameter
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 - No Parameter Provided

JSON

{
  "worked": false,
  "detail": "Either 'id', 'e2e_id' or 'idempotency_key' parameter is required",
  "message": "Either 'id', 'e2e_id' or 'idempotency_key' parameter is required",
  "data": null
}

400 Bad Request - Multiple Parameters Provided

JSON

{
  "worked": false,
  "detail": "Only one parameter should be provided: 'id', 'e2e_id' or 'idempotency_key'",
  "message": "Only one parameter should be provided: 'id', 'e2e_id' or 'idempotency_key'",
  "data": null
}

400 Bad Request - Transaction Not Found

Also returned when the transaction exists but the authenticated user has no policy granting access to the source account.

JSON

{
  "worked": false,
  "detail": "Transaction not found",
  "message": "Transaction not found",
  "data": null
}

401 Unauthorized

JSON

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

Business Rules

1. Parameter Exclusivity: Only one query parameter (id, e2e_id, or idempotency_key) can be used per request
2. Account Policy: The authenticated user must hold a policy for the transaction's source account; otherwise the API responds as if the transaction did not exist
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