Quickstart

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

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)

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"]
  }'

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.

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.

Comece aqui

Pré-requisitos

Fluxo completo

Próximos passos

Cobrança no cartão

Entender os webhooks

​Pré-requisitos

​Fluxo completo

​Próximos passos

Cobrança no cartão

Entender os webhooks

Pré-requisitos

Fluxo completo

Próximos passos