Cobranças

Criar cobrança

Cria uma cobrança e gera um PIX dinâmico na chave do Merchant. Retorna o br_code (copia-e-cola) pronto para exibir ao pagador.

POST/v1/charges

Headers

x-api-keystringobrigatório

Sua chave de API com escopo charge:write.

Idempotency-Keystringobrigatório

Chave única da operação (mín. 8 caracteres). Reenvios retornam a mesma cobrança.

Corpo da requisição

amountintegerobrigatório

Valor em centavos, positivo (R$ 25,99 = 2599).

methodenumopcionaldefault: pix

Método de pagamento. Hoje apenas pix é funcional; boleto e card retornam 422.

referencestringopcional

Identificador livre do seu lado (máx. 140 chars). Ecoado na resposta e nos webhooks.

descriptionstringopcional

Descrição exibível da cobrança (máx. 140 chars).

expires_inintegeropcionaldefault: 3600

Validade do QR em segundos (60 a 604800).

pix_keystringopcional

Chave PIX do Merchant a usar. Se omitida, usamos a chave ativa mais antiga.

webhook_urlstring (url)opcional

URL que recebe os eventos desta cobrança (além dos webhooks configurados do Merchant).

webhook_secretstringopcional

Segredo usado para assinar o webhook desta cobrança (HMAC). Veja verificar assinatura.

payerobjectopcional

Dados opcionais do pagador solicitado: name e document (CPF/CNPJ). Ecoado como payer_request; depois de paga, o campo payer passa a trazer quem de fato pagou, segundo o banco.

O fluxo de pagamento

Exiba o br_code como QR ou botão copia-e-cola. Quando o PIX entrar, a cobrança vira paid e enviamos o evento charge.paid para o seu webhook_url, com o reference que você mandou e o payer real identificado pelo banco.

Requisição

curl https://apiv2.onnixpay.com/v1/charges \
  -X POST \
  -H "x-api-key: sk_live_sua_chave_aqui" \
  -H "Idempotency-Key: pedido-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2599,
    "method": "pix",
    "reference": "pedido-1042",
    "description": "Plano Pro mensal",
    "expires_in": 3600,
    "webhook_url": "https://sualoja.com/webhooks/onnix",
    "webhook_secret": "whsec_minha_chave_secreta",
    "payer": {
      "name": "Maria Souza",
      "document": "12345678909"
    }
  }'

Resposta

{
  "id": "019e8f03-2d48-7f9b-9d8e-eb22404754b2",
  "object": "charge",
  "status": "pending",
  "amount": 2599,
  "currency": "BRL",
  "method": "pix",
  "reference": "pedido-1042",
  "payer": { "name": "Maria Souza", "document": "12345678909" },
  "payer_request": { "name": "Maria Souza", "document": "12345678909" },
  "pix": {
    "br_code": "00020101021226930014br.gov.bcb.pix...6304CACD",
    "txid": "kk6g232xel65a0daee4dd13kk4000637343",
    "end_to_end_id": null
  },
  "webhook_url": "https://sualoja.com/webhooks/onnix",
  "expires_at": "2026-06-03T20:16:32.703Z",
  "paid_at": null,
  "created_at": "2026-06-03T19:46:33.585Z"
}

AnteriorO objeto Charge Próximo Consultar cobrança