Generate PIX Charge (Cash-In)

POST /api/pix/cash-in

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 140 chars)
`transaction.externalId`	string	Yes	External transaction ID (unique identifier per account)
`transaction.expirationTime`	number	No	Expiration time in seconds (min 5 min, max 7 days). Default: `86400` (24h)
`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). Informational — you may use the integrator's own CNPJ
`additionalInfo`	object	No	Additional information (string:string key-value pairs, maximum 10 keys)
`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 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": "12345678901"
  }
}

Most common scenario: generates a QR Code to display to the payer, with order metadata and 1-hour expiration.

{
  "transaction": {
    "value": 189.90,
    "description": "Pedido #8842 - Loja Virtual",
    "externalId": "ORD-8842-20240115",
    "expirationTime": 3600,
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Carlos Oliveira",
    "document": "98765432000188"
  },
  "additionalInfo": {
    "orderId": "8842",
    "storeName": "Tech Solutions",
    "customerEmail": "carlos@email.com"
  }
}

High-value charge (B2B) with long expiration (7 days) and CNPJ as payer.

{
  "transaction": {
    "value": 15750.00,
    "description": "NF 2024/0042 - Consultoria em TI",
    "externalId": "NF-2024-0042",
    "expirationTime": 604800,
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Empresa ABC Ltda",
    "document": "11222333000144"
  },
  "additionalInfo": {
    "nfNumber": "2024/0042",
    "contractId": "CTR-789"
  }
}

Marketplace: a R$ 200 payment split between the seller (70%), platform (20%), and courier (R$ 10 fixed). Splits will be executed according to the frequency configured on the account.

{
  "transaction": {
    "value": 200.00,
    "description": "Pedido #12345 - Marketplace",
    "externalId": "MKT-12345",
    "generateQrCode": true
  },
  "payer": {
    "fullName": "João Pereira",
    "document": "12345678901"
  },
  "splits": [
    {
      "pixKey": "vendedor@email.com",
      "pixKeyType": "EMAIL",
      "name": "Loja do João",
      "document": "98765432000188",
      "type": "PERCENTAGE",
      "value": 70
    },
    {
      "pixKey": "11222333000144",
      "pixKeyType": "CNPJ",
      "name": "Marketplace Ltda",
      "document": "11222333000144",
      "type": "PERCENTAGE",
      "value": 20
    },
    {
      "pixKey": "11999887766",
      "pixKeyType": "PHONE",
      "name": "Entregador Silva",
      "document": "98765432100",
      "type": "FIXED",
      "value": 10.00
    }
  ]
}

Result after payment confirmation:

Recipient	Type	Calculation	Amount
Loja do João	70%	R$ 200 x 70%	R$ 140.00
Marketplace Ltda	20%	R$ 200 x 20%	R$ 40.00
Entregador Silva	Fixed	—	R$ 10.00
Remaining balance	—	R$ 200 - R$ 190	R$ 10.00

Single split with immediate execution: as soon as the payment is confirmed, the transfer to the provider is made automatically (without waiting for the account's frequency).

{
  "transaction": {
    "value": 350.00,
    "description": "Serviço de consultoria - Projeto Alpha",
    "externalId": "SVC-ALPHA-001",
    "generateQrCode": true
  },
  "payer": {
    "fullName": "Empresa XYZ S.A.",
    "document": "55666777000199"
  },
  "splits": [
    {
      "pixKey": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
      "pixKeyType": "RANDOM",
      "name": "Consultor Freelancer",
      "document": "12345678901",
      "type": "PERCENTAGE",
      "value": 80,
      "immediate": true
    }
  ]
}

See the Payment Split guide for full details on types, calculations, frequencies, and advanced examples.

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.

{
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-in",
  "method": "POST",
  "code": "PUB_VALIDATION_ERROR",
  "message": "Validation failed",
  "userMessage": "Dados da requisição inválidos",
  "details": {
    "errors": [
      "transaction.value must not be less than 0.01",
      "transaction.description should not be empty"
    ]
  }
}

Common causes:

transaction.value less than 0.01 or with more than 2 decimal places
transaction.description or transaction.externalId empty
expirationTime less than 300 (5 min) or greater than 604800 (7 days)
Sum of splits exceeds the transaction amount

Token missing, expired, or invalid.

{
  "statusCode": 401,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-in",
  "method": "POST",
  "code": "PUB_UNAUTHORIZED",
  "message": "Unauthorized",
  "userMessage": "Token de autenticação inválido ou expirado"
}

Failed to communicate with the PIX provider. Try again.

{
  "statusCode": 500,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "path": "/api/pix/cash-in",
  "method": "POST",
  "code": "PUB_INTERNAL_ERROR",
  "message": "Failed to generate PIX charge",
  "userMessage": "Erro ao gerar cobrança PIX. Tente novamente em alguns instantes.",
  "errorId": "err_a1b2c3d4"
}