Sends a Pix transfer from the authenticated account to a Pix key. Funds are
reserved against the account balance before the transfer is dispatched, so a
200 means the money is committed locally and the transfer is in flight - it
does not mean the recipient has been credited. Settlement arrives on the
PayOutCompleted webhook, or by polling GET /api/payout/{reference_code}.
Requires an access key with cash-out enabled. This route is idempotent: an
Idempotency-Key header is required, and a repeat of the same key replays the
first response instead of sending a second transfer.
Possible Status
- done
- failed
- totally_refunded
- partially_refunded
Idempotency-Key
The Idempotency-Key is a required header for ensuring the idempotency of API requests. It allows clients to safely retry a request without accidentally performing the same operation multiple times. This is especially critical for operations like payment processing, payouts, or other actions that should not be executed more than once.
Key Points:
- Required: Every idempotent API request must include the
Idempotency-Keyheader. - Uniqueness: The key must be unique for each distinct operation. For example, a new key should be generated for every new payout request.
- Format: The key should be a unique string, typically a UUID (e.g.,
123e4567-e89b-12d3-a456-426614174000). You can use the same value used inreference_code. - Lifetime: The key's validity is tied to the server's caching mechanism. Use the same key for retries of the same operation within the expiration window, which is 1 hour.
Client request timeout
We recommend setting a generous timeout for your client requests, as the PIX network can experience latency during peak hours. A timeout of 30 seconds is a good starting point, but you may need to adjust it based on your specific needs.