Endpoint

POST /v2/finance/create-cashout

Headers

Body Details

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "amount": 100.50,
  "key": "[email protected]",
  "tag": "payment-reference-123"
}

Request Examples

Basic transfer:

POST /v2/finance/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]"
}

Transfer with tag:

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

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "amount": 250.00,
  "key": "+5511999999999",
  "tag": "invoice-payment-456"
}

Transfer with idempotency key:

POST /v2/finance/create-cashout
Authorization: Bearer <access_token>
hmac: <computed_hmac>
idempotency-key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "900002",
  "amount": 1500.00,
  "key": "12345678901",
  "tag": "contract-payment"
}

Response Details

{
  "worked": true,
  "id": 789461,
  "transaction_id": 789461,
  "code_transaction": null,
  "status": "NEW",
  "amount": 100.5,
  "fee": 0.0,
  "key": "recip***@example.com",
  "tag": "payment-reference-123",
  "from_accout": "123456",
  "recipient_instution": null,
  "recipient_instution_name": null,
  "recipient_account_id": null,
  "recipient_branch_id": null,
  "recipient_legal_id": null,
  "recipient_name": null,
  "recipient_account_type": null,
  "operationUuid": null,
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "erro_descriptor": "",
  "new_erro_descriptor": ""
}

Error Responses

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.

Validations:

• Amount must be greater than zero and have at most 2 decimal places.
• PIX key must be valid according to PIX standards (email, phone, CPF/CNPJ, or EVP).
• Source account must be identified by branch identifier and account number.

Transaction Status:

• Newly created transactions have status NEW and require approval before being processed.
• Use the approve endpoint to transition the transaction to PROCESSING status.

Idempotency:

• The optional idempotency-key header prevents duplicate transactions when provided.
• Use UUID v4 format (RFC 4122) for the idempotency key.
• Retrying a request with the same idempotency key will:
  • Return HTTP 200 with the existing transaction if the request body is identical
  • Return HTTP 409 if the request body differs from the original request
• Idempotency keys are unique per company and have no expiration.

Important Notes:

• Recipient information (name, CPF/CNPJ, bank details) is resolved by the PIX system after approval.
• For transfers using complete recipient account details instead of PIX keys, use the manual cashout endpoint.

Use Cases

1. API Integration: Third-party systems integrate with the API to initiate transfers automatically.
2. PIX Key Transfers: Quick transfers using just the recipient's PIX key (email, phone, CPF/CNPJ, or EVP).
3. Transaction Tracking: Use the optional tag field to associate transfers with internal references.
4. Two-Step Workflow: Transactions are created with NEW status and require explicit approval before processing.
5. Secure Transfers: HMAC validation ensures request integrity and prevents tampering.