Headers

Body Details

{
  "id": 789456
}

Request Examples

Approve a cashout transaction:

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

{
  "id": 789456
}

Approve a manual cashout transaction:

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

{
  "id": 789457
}

Response Details

{
  "worked": true,
  "id": 789456,
  "transaction_id": 789456,
  "code_transaction": "E789456",
  "status": "PROCESSING",
  "amount": 100.5,
  "fee": 0.0,
  "key": "[email protected]",
  "tag": "payment-reference-123",
  "from_accout": "123456",
  "recipient_instution": "12345678",
  "recipient_instution_name": "Example Bank",
  "recipient_account_id": "654321",
  "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
}

Error Responses

Business Rules

1. Status Validation: The transaction must be in NEW status to be approved. Transactions in other statuses cannot be approved.
2. HMAC Validation: The request body must be validated using the provided HMAC signature.
3. Status Transition: Upon approval, the transaction status changes from NEW to PROCESSING.
4. Background Processing: After approval, a background task is initiated to complete the transfer.
5. Transaction Locking: The transaction is locked during the approval process to prevent concurrent modifications.

Two-Step Approval Workflow

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

Step 1: Create Transaction

Use one of the following endpoints to create a cashout transaction with NEW status:

• POST /create-cashout - Create cashout with PIX key
• POST /create-cashout-manual - Create cashout with manual account details

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 /create-cashout
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "amount": 100.50,
  "key": "[email protected]"
}

Response:

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

2. Approve the transaction:

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

{
  "id": 789456
}

Response:

{
  "worked": true,
  "id": 789456,
  "status": "PROCESSING",
  ...
}

Use Cases

1. Manual Approval Workflow: Organizations that require manual review and approval of transactions before processing.
2. Compliance Requirements: Companies with compliance policies that mandate dual authorization for financial transactions.
3. Risk Management: High-value transactions that need additional verification before being processed.
4. Audit Trail: Separating creation and approval provides a clear audit trail showing who created and who approved each transaction.
5. Different User Roles: One user creates the transaction, and another user with approval permissions reviews and approves it.

Differences from Self-Approve Endpoints

Transaction Status Flow

[Create Transaction] → NEW → [Approve Transaction] → PROCESSING → SUCCESS/FAILED

• NEW: Transaction created and waiting for approval
• PROCESSING: Transaction approved and being processed by the payment system
• SUCCESS: Transfer completed successfully
• FAILED: Transfer failed (insufficient funds, recipient issues, etc.)

Only transactions in NEW status can be approved. Once a transaction moves to PROCESSING or any other status, it cannot be approved again.

Related Endpoints

• POST /create-cashout - Create cashout transaction with PIX key (requires separate approval)
• POST /create-cashout-manual - Create cashout with manual details (requires separate approval)
• POST /create-cashout-self-approve - Create and auto-approve in one step
• POST /create-cashoutmanual-self-approve - Create manual cashout and auto-approve