Ir para o conteúdo

Desenvolvedores

Um POST cobra.Webhook avisa.

API REST, chaves por ambiente e webhooks assinados. Teste tudo no sandbox.

create-payment.sh
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]"
    }
  }'
POST /v1/payments · 201 Created

Verifique a assinatura.Rejeite o que não bater.

HMAC-SHA256 do timestamp e do corpo bruto, comparado em tempo constante.

  • Evento no cabeçalhoX-Webhook-Event. O corpo não tem envelope.
  • Entrega ao menos uma vezDeduplique por X-Webhook-Delivery-Id.
  • 300 segundosJanela recomendada contra replay.
Guia de webhooks
verify-webhook.js
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");
});
HMAC-SHA256 · timingSafeEqual

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.

Cobranças
CentavosResultado
,01Paga, cerca de 5 s depois
,02Fica em aberto
,03Cancelada
,04Expirada
,05Paga
OutrosPaga
Saques
CentavosResultado
,01Concluído
,02Falha: saldo insuficiente no provedor
,03Falha: chave Pix inválida
,04Fica em processamento
OutrosConcluí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.

Guia do sandbox

O contrato da API.Igual em produção.

O que vale em toda chamada.

  • Autenticação

    Bearer com ypk_test_ ou ypk_live_. O prefixo escolhe o ambiente; a URL é a mesma.

  • Escopos

    Cada chave só faz o que pode: payments:write, withdrawals:read, balance:read e outros.

  • Idempotência

    X-Idempotency-Key nos POSTs que criam recurso. Vale 24 h; corpo diferente na mesma chave recebe 409.

  • Erros

    error.code estável, mensagem legível e details por 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

  1. NEW
  2. PROCESSING
  3. CONFIRMED
  4. PAID
  5. PARTIAL_REFUND
  6. REFUNDED

Antes do pagamento

  • PENDING_METHOD_SELECTION
  • EXPIRED
  • CANCELLED

Depois de pago

  • CHARGEBACK
  • MED_FROZEN
  • PENDING_METHOD_SELECTION só 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ó.

TScheckout.ts

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_
Abrir a documentação

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.