Create cashout manual (create payment for approval)

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 /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 /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

Amount Validation: The amount must be greater than zero and have at most 2 decimal places.
Transaction Status: Newly created transactions have status NEW and require approval before being processed.
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_model field must always be "Movement".

Idempotency

This endpoint supports the optional idempotency-key header to prevent duplicate transactions. For complete details on how idempotency works, including key format, response codes, and best practices, see the Idempotency section in the main documentation.