Guia de integração

​

Venda avulsa no cartão

{
  "customer": {
    "name": "Maria Silva",
    "email": "maria@exemplo.com",
    "phone": { "ddi": "55", "ddd": "11", "number": "999998888" },
    "document": { "type": "cpf", "number": "12345678909" },
    "ip": "203.0.113.10"
  },
  "items": [{ "code": "curso-vitalicio", "description": "Curso vitalício", "quantity": 1, "amount": 69700 }],
  "payments": [{
    "type": "card",
    "amount": 69700,
    "capture_method": "automatic",
    "card": { "number": "...", "holder_name": "MARIA SILVA", "exp_month": "12", "exp_year": "2030", "cvc": "123", "installments": 6 }
  }],
  "metadata": { "order_id": "seu-id-interno" }
}

• Envie capture_method: "automatic". O padrão é manual: o pedido fica em requires_capture e a autorização é cancelada em cerca de 26 h se você não chamar POST /v2/orders/{id}/capture.
• Parcelas não mudam o valor. Se você cobra juros, some-os ao amount dos itens e do pagamento.
• customer.ip é o IP do comprador, usado nos bloqueios de cliente.
• Grave o id do pedido (ord_...) e o payments[].id (cha_...). São eles que chegam nos webhooks; o pedido não devolve o seu metadata.

​

PIX no seu checkout

{
  "customer": { "name": "...", "email": "...", "phone": { "ddi": "55", "ddd": "11", "number": "999998888" } },
  "items": [{ "code": "plano-anual", "description": "Plano anual", "quantity": 1, "amount": 29700 }],
  "payments": [{ "type": "pix", "amount": 29700, "pix_expiration": 1800 }]
}

• A resposta vem em requires_action com next_action.type: "pix_display_qr_code". Mostre next_action.pix.qr_code_url (imagem) e next_action.pix.qr_code (copia e cola).
• pix_expiration é em segundos. next_action.pix.expires_at vem como AAAA-MM-DD HH:MM:SS, no horário de Brasília e sem fuso: converta antes de mostrar a contagem regressiva.
• Atualize o seu banco no webhook order.paid e faça a página consultar o seu servidor. O limite de 120 requisições por minuto vale para a conta inteira, então evite consultar a API em loop.
• Sem pagamento, chega charge.expired. Ofereça um novo PIX.

​

Assinatura

{
  "code": "assinatura-123",
  "interval": "day",
  "interval_count": 30,
  "customer": {
    "name": "...", "email": "...",
    "phone": { "ddi": 55, "ddd": 11, "number": "999998888" },
    "document": { "type": "cpf", "number": "12345678909" }
  },
  "items": [{ "code": "plano-mensal", "description": "Plano mensal", "quantity": 1, "amount": 3900 }],
  "payment": { "type": "card", "card": { "number": "...", "holder_name": "...", "exp_month": "12", "exp_year": "2030", "cvc": "123", "installments": 1 } },
  "metadata": { "user_id": "seu-id-interno" }
}

• Não existe mês de calendário: “mensal” é day × 30 e “anual” é day × 365. Para fixar o dia, ajuste com next-billing-date.
• Na assinatura, customer.document e items[].code são obrigatórios.
• A primeira fatura vem em latest_invoice. Trate o status dela como o de um pedido; o código de verificação da fatura vai em POST /v2/invoices/{id}/confirm.
• No PIX, cada ciclo gera uma fatura com um QR code novo, entregue no invoice.created. Envie esse QR code ao seu cliente.

• Uma renovação recusada é cobrada de novo uma vez por dia, até 3 tentativas. Para o cliente quitar antes, use POST /v2/invoices/{id}/pay.
• O cancelamento (POST /v2/subscriptions/{id}/cancel) é imediato. Se o seu produto mantém o acesso até o fim do período pago, guarde essa data antes.

​

Cupons e descontos

• Não há objeto de cupom: o seu sistema valida o código, os usos e a validade.
• Pedido: envie o preço já com desconto.
• Assinatura: discounts: [{ "type": "percentage", "value": 50, "invoice_number": 1 }]. Sem invoice_number, vale para todas as faturas. Não combina com split.

​

Estorno

​

Antes de ir para produção