Pix cashout using pix key (create payment for approval)

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

Creates a new PIX cashout transaction using a PIX key. This endpoint is designed for API integrations where transfers are initiated using the recipient's PIX key. The transaction is created with NEW status and requires approval before being processed.

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 (email, phone, CPF/CNPJ, or EVP random key).	required
tag	String	Optional reference tag for tracking purposes. Free text field for client use.	optional

Request Examples

Basic transfer:

HTTP

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

HTTP

POST /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": "[phone]",
  "tag": "invoice-payment-456"
}

Transfer with idempotency key:

HTTP

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

JSON

{
  "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": ""
}

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 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 for status NEW when using PIX keys.
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. Will be null for status NEW.
recipient_branch_id	String	Recipient's branch identifier. Will be null for status NEW.
recipient_legal_id	String	Recipient's CPF or CNPJ. Will be null for status NEW.
recipient_name	String	Recipient's name. Will be null for status NEW.
recipient_account_type	String	Type of recipient's account. Will be null for status NEW.
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. Authentication: This endpoint requires API authentication (audience type: API) with Bearer token and HMAC signature.
2. HMAC Validation: The request body must be validated using the provided HMAC signature.
3. PIX Key Validation: The PIX key must be valid according to PIX standards (email, phone, CPF/CNPJ, or EVP).
4. Amount Validation: The amount must be greater than zero and have at most 2 decimal places.
5. Transaction Status: Newly created transactions have status NEW and require approval before being processed.
6. Account Identification: The source account is identified by branch identifier and account number.

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.

Differences from Other Endpoints

This endpoint is similar to /create-cashout but may have specific use cases or workflow differences. For transfers using complete recipient account details instead of PIX keys, see the Create Cashout Manual documentation.

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.

For more detailed examples and implementation guidance, see the Create Cashout documentation.