Gerar cobrança PIX

Cria uma cobrança PIX e retorna o ID. Com esse ID você obtém o QR Code (base64, SVG ou URL) para o cliente pagar.

Overview

Este endpoint inicia o fluxo de recebimento via PIX. Após criar a cobrança, use Obter QR Code para gerar o QR no formato desejado.

Requisitos: API Key com escopo pix:write; corpo em JSON com amount em centavos.

Fluxo

Criar cobrança → GET /pix/{id}/qrcode → exibir QR ao cliente → consultar status ou receber webhook pix.received.

Endpoint

POSTPOST /pix

Base URL:https://api.onnixpay.com/api/v1/sdk

Headers

Header	Obrigatório	Descrição
X-API-Key	Sim	Sua API Key (obrigatório).
Content-Type	Sim	Obrigatório para POST com body.

Body Parameters

Todas as propriedades do corpo da requisição, com tipo, obrigatoriedade, restrições e exemplo.

Campo	Tipo	Obrigatório	Descrição	Enum	Exemplo
amount	number	Sim	Valor da cobrança em centavos. Ex.: 10000 = R$ 100,00. Utilizado para gerar o QR Code PIX e exibir ao pagador.Inteiro positivo. Mínimo: 1. Máximo: (definir).	—	5000
description	string	Não	Descrição ou identificador exibido para o pagador e para sua conciliação interna.Máx. 140 caracteres.	—	Pedido #1234
externalId	string	Não	ID único do seu sistema para conciliação. Deve ser único por cobrança.Recomendado formato alfanumérico. Evitar caracteres especiais.	—	ordem-abc-123

Exemplo cURL

cURL

curl -X POST "https://api.onnixpay.com/api/v1/sdk/pix" \
  -H "X-API-Key: ox_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 5000,
  "description": "Pedido #1234",
  "externalId": "ordem-abc-123"
}'

Response — Sucesso (201)

JSON

{
  "id": "pix_xyz789",
  "status": "pending",
  "amount": 5000,
  "description": "Cobrança PIX",
  "createdAt": "2025-02-09T12:00:00.000Z"
}

Campos da resposta

Campo	Tipo	Descrição
id	string	Identificador único da cobrança PIX. Use em GET /pix/{id}/qrcode e GET /pix/{id}.
status	string	Status atual. Valores: pending (aguardando pagamento), completed, cancelled.
amount	number	Valor em centavos (eco do request).
description	string	Descrição informada na criação.
createdAt	string	Data e hora de criação em ISO 8601 (UTC).

Status codes e erros comuns

Status	Código	Mensagem
400	INVALID_REQUEST	Payload inválido ou campos obrigatórios faltando (ex.: amount).
401	INVALID_API_KEY	Chave de API inválida ou ausente.
429	RATE_LIMIT_EXCEEDED	Limite de criações PIX por minuto excedido.

Exemplo de resposta de erro

JSON

{
  "code": "INVALID_REQUEST",
  "message": "Os dados enviados são inválidos.",
  "details": { "field": "amount", "reason": "Deve ser um número positivo." }
}

Observações e boas práticas

Guarde o id retornado para obter o QR Code e consultar o status. A API Key deve ser mantida em variável de ambiente e nunca exposta no frontend.

Headers

X-API-Key: ox_sua_chave_aqui
Content-Type: application/json

Request body (JSON)

{
  "amount": 5000,
  "description": "Pedido #1234",
  "externalId": "ordem-abc-123"
}

cURL

curl -X POST "https://api.onnixpay.com/api/v1/sdk/pix" \
  -H "X-API-Key: ox_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 5000,
  "description": "Pedido #1234",
  "externalId": "ordem-abc-123"
}'

Response (201)

{
  "id": "pix_xyz789",
  "status": "pending",
  "amount": 5000,
  "description": "Cobrança PIX",
  "createdAt": "2025-02-09T12:00:00.000Z"
}