Primeira cobrança

Inscreva-se para receber o pagamentoCopiar link da seção

Cadastre uma URL do seu backend para receber o evento charge.paid. Faça isso uma vez, não a cada cobrança.

curl -X POST "https://api.gates2b.com/webhook-subscriptions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscribedEvents": ["charge.paid"],
    "callbackUrl": "https://minhaloja.com.br/webhooks/pagamentos"
  }'

Guarde o secret da resposta: ele aparece só agora e serve para verificar a assinatura de cada entrega. Detalhes em Webhooks.

Crie a cobrançaCopiar link da seção

curl -X POST "https://api.gates2b.com/charge" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "grossAmount": "49.90",
    "currency": "BRL",
    "paymentMethod": "PIX",
    "externalReference": "pedido-1042",
    "description": "Pedido 1042"
  }'

grossAmount é string com duas casas decimais. externalReference é o seu identificador do pedido: ele volta no webhook e evita que você precise guardar o id da cobrança para conciliar.

Mostre o pagamento ao clienteCopiar link da seção

Com paymentMethod: "PIX", a resposta é a tentativa de pagamento já criada: o id é da tentativa e o id da cobrança vem em chargeId. Use um dos dois caminhos:

• Checkout pronto: redirecione o cliente para checkoutUrl.
• Na sua tela: exiba checkoutMeta.qr_image (imagem em base64) e ofereça o copia e cola de checkoutMeta.emv.

{
  "id": "8d3f2a61-4c0b-4e7a-9b15-2f6e1c9a7d40",
  "chargeId": "01JC8Z3R5W7Y9A1C3E5G7J9K2M",
  "status": "PROCESSING",
  "paymentMethod": "PIX",
  "checkoutMeta": {
    "url": "https://pay.gates2b.com/01JC8Z3R5W7Y9A1C3E5G7J9K2M",
    "emv": "00020101021226810014br.gov.bcb.pix...",
    "qr_image": "data:image/png;base64,iVBORw0KGgo..."
  },
  "checkoutUrl": "https://pay.gates2b.com/01JC8Z3R5W7Y9A1C3E5G7J9K2M"
}

Confirme pelo webhookCopiar link da seção

Quando o cliente paga, a sua URL recebe um POST com o evento charge.paid. Verifique a assinatura, marque o pedido como pago e responda 2xx. Qualquer outra resposta faz a entrega ser repetida.

Use o webhook como fonte da verdade. Não libere o pedido pelo retorno do navegador do cliente.