Gerar cobrança PIX (Cash-In)
POST /api/pix/cash-in
POST https://<api-host>/api/pix/cash-inRequer um Bearer token no header Authorization. Veja Gerar Token para obter um.
Gera um QR Code dinâmico para recebimento via PIX. A cobrança é criada com status PENDING e, quando paga, o status muda para CONFIRMED via webhook.
Autenticação
Requer token Bearer no header Authorization.
Request Body
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
transaction | object | Sim | Dados da transação |
transaction.value | number | Sim | Valor em reais (até 2 casas decimais). Mínimo: 0.01 |
transaction.description | string | Sim | Descrição da transação (máx 100 caracteres) |
transaction.externalId | string | Sim | ID externo da transação (único por conta, máx 50 caracteres; não pode começar com MIRROR:) |
transaction.expirationTime | number | Não | Tempo de expiração em segundos (min 30s, max 7 dias). Default: 86400 (24h). Alguns provedores exigem mínimos maiores — ver Limites por provedor |
transaction.generateQrCode | boolean | Não | Se true, retorna o QR Code em Base64. Default: false |
payer | object | Sim | Dados do pagador (informativos — não enviados ao PSP) |
payer.fullName | string | Sim | Nome do pagador. Informativo — pode usar valor fixo (ex: razão social da conta). Máx: 100 chars |
payer.document | string | Sim | CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números. Informativo — pode usar o CNPJ do próprio integrador |
additionalInfo | object | Não | Informações adicionais (chave-valor string:string, máximo 10 chaves; a chave mirror é reservada) |
splits | array | Não | Lista de destinatários para split do pagamento (máximo 10). Quando o PIX-IN é confirmado, o valor é dividido automaticamente. A soma dos splits mais as taxas não pode exceder o valor da transação |
splits[].pixKey | string | Sim | Chave PIX do destinatário do split (máx 255 chars) |
splits[].pixKeyType | string | Sim | Tipo da chave: EMAIL, PHONE, CPF, CNPJ, RANDOM |
splits[].name | string | Sim | Nome do destinatário (máx 255 chars) |
splits[].document | string | Sim | CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números |
splits[].type | string | Sim | Tipo do split: FIXED (valor fixo em reais) ou PERCENTAGE (percentual sobre valor bruto) |
splits[].value | number | Sim | Valor do split. FIXED: reais com até 2 casas (ex: 10.50). PERCENTAGE: percentual direto (ex: 10 = 10%). Mínimo: 0.01 |
splits[].immediate | boolean | Não | Se true, split executado imediatamente após o PIX-IN. Default: false (segue frequência da conta) |
Exemplos de Request
Cenário mínimo: gera uma cobrança sem QR Code, sem dados adicionais.
{
"transaction": {
"value": 49.90,
"description": "Assinatura mensal - Plano Básico",
"externalId": "SUB-2024-001"
},
"payer": {
"fullName": "Maria Silva",
"document": "12345678909"
}
}Veja o guia de Split de Pagamentos para detalhes completos sobre tipos, cálculos, frequências e exemplos avançados.
Exemplos de Código
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)
| Campo | Tipo | Descrição |
|---|---|---|
transactionId | string | Identificador único da transação gerada |
correlationId | string | ID de correlação da transação (UUID) |
externalId | string | ID externo da transação (mesmo valor do input) |
status | string | Status da transação: PENDING (aguardando pagamento) |
pixCode | string | Código Pix no formato padrão EMV (copia e cola) |
generateTime | string | Data e hora de geração do Pix (ISO 8601) |
expirationDate | string | Data e hora de expiração do Pix (ISO 8601) |
qrCodeImage | string | QR Code em Base64 (apenas quando 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..."
}Erros
Retornado quando o body não atende as validações. Erros nos campos internos (transaction.*, payer.*, splits[]) vêm com message em forma de lista, uma mensagem por campo. Erros nos campos de primeiro nível (por exemplo, transaction ausente ou campo desconhecido) vêm com code: PUB_REQUEST_BODY_INVALID e os campos em 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"
}Causas comuns:
transaction.valuemenor que0.01ou com mais de 2 casas decimaistransaction.descriptionoutransaction.externalIdvazios,descriptioncom mais de 100 caracteres ouexternalIdcom mais de 50externalIdjá utilizado nesta conta (PIX_DUPLICATE_EXTERNAL_ID)expirationTimemenor que 30 (segundos) ou maior que 604800 (7 dias)expirationTimemenor que o mínimo do provedor da conta (errorCodePROVIDER_EXPIRATION_BELOW_MINIMUM) — ver Limites por provedor- Soma dos splits excede o valor da transação