Quickstart - Ephra

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. A Ephra testa a URL com um POST no momento do cadastro, então ela já precisa estar no ar.

curl -s -X POST https://api.ephra.io/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seusite.com/webhooks/ephra",
    "events": ["transaction_created", "transaction_paid"],
    "name": "Quickstart"
  }'

{
  "success": true,
  "data": {
    "id": 31,
    "name": "Quickstart",
    "url": "https://seusite.com/webhooks/ephra",
    "events": ["transaction_created", "transaction_paid"],
    "isActive": true,
    "productIds": [],
    "offerIds": [],
    "signatureSecretMasked": "••••••••8ebf",
    "mtlsCapable": false,
    "createdAt": "2026-09-12T07:47:59.039Z",
    "updatedAt": "2026-09-12T07:47:59.039Z"
  }
}

Cadastre uma vez só. A rota legada POST /v1/webhook, no singular, grava na mesma coleção: cadastrar nas duas cria dois webhooks para a mesma URL e cada evento chega em dobro. Detalhes em Plataforma.

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.

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, a política de retentativas e como proteger o seu endpoint.

​Pré-requisitos

​Fluxo completo

​Próximos passos

Cobrança no cartão

Entender os webhooks

Pré-requisitos

Fluxo completo

Próximos passos