Criar Cobrança

Referência do endpoint para gerar uma cobrança Pix imediata com QR Code dinâmico

Criar cobrança imediata

POST /api/v1/pix-charges

Gera uma cobrança Pix imediata e devolve o txid, o código Pix Copia e Cola e a imagem do QR Code em Base64. O txid é gerado pela API — guarde-o para consultar a cobrança, cancelá-la, solicitar devoluções e conciliar as notificações do webhook.

Requer autenticação mTLS. Veja Autenticação.

Request

Headers

Header	Obrigatório	Exemplo
`Content-Type`	sim	`application/json`
`x-transaction-id`	não	`328d5e1a-06dd-4263-8081-0a2ec31c1f9a`

Body

{
  "amount": 400.00,
  "expiration": 3600,
  "description": "Pedido 12345",
  "userReference": "PED-12345",
  "debtor": {
    "naturalPersonIdentification": "77685349051",
    "name": "Fulano Gomes da Silva"
  }
}

Campos

Campo	Tipo	Obrigatório	Descrição
`amount`	number	sim	Valor da cobrança. Mínimo `0.01`
`expiration`	integer	não	Tempo de vida da cobrança em segundos. Padrão: `86400` (24 h)
`description`	string	não	Descrição da cobrança. Máximo 140 caracteres
`userReference`	string	não	Identificador do integrador (ex.: número do pedido), devolvido na consulta e no webhook. Máximo 77 caracteres
`debtor`	object	não	Identificação do devedor — ver abaixo

Campos de `debtor`

O devedor é a pessoa a quem a cobrança é destinada — não necessariamente quem vai efetivamente pagar.

Campo	Tipo	Descrição
`naturalPersonIdentification`	string	CPF do devedor (ex.: `77685349051`)
`legalPersonIdentification`	string	CNPJ do devedor (ex.: `00000000000191`)
`name`	string	Nome do devedor

debtor inteiro é opcional, e nenhum dos três campos é validado — a API não rejeita se ambos os documentos forem enviados juntos, nem exige documento quando name é enviado. Se legalPersonIdentification vier preenchido, ele tem prioridade sobre naturalPersonIdentification internamente.

Response

`201 Created`

{
  "txid": "astra260915120000123cob4A2F9012",
  "calendar": {
    "creationDate": "2026-09-15T14:30:00",
    "expiration": 3600,
    "expirationDate": "2026-09-15T15:30:00"
  },
  "debtor": {
    "naturalPersonIdentification": "77685349051",
    "name": "Fulano Gomes da Silva"
  },
  "amount": 400.00,
  "status": "ACTIVE",
  "pixCopyAndPaste": "astra260915120000123cob4A2F9012|400.00|Pedido 12345",
  "qrCodeBase64": "iVBORw0KGgoAAAANSUhEUgAAAUoAAAFKAQAAAABTUiuoAAAB7klEQVR4nO2bQYr...",
  "description": "Pedido 12345",
  "userReference": "PED-12345",
  "pix": null,
  "devolutionAllowed": false,
  "devolutions": null
}

Campos da resposta

Campo	Tipo	Descrição
`txid`	string	Identificador da cobrança. Use em Consultar/cancelar cobrança e em Devoluções
`calendar.creationDate`	string (date-time)	Momento de criação da cobrança
`calendar.expiration`	integer	Tempo de vida da cobrança em segundos
`calendar.expirationDate`	string (date-time)	Momento em que a cobrança expira
`debtor`	object \| null	Devedor informado na criação
`amount`	number	Valor da cobrança
`status`	string	`ACTIVE` na criação — ver Status da cobrança
`pixCopyAndPaste`	string	Código Pix Copia e Cola. Ambiente sandbox: string mockada, não é um BR Code/EMV válido
`qrCodeBase64`	string	Imagem PNG do QR Code em Base64 (sem prefixo `data:`), gerada a partir de `pixCopyAndPaste`
`description`	string	Descrição informada na criação
`userReference`	string	Referência informada na criação
`pix`	object \| null	Pix recebido. `null` até a cobrança ser paga
`devolutionAllowed`	boolean	Sempre `false` na criação — só fica `true` ao consultar uma cobrança paga
`devolutions`	array \| null	Devoluções da cobrança. `null` até haver alguma

Para exibir o QR Code em uma página web, use <img src="data:image/png;base64,{qrCodeBase64}" />. O mesmo conteúdo pode ser oferecido como texto via pixCopyAndPaste para pagamento no app do banco.

Erros

Status	Significado
`400`	Requisição inválida (`amount` ausente ou menor que `0.01`, `description` acima de 140 caracteres, `userReference` acima de 77)
`401`	Certificado de cliente ausente ou inválido

Criar Cobrança

On this page