Create Cashout Manual (Requires Approval)

Creates a new PIX cashout transaction using manual recipient account details. This endpoint allows you to initiate a transfer by specifying the complete recipient bank account information instead of using a PIX key. The transaction is created with `NEW` status and requires approval before being processed.

POSThttps://api.saq.digital/v2/finance/create-cashout-manual

curl --request POST \
  --url 'https://api.saq.digital/v2/finance/create-cashout-manual' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'hmac: <HMAC_SIGNATURE>' \
  --header 'Content-Type: application/json' \
  --data '{
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "amount": 500,
  "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"
}'

Response200

{
  "worked": true,
  "id": 789457,
  "transaction_id": 789457,
  "code_transaction": null,
  "status": "NEW",
  "amount": 100.5,
  "fee": 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": ""
}

Endpoint

POST /v2/finance/create-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
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:

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": 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 /v2/finance/create-cashout-manual
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": 789457,
  "transaction_id": 789457,
  "code_transaction": null,
  "status": "NEW",
  "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` for transactions with status `NEW`.
status	String	Current status of the transaction. Will be `NEW` for newly created 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` for status `NEW`.
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 processed.
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

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.
All recipient account details must be provided accurately to ensure successful transfer.
The recipient_account_model field must always be "Movement".
ISPB code must be 8 digits.
CPF/CNPJ must contain numbers only.

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:

This endpoint provides all recipient details upfront, unlike PIX key transfers where details are resolved by the PIX system.
For transfers using PIX keys instead of manual account details, use the PIX key cashout endpoint.

curl --request POST \
  --url 'https://api.saq.digital/v2/finance/create-cashout-manual' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'hmac: <HMAC_SIGNATURE>' \
  --header 'Content-Type: application/json' \
  --data '{
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "amount": 500,
  "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"
}'

Response200

{
  "worked": true,
  "id": 789457,
  "transaction_id": 789457,
  "code_transaction": null,
  "status": "NEW",
  "amount": 100.5,
  "fee": 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": ""
}