Skip to content

Criar Cobrança Pix ​

Cria uma cobrança Pix com QR Code para pagamento instantâneo.

POST /api/charge/pix ​

Endpoint ​

POST https://api.divipay.com.br/api/charge/pix

Headers ​

HeaderValorObrigatório
AuthorizationBearerSim
Content-Typeapplication/jsonSim

Body Parameters ​

CampoTipoDescriçãoObrigatório
amountnumberValor da cobrança em reaisSim
descriptionstringDescrição (máx. 25 caracteres)Sim
referenceIdstringID de referência do seu sistemaSim
callbackUrlstringURL para receber webhookSim
expirationSecondsnumberTempo de expiração em segundosSim
customerIdstringID da subconta (opcional)Não
feestringTaxa fixa a ser cobradaNão
clientobjectDados do clienteSim
itensarrayLista de itens da cobrançaSim

referenceId não é idempotente

O referenceId não é único e não evita duplicidade: reenviar a mesma requisição cria uma nova cobrança (novo id e novo QR Code). Controle retentativas do seu lado. Idempotência automática só existe na Cobrança em Lote (header Idempotency-Key).

Objeto Client ​

CampoTipoDescriçãoObrigatório
namestringNome do cliente (máx. 255 caracteres)Sim
documentstringCPF ou CNPJ (somente números)Sim
emailarray/stringEmail do clienteSim
phonestringTelefone com DDD (somente números)Sim
ipstringIP do clienteNão
fingerprintstringFingerprint do dispositivo (antifraude). OpcionalNão

Objeto Item ​

CampoTipoDescriçãoObrigatório
namestringNome do itemSim
quantitynumberQuantidadeSim
unitPricenumberValor unitárioSim
feePercentnumberPercentual de taxa para splitSim

Exemplo de Requisição ​

bash
curl -X POST https://api.divipay.com.br/api/charge/pix \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "description": "Pagamento Pedido #123",
    "referenceId": "pedido-123",
    "callbackUrl": "https://seusite.com/webhook",
    "expirationSeconds": 3600,
    "client": {
      "name": "João Silva",
      "document": "12345678901",
      "email": "joao@email.com",
      "phone": "11999999999",
      "ip": "203.0.113.10"
    },
    "itens": [
      {
        "name": "Produto A",
        "quantity": 2,
        "unitPrice": 50.00,
        "feePercent": 0
      }
    ]
  }'
javascript
const response = await fetch('https://api.divipay.com.br/api/charge/pix', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SEU_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 100.00,
    description: 'Pagamento Pedido #123',
    referenceId: 'pedido-123',
    callbackUrl: 'https://seusite.com/webhook',
    expirationSeconds: 3600,
    client: {
      name: 'João Silva',
      document: '12345678901',
      email: 'joao@email.com',
      phone: '11999999999',
      ip: '203.0.113.10'
    },
    itens: [
      {
        name: 'Produto A',
        quantity: 2,
        unitPrice: 50.00,
        feePercent: 0
      }
    ]
  })
});

const data = await response.json();
python
import requests

response = requests.post(
    'https://api.divipay.com.br/api/charge/pix',
    headers={
        'Authorization': 'Bearer SEU_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'amount': 100.00,
        'description': 'Pagamento Pedido #123',
        'referenceId': 'pedido-123',
        'callbackUrl': 'https://seusite.com/webhook',
        'expirationSeconds': 3600,
        'client': {
            'name': 'João Silva',
            'document': '12345678901',
            'email': 'joao@email.com',
            'phone': '11999999999',
            'ip': '203.0.113.10'
        },
        'itens': [
            {
                'name': 'Produto A',
                'quantity': 2,
                'unitPrice': 50.00,
                'feePercent': 0
            }
        ]
    }
)

data = response.json()

Resposta de Sucesso ​

Status: 201 Created

json
{
  "id": "8f7c6a2d-4a1b-4de8-9f2d-1e84f7b80c11",
  "status": "PENDING",
  "amount": 100.00,
  "description": "Pagamento Pedido #123",
  "referenceId": "pedido-123",
  "qrCode": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-42661417400052040000530398654041.005802BR5913DIVIPAY LTDA6009SAO PAULO62070503***63041D3D",
  "qrCodeImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "pixCopyPaste": "00020126580014br.gov.bcb.pix0136123e4567...",
  "expiresAt": "2024-11-04T16:00:00.000Z",
  "createdAt": "2024-11-04T15:00:00.000Z"
}

Exibindo o QR Code ​

Opção 1: Imagem Base64 ​

html
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." alt="QR Code Pix" />

Opção 2: Código Pix Copia e Cola ​

html
<div>
  <p>Ou copie o código Pix:</p>
  <input 
    type="text" 
    value="00020126580014br.gov.bcb.pix..." 
    readonly 
    onclick="this.select()"
  />
  <button onclick="copyToClipboard()">Copiar</button>
</div>

<script>
function copyToClipboard() {
  const input = document.querySelector('input');
  input.select();
  document.execCommand('copy');
  alert('Código Pix copiado!');
}
</script>

Split de Pagamento ​

Para dividir o pagamento com uma subconta, use o campo customerId e configure a taxa:

json
{
  "customerId": "5a4c2b18-8f01-49cc-9e3d-2b3b7f1d4e66",
  "fee": "5.00",
  "amount": 100.00,
  // ... outros campos
}

Neste exemplo:

  • R$ 5,00 ficam na conta principal
  • R$ 95,00 vão para a subconta

SPLIT INVERSO

Use valor negativo no fee para inverter o split. Exemplo: "fee": "-5.00" envia R$ 5,00 para a conta principal e R$ 95,00 para a subconta.

Webhook ​

Quando o pagamento for confirmado, você receberá:

json
{
  "status": "APPROVED",
  "id": "8f7c6a2d-4a1b-4de8-9f2d-1e84f7b80c11",
  "txId": "E1234567890123456789012345678901",
  "transactionCode": "E1234567890123456789012345678901",
  "referenceId": "pedido-123",
  "amount": 100.00,
  "type": "PIX",
  "chargeType": "PIX"
}

Respostas de Erro ​

403 Forbidden ​

Token inválido ou expirado.

json
{
  "statusCode": 403,
  "message": "Forbidden"
}

400 Bad Request ​

Dados inválidos na requisição.

json
{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    "amount must be a positive number",
    "client.document must be a valid CPF or CNPJ"
  ]
}

Exemplo Completo ​

javascript
async function createPixCharge(orderId, amount, customer) {
  try {
    const response = await fetch('https://api.divipay.com.br/api/charge/pix', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        amount,
        description: `Pedido #${orderId}`,
        referenceId: orderId,
        callbackUrl: `${process.env.BASE_URL}/webhook/divipay`,
        expirationSeconds: 3600, // 1 hora
        client: {
          name: customer.name,
          document: customer.cpf,
          email: customer.email,
          phone: customer.phone,
          ip: customer.ip
        },
        itens: customer.cart.map(item => ({
          name: item.name,
          quantity: item.quantity,
          unitPrice: item.price,
          feePercent: 0
        }))
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    const charge = await response.json();
    
    return {
      chargeId: charge.id,
      qrCode: charge.qrCodeImage,
      pixCode: charge.pixCopyPaste,
      expiresAt: charge.expiresAt
    };
    
  } catch (error) {
    console.error('Erro ao criar cobrança:', error);
    throw error;
  }
}

Próximos Passos ​

Documentação da API DiviPay