post
https://gateway.prd.pppay.cloud/api/pix/pay
Creates a PIX payment request to a destination PIX key.
This endpoint allows PIX transfers to individuals or businesses using CPF/CNPJ, email, phone number, or random key (EVP).
- The PIX key must match the format defined in
pix_key_type. - The CPF/CNPJ provided in
document_numbermust be valid. - The
birth_datefield is required for merchants authorized to process transactions involving minors. If provided:- If it matches the CPF submitted, the payment will be created normally.
- If it does not match, a validation error will be returned.
- When used, the
bank_accounts_allowedfield restricts the banks authorized to settle the transaction.
PIX Key types reference
| Key | Description |
|---|---|
| document | Use a Brazilian document as a key. It could be a CPF or CNPJ document. (also known as Personal ID) |
| Use an email as key. It should be a valid email. | |
| phone | Use a phone number as PIX Key, format: XXYYYYYYYYY. XX - first 2 numbers being the code area YYYYYYYYY - last 9 numbers being phone itself |
| random | Use a random key as PIX Key in UUID format. |
Business Rule Notes
pix_key_valueauto-fill: if omitted butdocument_numberis provided, the system automatically usesdocument_numberas the PIX key.- PIX key normalization (transparent to the client):
phone: +55 is added automatically if not presentemail: converted to lowercasedocument: non-numeric characters are removed
- Ownership validation (
isSameTaxId): the system queries the processor's DICT and verifies whether thedocument_numberprovided matches the PIX key holder. If it does not match → 422. - Invalid PIX key: if the key does not exist in the DICT → 422 with pix_key_value.
- Blocked ISPB: if the destination financial institution is on the merchant's blocklist → 422.
- Duplicate transaction (VelocityControl): same credentials within a short interval → 409.
- bank_accounts_allowed: restricts the payment to specific bank accounts. Accepted fields are ispb, account_number, and branch.
Important: internally, this endpoint performs two operations with the provider. First, a DICT query is made to decode the provided PIX key — this is where all validations occur: key existence, match between the payer's document_number and the key holder, and ISPB block check. Only after this query succeeds is the second operation executed: the payment settlement request to the provider. This means errors related to the PIX key (pix_key_value) are returned before any financial movement is initiated.