Generate PIX Charge (Cash-In)
POST /api/pix/cash-in
POST https://<api-host>/api/pix/cash-inRequires a Bearer token in the Authorization header. See Generate Token to obtain one.
Generates a dynamic QR Code for receiving payments via PIX. The charge is created with status PENDING and, when paid, the status changes to CONFIRMED via webhook.
Authentication
Requires a Bearer token in the Authorization header.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
transaction | object | Yes | Transaction data |
transaction.value | number | Yes | Amount in BRL (up to 2 decimal places). Minimum: 0.01 |
transaction.description | string | Yes | Transaction description (max 100 characters) |
transaction.externalId | string | Yes | External transaction ID (unique per account, max 50 characters; must not start with MIRROR:) |
transaction.expirationTime | number | No | Expiration time in seconds (min 30s, max 7 days). Default: 86400 (24h). Some providers require higher minimums — see Per-provider limits |
transaction.generateQrCode | boolean | No | If true, returns the QR Code in Base64. Default: false |
payer | object | Yes | Payer data (informational — not sent to the PSP) |
payer.fullName | string | Yes | Payer's name. Informational — a fixed value may be used (e.g., the account's legal name). Max: 100 chars |
payer.document | string | Yes | CPF (11 digits) or CNPJ (14 digits), digits only. Informational — you may use the integrator's own CNPJ |
additionalInfo | object | No | Additional information (string:string key-value pairs, maximum 10 keys; the mirror key is reserved) |
splits | array | No | List of split payment recipients (maximum 10). When the PIX-IN is confirmed, the amount is automatically divided. The sum of splits plus fees cannot exceed the transaction amount |
splits[].pixKey | string | Yes | PIX key of the split recipient (max 255 chars) |
splits[].pixKeyType | string | Yes | Key type: EMAIL, PHONE, CPF, CNPJ, RANDOM |
splits[].name | string | Yes | Recipient name (max 255 chars) |
splits[].document | string | Yes | CPF (11 digits) or CNPJ (14 digits), numbers only |
splits[].type | string | Yes | Split type: FIXED (fixed amount in BRL) or PERCENTAGE (percentage over gross amount) |
splits[].value | number | Yes | Split value. FIXED: BRL amount with up to 2 decimals (e.g., 10.50). PERCENTAGE: percentage directly (e.g., 10 = 10%). Minimum: 0.01 |
splits[].immediate | boolean | No | If true, the split is executed immediately after the PIX-IN. Default: false (follows the account's configured frequency) |
Request Examples
Minimal scenario: generates a charge without QR Code and without additional data.
{
"transaction": {
"value": 49.90,
"description": "Assinatura mensal - Plano Básico",
"externalId": "SUB-2024-001"
},
"payer": {
"fullName": "Maria Silva",
"document": "12345678909"
}
}See the Payment Split guide for full details on types, calculations, frequencies, and advanced examples.
Code Examples
curl -X POST "https://<api-host>/api/pix/cash-in" \
-H "Authorization: Bearer $PIX_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"transaction": {
"value": 49.90,
"description": "Assinatura mensal - Plano Básico",
"externalId": "SUB-2024-001"
},
"payer": {
"fullName": "Maria Silva",
"document": "12345678909"
}
}'const axios = require('axios');
const response = await axios.post('https://<api-host>/api/pix/cash-in',
{
"transaction": {
"value": 49.90,
"description": "Assinatura mensal - Plano Básico",
"externalId": "SUB-2024-001"
},
"payer": {
"fullName": "Maria Silva",
"document": "12345678909"
}
},
{
headers: {
'Authorization': `Bearer ${process.env.PIX_API_TOKEN}`,
'Content-Type': 'application/json',
},
}
);
console.log(response.data);Response (201 Created)
| Field | Type | Description |
|---|---|---|
transactionId | string | Unique identifier of the generated transaction |
correlationId | string | Transaction correlation ID (UUID) |
externalId | string | External transaction ID (same value as input) |
status | string | Transaction status: PENDING (awaiting payment) |
pixCode | string | PIX code in standard EMV format (copy and paste) |
generateTime | string | PIX generation date and time (ISO 8601) |
expirationDate | string | PIX expiration date and time (ISO 8601) |
qrCodeImage | string | QR Code in Base64 (only when generateQrCode=true) |
{
"transactionId": "7845",
"correlationId": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "ORD-8842-20240115",
"status": "PENDING",
"pixCode": "00020126580014br.gov.bcb.pix0136550e8400-e29b-41d4-a716-4466554400005204000053039865802BR5916Tech Solutions Ltda6009SAO PAULO62070503***63041D3D",
"generateTime": "2024-01-15T10:30:00.000Z",
"expirationDate": "2024-01-15T11:30:00.000Z",
"qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51..."
}Errors
Returned when the body does not pass validation. Errors in nested fields (transaction.*, payer.*, splits[]) come with message as a list, one message per field. Errors in top-level fields (for example, missing transaction or an unknown field) come with code: PUB_REQUEST_BODY_INVALID and the fields in details.violations.
{
"statusCode": 400,
"timestamp": "2026-04-10T15:27:36.608Z",
"path": "/api/pix/cash-in",
"method": "POST",
"code": "HTTP_ERROR",
"message": [
"transaction.value deve ser no mínimo 0.01",
"transaction.description deve ter no máximo 100 caracteres"
],
"userMessage": "Requisição inválida. Verifique os dados enviados.",
"errorId": "31b5dc36b86c598e51a2a5389a37060d",
"error": "Bad Request"
}Common causes:
transaction.valueless than0.01or with more than 2 decimal placestransaction.descriptionortransaction.externalIdempty,descriptionlonger than 100 characters orexternalIdlonger than 50externalIdalready used on this account (PIX_DUPLICATE_EXTERNAL_ID)expirationTimeless than 30 (seconds) or greater than 604800 (7 days)expirationTimeless than the account provider minimum (errorCodePROVIDER_EXPIRATION_BELOW_MINIMUM) — see Per-provider limits- Sum of splits exceeds the transaction amount