Approve Cashout

Time	Status	User Agent
Retrieving recent requests…

Endpoint

POST /v2/finance/approve-cashout-manual

Headers

Parameter	Type	Description	Required or Optional	Example
Authorization	String	Bearer + Access_token	required	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo
hmac	String	HMAC (Hash-based Message Authentication Code) is an authentication algorithm that combines a private key with a message to create a Message Authentication Code (MAC).	required	hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b99f4081ff231b87f82118c1e77a959e1f40eacf690a8fa61a827a9ba01d546f6

Body Details

{
  "id": 789457
}

Field	Type	Description	Required or Optional
id	Integer	The unique identifier of the transaction to approve.	required

Request Examples

Approve a manual cashout transaction:

POST /v2/finance/approve-cashout-manual
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json

{
  "id": 789457
}

Response Details

{
  "worked": true,
  "id": 789457,
  "transaction_id": 789457,
  "code_transaction": "E789457",
  "status": "PROCESSING",
  "amount": 100.5,
  "fee": 0.0,
  "key": null,
  "tag": "payment-reference-123",
  "from_accout": "123456",
  "recipient_instution": "12345678",
  "recipient_instution_name": "Example Bank",
  "recipient_account_id": "654321-9",
  "recipient_branch_id": "0001",
  "recipient_legal_id": "12345678901",
  "recipient_name": "John Doe",
  "recipient_account_type": "CONTA_CORRENTE",
  "operationUuid": null,
  "idempotency_key": null,
  "erro_descriptor": null,
  "new_erro_descriptor": null
}

Field	Type	Description
worked	Boolean	Always `true` for successful requests.
id	Integer	Unique identifier of the transaction.
transaction_id	Integer	Transaction identifier (same as id).
code_transaction	String	Human-readable transaction code.
status	String	Current status of the transaction. Will be `PROCESSING` after approval.
amount	Float	Amount to be transferred.
fee	Float	Transaction fee charged. Currently 0.0 for PIX transactions.
key	String	PIX key used for the transfer, or `null` if manual details were provided.
tag	String	Reference tag provided when the transaction was created, or `null`.
from_accout	String	Source account number from which the transfer will be made.
recipient_instution	String	ISPB code of the recipient's financial institution.
recipient_instution_name	String	Name of the recipient's financial institution.
recipient_account_id	String	Recipient's account number.
recipient_branch_id	String	Recipient's branch identifier.
recipient_legal_id	String	Recipient's CPF or CNPJ.
recipient_name	String	Recipient's name.
recipient_account_type	String	Type of recipient's account (e.g., CONTA_CORRENTE, CONTA_POUPANCA).
operationUuid	String	Operation UUID from the payment system, or `null` if not yet assigned.
idempotency_key	String	The idempotency key if one was provided during creation, or `null`.
erro_descriptor	String	Error description if the transaction failed, or `null` if successful.
new_erro_descriptor	String	Additional error information, or `null` if not applicable.

Error Responses

HTTP Code	Error Message	Description
400	Transaction not found	The transaction does not exist.
400	Transaction in wrong status	The transaction is not in `NEW` status. Only transactions with `NEW` status can be approved.
401	Unauthorized	Invalid or missing authentication token. Ensure you are sending a valid Bearer token and HMAC signature.
422	Validation error	Request validation failed. Check that the transaction ID is valid.

Business Rules

Authentication:

This endpoint requires API authentication with Bearer token and HMAC signature.
The request body must be validated using the provided HMAC signature.

Status Validation:

The transaction must be in NEW status to be approved.
Transactions in other statuses cannot be approved.

Status Transition:

Upon approval, the transaction status changes from NEW to PROCESSING.
A background task is initiated to complete the transfer.

Transaction Processing:

The transaction is locked during the approval process to prevent concurrent modifications.
Once approved, the transaction cannot be modified or cancelled.

Two-Step Approval Workflow

This endpoint is part of a two-step approval workflow:

Step 1: Create Transaction

Create a manual cashout transaction with NEW status using the create cashout manual endpoint.

Step 2: Approve Transaction

Use this endpoint to approve the transaction, changing its status to PROCESSING and initiating the transfer.

Workflow Example

1. Create the transaction:

POST /v2/finance/create-cashout-manual
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "amount": 100.50,
  "recipient_account_branch": "0001",
  "recipient_account_branch_digit": "0",
  "recipient_account_number": "654321",
  "recipient_account_number_digit": "9",
  "recipient_account_type": "CURRENT_ACCOUNT",
  "recipient_account_model": "Movement",
  "recipient_name": "John Doe",
  "recipient_legal_id": "12345678901",
  "recipient_instution": "12345678"
}

Response:

{
  "worked": true,
  "id": 789457,
  "status": "NEW",
  ...
}

2. Approve the transaction:

POST /v2/finance/approve-cashout-manual
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json

{
  "id": 789457
}