post
https://api.somossimpay.com.br/v2/finance/create-cashoutmanual-self-approve
Creates a new PIX cashout transaction using manual recipient account details and automatically approves it for processing. This endpoint combines the creation and approval steps, immediately transitioning the transaction from NEW to PROCESSING status. A background task is initiated to complete the transfer using the provided recipient account information.
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 |
| idempotency-key | String | Optional UUID to prevent duplicate transactions. When provided, ensures that retrying the same request will not create multiple transactions. See Idempotency section below. | optional | 550e8400-e29b-41d4-a716-446655440000 |
Body Details
{
"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",
"tag": "payment-reference-123"
}
| Field | Type | Description | Required or Optional |
|---|---|---|---|
| source_account_branch_identifier | String | Branch identifier of the source account from which the transfer will be made. | required |
| source_account_number | String | Account number of the source account from which the transfer will be made. | required |
| amount | Decimal | Amount to be transferred. Must be greater than 0 and have up to 2 decimal places. | required |
| recipient_account_branch | String | Branch number of the recipient's bank account. | required |
| recipient_account_branch_digit | String | Branch verification digit. Use empty string if not applicable. | optional |
| recipient_account_number | String | Account number of the recipient. | required |
| recipient_account_number_digit | String | Account number verification digit. | required |
| recipient_account_type | String | Type of recipient's account. See Account Type Values section below for accepted values. | required |
| recipient_account_model | String | Account model. Must always be "Movement" (fixed value). | required |
| recipient_name | String | Full name of the recipient. | required |
| recipient_legal_id | String | CPF or CNPJ of the recipient (numbers only). | required |
| recipient_instution | String | ISPB code of the recipient's financial institution (8 digits). | required |
| tag | String | Optional reference tag for tracking purposes. Free text field for client use. | optional |
Request Examples
Transfer to checking account with auto-approval:
POST /create-cashoutmanual-self-approve
Authorization: Bearer <access_token>
hmac: <computed_hmac>
Content-Type: application/json
{
"source_account_branch_identifier": "0001",
"source_account_number": "123456",
"amount": 500.00,
"recipient_account_branch": "0123",
"recipient_account_branch_digit": "",
"recipient_account_number": "987654",
"recipient_account_number_digit": "3",
"recipient_account_type": "CURRENT_ACCOUNT",
"recipient_account_model": "Movement",
"recipient_name": "Maria Silva",
"recipient_legal_id": "98765432100",
"recipient_instution": "60701190"
}
Transfer with idempotency key:
POST /create-cashoutmanual-self-approve
Authorization: Bearer <access_token>
hmac: <computed_hmac>
idempotency-key: 7c9e6679-7425-40de-944b-e07fc1f90ae7
Content-Type: application/json
{
"source_account_branch_identifier": "0001",
"source_account_number": "123456",
"amount": 1250.75,
"recipient_account_branch": "0001",
"recipient_account_branch_digit": "0",
"recipient_account_number": "111222",
"recipient_account_number_digit": "5",
"recipient_account_type": "SAVING_ACCOUNT",
"recipient_account_model": "Movement",
"recipient_name": "João Santos",
"recipient_legal_id": "12345678901",
"recipient_instution": "12345678",
"tag": "contract-payment-456"
}
Response Details
{
"worked": true,
"id": 789459,
"transaction_id": 789459,
"code_transaction": null,
"status": "PROCESSING",
"amount": 100.5,
"fee": 0.0,
"key": null,
"tag": "payment-reference-123",
"from_accout": "123456",
"recipient_instution": "12345678",
"recipient_instution_name": null,
"recipient_account_id": "654321-9",
"recipient_branch_id": "0001",
"recipient_legal_id": "123********01",
"recipient_name": "John Doe",
"recipient_account_type": "Current Account",
"operationUuid": null,
"idempotency_key": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"erro_descriptor": "",
"new_erro_descriptor": ""
}
| 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. Will be null initially for PROCESSING transactions. |
| status | String | Current status of the transaction. Will be PROCESSING for self-approved cashouts. |
| amount | Float | Amount transferred. |
| fee | Float | Transaction fee charged. Currently 0.0 for PIX transactions. |
| key | String | PIX key used. Will be null for manual transfers. |
| tag | String | Reference tag provided in the request, or empty string if not provided. |
| from_accout | String | Source account number from which the transfer was made. |
| recipient_instution | String | ISPB code of the recipient's financial institution. |
| recipient_instution_name | String | Name of the recipient's financial institution. Will be null initially. |
| recipient_account_id | String | Recipient's account number with verification digit (e.g., "654321-9"). |
| recipient_branch_id | String | Recipient's branch identifier. |
| recipient_legal_id | String | Recipient's CPF or CNPJ (may be masked for security). |
| recipient_name | String | Recipient's name. |
| recipient_account_type | String | Type of recipient's account (e.g., "Current Account", "Savings Account", "Payment Account"). |
| operationUuid | String | Operation UUID from the payment system, or null if not yet assigned. |
| idempotency_key | String | The idempotency key provided in the request, or null if not provided. |
| erro_descriptor | String | Error description if the transaction failed, or empty string if successful. |
| new_erro_descriptor | String | Additional error information, or empty string if not applicable. |
Error Responses
| HTTP Code | Error Message | Description |
|---|---|---|
| 400 | Account not found | The specified source account does not exist. |
| 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 all required fields are present and in the correct format. |
Account Type Values
When providing manual recipient account details, use these values for recipient_account_type:
| Value | Description |
|---|---|
| CURRENT_ACCOUNT | Current Account |
| PAYMENT_ACCOUNT | Payment Account |
| SAVING_ACCOUNT | Savings Account |
Note: The recipient_account_model field must always be set to "Movement" (fixed value).
Business Rules
- Amount Validation: The amount must be greater than zero and have at most 2 decimal places.
- Transaction Status: The transaction is created with
NEWstatus, then immediately transitioned toPROCESSINGstatus. - Background Processing: After the response is returned, a background task processes the cashout approval.
- HMAC Validation: The request body must be validated using the provided HMAC signature.
- Recipient Information: All recipient account details must be provided accurately to ensure successful transfer.
- Account Model: The
recipient_account_modelfield must always be"Movement".
Idempotency
This endpoint supports the optional idempotency-key header to prevent duplicate transactions. Since this endpoint automatically approves transactions, using idempotency keys is critically important to avoid duplicate money transfers.
For complete details on how idempotency works, including key format, response codes, and best practices, see the Idempotency section in the main documentation.
Differences from Standard Create Cashout Manual
| Feature | Create Cashout Manual | Create Cashout Manual Self Approve |
|---|---|---|
| Initial Status | NEW | PROCESSING |
| Approval Required | Yes (separate call) | No (automatic) |
| Required Permissions | CREATE | CREATE + APPROVE |
| Idempotency Importance | Recommended | Critical (strongly recommended) |
| Background Processing | After approval | Immediate |
| Use Case | Multi-step approval | Single-step, trusted operations |
For more detailed examples and implementation guidance, see the Create Cashout documentation.