Y Yuupe Pay API v1Painel
Começando

Início rápido

Do zero ao primeiro Pix pago no sandbox: chave, webhook, pedido e confirmação.

1. Pegue a chave de sandbox

No painel da Yuupe, em Yuupe Pay › Integração, gere uma chave yp_test_…. Ela aparece uma única vez: guarde no cofre de segredos do servidor, nunca no código do navegador.

2. Cadastre o webhook

Na mesma tela, em Webhooks, cadastre a URL https do seu servidor que vai receber os avisos (por exemplo https://loja.exemplo.com/webhooks/yuupe-pay). Copie o segredo: ele assina cada aviso.

Conferir a assinatura (Node.js)
import { createHmac, timingSafeEqual } from 'node:crypto'

// Use o corpo CRU (string/Buffer), antes de qualquer JSON.parse.
export function assinaturaValida(cabecalho, corpoCru, segredo) {
  const partes = Object.fromEntries(String(cabecalho).split(',').map((p) => p.split('=')))
  const t = Number(partes.t)
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false   // mais de 5 min: recusa
  const esperado = createHmac('sha256', segredo).update(`${t}.${corpoCru}`).digest('hex')
  const a = Buffer.from(esperado), b = Buffer.from(partes.v1 ?? '')
  return a.length === b.length && timingSafeEqual(a, b)
}

// Express:
app.post('/webhooks/yuupe-pay', express.raw({ type: 'application/json' }), (req, res) => {
  const cru = req.body.toString('utf8')
  if (!assinaturaValida(req.get('X-Yuupe-Signature'), cru, process.env.YUUPE_PAY_WEBHOOK_SEGREDO)) {
    return res.status(401).end()
  }
  const evento = JSON.parse(cru)
  // descarte repetidos pelo evento.id; depois trate evento.tipo e evento.pedido
  res.status(200).end()
})

Detalhes e PHP em Webhooks.

3. Crie um pedido Pix

O pedido é criado e cobrado na mesma chamada. No Pix, o CPF/CNPJ e o endereço do comprador são obrigatórios.

POST /pedidos
curl -X POST https://yuupe.me/api/v1/pay/pedidos \
  -H "Authorization: Bearer yp_test_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "numero_pedido": "NIC-2026-000123",
    "metodo": "pix",
    "idioma": "pt-BR",
    "comprador": {
      "nome": "Maria Souza",
      "email": "maria@exemplo.com",
      "documento": "529.982.247-25",
      "telefone": "+5561999990000",
      "endereco": {
        "logradouro": "Rua das Flores", "numero": "123", "bairro": "Asa Sul",
        "cidade": "Brasília", "uf": "DF", "cep": "70000-000"
      }
    },
    "itens": [
      { "descricao": "Passaporte Infantil", "quantidade": 2, "valor_unitario_centavos": 7990 }
    ]
  }'
Resposta 201
{
  "id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
  "numero_pedido": "NIC-2026-000123",
  "ambiente": "sandbox",
  "status": "aguardando_pagamento",
  "metodo": "pix",
  "valor_centavos": 15980,
  "pix": {
    "qr_code": "00020101021226770014BR.GOV.BCB.PIX2555api.itau/pix/qr/v2/...",
    "qr_code_imagem": "https://.../qrcode.png",
    "expira_em": "2026-10-17T13:33:00-03:00"
  },
  "motivo": null,
  "criado_em": "2026-10-16T13:33:02-03:00",
  "pago_em": null
}

Mostre pix.qr_code_imagem sobre fundo branco e um botão para copiar pix.qr_code. Veja Pix.

4. Receba a confirmação

Quando o comprador paga, o seu webhook recebe pedido.aprovado, normalmente em poucos segundos. Libere a compra a partir dele. Se o Pix não for pago no prazo, chega pedido.expirado.

Enquanto o QR está na tela, o checkout pode consultar GET /pedidos/{id} a cada 4 a 5 segundos para trocar a tela sozinho. Quem libera a compra continua sendo o servidor.

5. Vá para produção

Gere uma chave yp_live_… e cadastre o webhook de produção (cada ambiente tem os seus endereços e segredos). Rotas e campos são os mesmos. Antes, passe pelo checklist.