Skip to main content
Este guia leva você de zero a um PIX pago. Ao final, você terá autenticado, criado uma cobrança e recebido a confirmação de pagamento por webhook.

​
Pré-requisitos

Antes de começar, você precisa de:
  • Uma API key (public + secret), gerada no painel da sua empresa. Veja Autenticação.
  • Um endpoint público HTTPS para receber os webhooks (pode ser um túnel local como ngrok durante os testes).

​
Fluxo completo

1

Autenticar

Troque sua API key por um token de acesso. Use o token no header Authorization das próximas chamadas.
TOKEN=$(curl -s -X POST https://api.ephra.io/auth \
  -u "$PUBLIC:$SECRET" | jq -r .token)
2

Cadastrar o webhook (uma vez)

Registre a URL que receberá as notificações. Guarde o signatureSecret retornado.
curl -s -X POST https://api.ephra.io/v1/webhook \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seusite.com/webhooks/ephra",
    "events": ["transaction_created", "transaction_paid"]
  }'
3

Criar a cobrança PIX

Gere o QR Code. A resposta traz o emv (copia e cola) e o qrCode (imagem PNG em base64) para o cliente pagar.
curl -s -X POST https://api.ephra.io/v1/pix/in/qrcode \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amountInCents": 10000,
    "description": "Pedido #1234",
    "customer": {
      "name": "Maria Silva",
      "email": "maria@email.com",
      "documentType": "cpf",
      "document": "12345678909"
    }
  }'
A transação nasce com status: "pending". Guarde o data.id para correlacionar o webhook.
4

Receber a confirmação

Quando o cliente pagar, seu endpoint recebe um POST com event: "transaction_paid" e transaction.status: "paid". Esse é o gatilho para liberar o pedido.
{
  "event": "transaction_paid",
  "transaction": { "id": "clxabc123def456", "amount": 10000, "status": "paid" }
}
Você recebe transaction_created quase imediatamente (status pending) e transaction_paid quando o pagamento for confirmado. Trate seu endpoint de forma idempotente — deduplique pelo transaction.id.

​
Próximos passos

Cobrança no cartão

Tokenize o cartão e cobre em até 12 parcelas.

Entender os webhooks

Conheça o modelo de eventos, validação de assinatura e idempotência.