Cashout auto approve pix key

POST https://api.somossimpay.com.br/v2/finance/create-cashout-self-approve

Creates a new PIX cashout transaction using a PIX key 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.

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

JSON

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "amount": 100.50,
  "key": "[email protected]",
  "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
key	String	PIX key of the recipient. Can be email, phone (use country example: +5511.....), CPF/CNPJ, or random key (EVP).	required
tag	String	Optional reference tag for tracking purposes. Free text field for client use.	optional

Request Examples

Transfer using email PIX key:

HTTP

POST /create-cashout-self-approve
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 idempotency key:

HTTP

POST /create-cashout-self-approve
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": "123456",
  "amount": 250.00,
  "key": "[phone]",
  "tag": "invoice-2024-001"
}

Transfer using CPF PIX key:

HTTP

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

{
  "source_account_branch_identifier": "0001",
  "source_account_number": "123456",
  "amount": 1500.00,
  "key": "12345678901"
}

Response Details

JSON

{
  "worked": true,
  "id": 789458,
  "transaction_id": 789458,
  "code_transaction": "E789458",
  "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": "550e8400-e29b-41d4-a716-446655440000",
  "erro_descriptor": null,
  "new_erro_descriptor": null
}

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 for the transfer (may be masked for security).
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. Will be null initially for PROCESSING transactions.
recipient_instution_name	String	Name of the recipient's financial institution. Will be null initially.
recipient_account_id	String	Recipient's account number. Will be null initially for PROCESSING transactions.
recipient_branch_id	String	Recipient's branch identifier. Will be null initially for PROCESSING transactions.
recipient_legal_id	String	Recipient's CPF or CNPJ. Will be null initially for PROCESSING transactions.
recipient_name	String	Recipient's name. Will be null initially for PROCESSING transactions.
recipient_account_type	String	Type of recipient's account. Will be null initially for PROCESSING transactions.
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.
400	Invalid Pix Key	The provided PIX key is invalid or in an incorrect format.
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.

Business Rules

1. PIX Key Validation: The PIX key must be valid according to PIX standards (email, phone, CPF/CNPJ, or EVP format).
2. Amount Validation: The amount must be greater than zero and have at most 2 decimal places.
3. Transaction Status: The transaction is created with NEW status, then immediately transitioned to PROCESSING status.
4. Background Processing: After the response is returned, a background task processes the cashout approval.
5. HMAC Validation: The request body must be validated using the provided HMAC signature.

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

Feature	Create Cashout	Create Cashout 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.