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.

GEThttps://api.saq.digital/v2/finance/status-cashout

curl --request GET \
  --url 'https://api.saq.digital/v2/finance/status-cashout' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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
}'

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-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": "***.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
}

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:

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

Query by EndToEndId:

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

Query by idempotency key:

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

Response

Success Response (200 OK)

{
  "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-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": "***.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
}

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

{
  "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

{
  "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.

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

401 Unauthorized

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

Business Rules

Parameter Exclusivity: Only one query parameter (id, e2e_id, or idempotency_key) can be used per request
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
Authentication: Requires valid Bearer token with Cashout.READ permission
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

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

curl --request GET \
  --url 'https://api.saq.digital/v2/finance/status-cashout' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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
}'