Criar Cobrança PIX

Esta seção explica como criar uma nova cobrança PIX e obter o QR Code para pagamento.

Visão Geral

As cobranças PIX permitem que você receba pagamentos através de QR Codes. Quando uma cobrança é criada, você recebe:

• Um código EMV (QR Code) que pode ser exibido para o pagador
• Uma referência única para consultar o status da cobrança
• Informações sobre expiração e metadados da transação

Endpoint

POST /account/{account_id}/charge/pix/create

Cria uma nova cobrança PIX e retorna o QR Code para pagamento.

URL Completa:

https://app.finexis.com.br/api/v1/gateway/account/{account_id}/charge/pix/create

Headers:

Authorization: Bearer {token}
Content-Type: application/json

Parâmetros da URL:

• account_id (obrigatório): ID da conta que receberá o pagamento

Body:

{
  "amount": 0.25,
  "description": "Teste com API Gateway",
  "currency": "BRL",
  "callback_url": "https://mydomain.com/webhook/receive"
}

Campos do Body:

Campo	Tipo	Obrigatório	Descrição
amount	number	✅ Sim	Valor da cobrança (decimal)
description	string	❌ Não	Descrição da cobrança
currency	string	✅ Sim	Moeda (padrão: "BRL")
callback_url	string	❌ Não	URL de notificação Webhook

Exemplo de Requisição:

curl -X POST \
  'https://app.finexis.com.br/api/v1/gateway/account/5/charge/pix/create' \
  -H 'Authorization: Bearer {seu_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 0.25,
    "description": "Pagamento de serviço",
    "currency": "BRL"
  }'

Resposta de Sucesso (200):

{
  "status": "success",
  "message": "Charge created successfully",
  "data": {
    "provider_id": 2,
    "amount": "0.250000000000000000",
    "currency": "BRL",
    "status": "pending",
    "description": "Teste com API Gateway",
    "content": "00020101021226880014br.gov.bcb.pix2566qrcode.microcashif.com.br/pix/e39afecc-497e-46be-8e89-21655baa87055204000053039865802BR5909VITALCRED6005Natal61085905476062070503***63040327",
    "external_id": "33133434-9123-4d24-92ff-280a9c7b63bd",
    "reference": "459747e9ce9c43c3a7fa75d58e",
    "metadata": {
      "emv": "00020101021226880014br.gov.bcb.pix2566qrcode.microcashif.com.br/pix/e39afecc-497e-46be-8e89-21655baa87055204000053039865802BR5909VITALCRED6005Natal61085905476062070503***63040327",
      "amount": 0.25,
      "description": "Teste com API Gateway",
      "uuid": "33133434-9123-4d24-92ff-280a9c7b63bd",
      "nonce": "rZdeD1sPFShjBwbv",
      "reference": "459747e9ce9c43c3a7fa75d58e",
      "sha256": "7b2d9e9a5c64de08d10d09bca84912831b033f554f6ed74a2749c71fedc065b5",
      "hash_schema": ["reference", "amount", "nonce"],
      "expires_in": 3600,
      "expires_at": "2025-11-20T20:46:06.906Z",
      "coust": 0,
      "tx_id": "459747e9ce9c43c3a7fa75d58e",
      "id": 7980114,
      "status": "ACTIVE"
    },
    "account_id": 5,
    "updated_at": "2025-11-20 20:36:06",
    "created_at": "2025-11-20 20:36:06",
    "id": 31
  }
}

Campos Importantes da Resposta

Campo	Descrição
content	Código EMV do QR Code PIX (use para gerar/exibir o QR Code)
reference	Referência única da cobrança (use para consultar status)
external_id	ID externo da cobrança
status	Status da cobrança (pending, paid, etc.)
metadata.expires_at	Data/hora de expiração do QR Code
metadata.expires_in	Tempo de expiração em segundos (padrão: 3600 = 1 hora)

Gerando o QR Code

O campo content contém o código EMV completo do PIX. Você pode usar bibliotecas como:

• JavaScript: qrcode (npm)
• Python: qrcode (pip)
• PHP: endroid/qr-code
• Outras: Qualquer biblioteca que gere QR Codes a partir de strings

Exemplo em JavaScript:

const QRCode = require('qrcode');
const qrCodeData = response.data.content;

QRCode.toDataURL(qrCodeData, (err, url) => {
  if (err) throw err;
  // Use 'url' para exibir o QR Code
});

Expiração

Por padrão, as cobranças PIX expiram em 3600 segundos (1 hora). Após a expiração, o QR Code não pode mais ser usado para pagamento.

Dica

Consulte o status da cobrança periodicamente para verificar se foi paga antes de expirar.

Próximos Passos

Após criar a cobrança:

1. Exiba o QR Code: Use o campo content para gerar e exibir o QR Code
2. Monitore o Status: Use Consultar Status para verificar se foi paga
3. Liste as Cobranças: Use Listar Cobranças para ver todas as cobranças