Desenvolvedores
Um POST cobra.Webhook avisa.
API REST, chaves por ambiente e webhooks assinados. Teste tudo no sandbox.
curl -X POST https://api.yuvexpay.com/v1/payments \
-H "Authorization: Bearer ypk_test_ab12cd34ef_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: order-1234-attempt-1" \
-d '{
"amount": 49.90,
"methods": ["PIX"],
"currency": "BRL",
"mode": "headless",
"description": "Order #1234",
"externalId": "order-1234",
"expiresInMinutes": 30,
"customer": {
"name": "Pedro Álvares Cabral",
"email": "[email protected]"
}
}'Verifique a assinatura.Rejeite o que não bater.
HMAC-SHA256 do timestamp e do corpo bruto, comparado em tempo constante.
- Evento no cabeçalho
X-Webhook-Event. O corpo não tem envelope. - Entrega ao menos uma vezDeduplique por
X-Webhook-Delivery-Id. - 300 segundosJanela recomendada contra replay.
import crypto from "crypto";
const SKEW_SECONDS = 300;
function verifyWebhook(rawBody, headers, secret) {
const ts = headers["x-webhook-timestamp"];
const sig = headers["x-webhook-signature"];
if (!ts || !sig) return false;
const drift = Math.abs(Math.floor(Date.now() / 1000) - parseInt(ts, 10));
if (drift > SKEW_SECONDS) return false;
const expected = "v1=" + crypto
.createHmac("sha256", secret)
.update(`${ts}.${rawBody}`)
.digest("hex");
const a = Buffer.from(sig);
const b = Buffer.from(expected);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
const rawBody = req.body.toString("utf8");
if (!verifyWebhook(rawBody, req.headers, process.env.WEBHOOK_SECRET)) {
return res.status(401).send("Invalid signature");
}
const eventType = req.headers["x-webhook-event"];
const deliveryId = req.headers["x-webhook-delivery-id"];
const body = JSON.parse(rawBody);
if (alreadyProcessed(deliveryId)) return res.status(200).send("OK");
switch (eventType) {
case "PAYMENT_PAID":
console.log(body.txId, body.amount, body.payer?.document ?? null);
break;
case "WITHDRAWAL_SENT":
console.log(body.txId, body.recipient?.document ?? null);
break;
case "WITHDRAWAL_FAILED":
console.log(body.txId, body.failureReason);
break;
}
res.status(200).send("OK");
});Teste sem dinheiro real.Os centavos decidem.
Com a chave ypk_test_, os centavos do valor escolhem o desfecho de Pix, cartão e boleto.
| Centavos | Resultado |
|---|---|
| ,01 | Paga, cerca de 5 s depois |
| ,02 | Fica em aberto |
| ,03 | Cancelada |
| ,04 | Expirada |
| ,05 | Paga |
| Outros | Paga |
| Centavos | Resultado |
|---|---|
| ,01 | Concluído |
| ,02 | Falha: saldo insuficiente no provedor |
| ,03 | Falha: chave Pix inválida |
| ,04 | Fica em processamento |
| Outros | Concluído |
Para forçar um status na hora, use POST /v1/payments/{id}/simulate.
O sandbox não envia webhooks. Consulte o status ou use Enviar teste no painel.
O contrato da API.Igual em produção.
O que vale em toda chamada.
Autenticação
Bearer com
ypk_test_ouypk_live_. O prefixo escolhe o ambiente; a URL é a mesma.Escopos
Cada chave só faz o que pode:
payments:write,withdrawals:read,balance:reade outros.Idempotência
X-Idempotency-Keynos POSTs que criam recurso. Vale 24 h; corpo diferente na mesma chave recebe 409.Erros
error.codeestável, mensagem legível edetailspor campo.Limites
1.000 GET, 100 POST e 2.000 no total por minuto, por empresa, com cabeçalhos
X-RateLimit-*.Versão
A versão da API fica fixa por chave. Você atualiza quando quiser.
Ciclo da cobrança.Sem adivinhação.
O caminho principal e os desvios possíveis. Os relevantes viram webhook.
Caminho principal
- NEW
- PROCESSING
- CONFIRMED
- PAID
- PARTIAL_REFUND
- REFUNDED
Antes do pagamento
- PENDING_METHOD_SELECTION
- EXPIRED
- CANCELLED
Depois de pago
- CHARGEBACK
- MED_FROZEN
PENDING_METHOD_SELECTIONsó no checkout hospedado.- Boleto vencido ainda pode virar
PAID.
Integre do seu jeito.Com ou sem código.
Escreva você, peça para a IA ou ligue blocos. A API é uma só.
API REST com webhooks assinados.
- Valores em reais, como
49.90 X-Idempotency-Key: repetir nunca cobra duas vezes- Webhook assinado com
HMAC-SHA256 - Sandbox com chave
ypk_test_
Funciona com
- Claude Code
- Cursor
- Codex
- Windsurf
- GitHub Copilot
- v0
- Replit
- n8n
- Make
- Zapier
Sua próxima vendapode cair aqui.
Sem mensalidade. Sem setup. Só a taxa por venda.
Toda conta nasce em sandbox, com chaves de teste.