Perguntas frequentes

Como obtenho minhas credenciais de API?

A API key (public + secret) é gerada no painel da sua empresa. Use-a na rota POST /auth para obter o token de acesso. O secret só aparece uma vez — guarde-o em um cofre de segredos.

Os valores são em reais ou centavos?

Sempre em centavos. amountInCents: 10000 equivale a R$ 100,00. As taxas em fees também vêm em centavos.

Quanto tempo dura o token de acesso?

O token é de curta duração — a validade vem em expiresIn (milissegundos) na resposta do login. Gere um novo token antes de iniciar suas operações e reutilize-o enquanto for válido. Veja Autenticação.

Qual a diferença entre PIX imediato e PIX com vencimento?

O PIX imediato (/v1/pix/in/qrcode) gera um QR Code para pagamento na hora, sem vencimento. O PIX com vencimento (/v1/pix/in/cob) tem data de vencimento e regras de multa, juros e desconto. Veja PIX.

Como sei que um pagamento foi confirmado?

Pelo webhook transaction_paid (status: "paid"). Esse é o gatilho para liberar o pedido. Evite polling — use webhooks. Como fallback, você pode consultar GET /v1/transactions/{id}.

Preciso confirmar o pagamento na resposta da criação?

Não. PIX e boleto nascem pending. Só libere o pedido quando receber o webhook transaction_paid. Cartão pode resolver na hora (paid/refused), mas confirme via webhook para os casos assíncronos.

Posso enviar dados do cartão direto na cobrança?

Não. Primeiro tokenize em POST /v1/card-token e use o cardToken na cobrança. Número e CVV nunca trafegam na rota de cobrança.

Como garanto que não vou processar o mesmo webhook duas vezes?

Use o campo id do evento (identificador da entrega) para deduplicar. A mesma entrega pode chegar mais de uma vez por retentativa. Veja Idempotência.

Como valido que o webhook veio mesmo da Ephra?

Valide a assinatura HMAC-SHA256 com o signatureSecret do webhook, usando comparação time-safe. Veja Segurança dos webhooks.

O que acontece se meu endpoint estiver fora do ar?

A Ephra reenvia o evento até 3 vezes, com backoff crescente (~8, 15 e 30 min), por até 48 horas. Depois disso, a entrega é marcada como failed.

Recebi 401 mesmo com o token. O que pode ser?

O token pode ter expirado, ou a sessão associada foi encerrada. Faça login novamente e repita a chamada. Confira também se o header está no formato Authorization: Bearer <token>.

Recebi 400 ao criar uma cobrança. O que verificar?

Cheque o amountInCents (inteiro positivo), o documento do cliente (CPF/CNPJ válido) e, se enviar items, se a soma bate com o amountInCents. A mensagem de erro descreve o problema.

Não encontrou sua dúvida?