API de Peptide-Pay

Peptide-Pay soporta cuatro modos de integración. Elige el que encaje con tus restricciones; la API por debajo es la misma.

Tres pasos: crear una sesión, redirigir al cliente, manejar el webhook. El ejemplo de abajo es una ruta de checkout Node.js lista para producción.

// Create a checkout session and redirect your customer.
// Authorization resolves the merchant wallet server-side — no wallet in the body.

const res = await fetch('https://peptide-pay.com/api/v1/checkout/init', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.PEPTIDEPAY_API_KEY}`, // sk_live_…
  },
  body: JSON.stringify({
    amount_cents: 5000,                       // €50.00 — integer, in cents
    currency: 'EUR',                          // EUR, USD, GBP, CAD, AUD, CHF
    email: 'buyer@example.com',               // optional, shown in checkout
    success_url: 'https://mystore.com/success',
    cancel_url:  'https://mystore.com/cart',
    webhook_url: 'https://mystore.com/api/peptidepay-webhook',
    metadata: { order_id: '1234' },
  }),
});

const { id, url, tracking_number } = await res.json();
// => { id: 'cs_abc…', url: 'https://peptide-pay.com/session/cs_abc…',
//      tracking_number: '0x…', provider: 'gateway', status: 'pending', … }

// Redirect your customer to the hosted checkout.
return Response.redirect(url, 303);

Ese es todo el happy path. El cliente aterriza en un checkout hospedado en , elige tarjeta o cripto, y tu webhook se dispara en menos de 30s tras el pago.

Dos esquemas, según el modo de integración:

Base URL: . Todos los endpoints hablan JSON, devuelven un objeto en éxito y un en 4xx/5xx.

Cuando una sesión llega a un estado terminal hacemos POST de un evento JSON firmado a la que configuraste (por sesión o en el dashboard). Parsea siempre el body de la request para verificar la firma — re-serializar JSON reordena las claves y rompe el HMAC.

POST /your-endpoint  HTTP/1.1
Host: mystore.com
Content-Type: application/json
x-peptidepay-signature: t=1745300551,v1=3f9b5c1e8a7d…    ← HMAC-SHA256, hex

{
  "event":      "order.paid",
  "session_id": "cs_abc123",
  "order_id":   "1234",
  "address_in": "0xAb12…",
  "status":     "paid",
  "amount":     5000,
  "currency":   "EUR",
  "txid":       "0xfa89b2…",
  "paid_at":    "2026-04-23T10:02:31.000Z",
  "attempt":    1
}

Hoy solo se entrega — las sesiones expired y failed son observables vía (status pasa a tras el TTL de 24h; los fallos terminales muestran ). Puede que añadamos push events para ellos en una release futura.

Los merchants con cuenta de signup reciben un secret y cada entrega lleva un header con la forma . Computa y compara en tiempo constante contra . Rechaza cualquier cosa más antigua de 5 minutos.

// Node.js — Express/Next.js route handler
import crypto from 'node:crypto';

const SECRET = process.env.PEPTIDEPAY_WEBHOOK_SECRET; // dashboard → Webhooks

export async function POST(req) {
  const rawBody = await req.text();                 // MUST be the raw bytes
  const header  = req.headers.get('x-peptidepay-signature') ?? '';
  const [ tPart, v1Part ] = header.split(',');
  const t  = tPart?.split('=')[1];
  const v1 = v1Part?.split('=')[1];
  if (!t || !v1) return new Response('bad sig', { status: 400 });

  // Reject replays older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300)
    return new Response('stale', { status: 400 });

  const expected = crypto
    .createHmac('sha256', SECRET)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  const ok =
    v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1, 'hex'), Buffer.from(expected, 'hex'));
  if (!ok) return new Response('invalid sig', { status: 401 });

  const event = JSON.parse(rawBody);
  // Idempotency: dedupe by event.session_id in your DB — retries re-fire
  // the same event (with an incrementing "attempt" field) until you 2xx.
  if (event.event === 'order.paid') {
    await markOrderPaid(event.order_id, event.txid);
  }
  return new Response('ok');
}

Reintentamos respuestas no-2xx (y timeouts > 5s) con backoff exponencial. Seis intentos en total a lo largo de ~42 horas:

• Intento 1 — inmediatamente al confirmarse.
• Intento 2 — +5 minutos.
• Intento 3 — +15 minutos.
• Intento 4 — +1 hora.
• Intento 5 — +4 horas.
• Intento 6 — +12 horas, luego +24 horas (final).

Tras 6 intentos fallidos el evento pasa a dead-letter. Puedes volver a pedir el estado actual en cualquier momento vía .

Veo 'invalid signature' en todas las entregas

Tu framework parseó el body como JSON antes de que lo hashearas. Lee los bytes RAW (Express: express.raw({type:'*/*'}); Next.js: req.text(); Laravel: request()->getContent(); Rails: request.raw_post). Nunca re-serialices antes de hashear.

IP whitelist — ¿desde qué IPs enviáis?

Las entregas salen actualmente de Vercel Edge (IPs dinámicas). No publicamos un rango estático. Si TIENES que hacer whitelist, usa el header de firma como tu auth gate y acepta cualquier IP origen — el HMAC es la verdadera prueba de identidad.

¿HTTPS obligatorio?

Sí. Nos negamos a hacer POST a endpoints http:// (riesgo de confused deputy / replay en plaintext). La URL https gratuita de ngrok funciona para testing local.

Mi endpoint es lento — ¿puedo extender el timeout de 5s?

No. Responde 2xx inmediatamente, luego procesa asíncronamente (cola de jobs, setImmediate, goroutine). Los handlers que bloquean mucho terminan siempre en timeout.

La API es lo bastante pequeña como para que esté perfectamente bien — pero el SDK de Node te da tipos, retries automáticos y un helper que te gestiona la verificación de firma.

// npm install github:kinerette/peptide-pay-sdk

import { PeptidePay } from 'peptide-pay';

const pp = new PeptidePay(process.env.PEPTIDEPAY_API_KEY);

// Create a session
const session = await pp.checkout.create({
  amount_cents: 5000,
  currency: 'EUR',
  customer_email: 'buyer@example.com',
  success_url: 'https://mystore.com/success',
  cancel_url:  'https://mystore.com/cart',
  metadata: { order_id: '1234' },
});

// Retrieve a session
const latest = await pp.sessions.retrieve(session.id);

// Verify + parse a webhook (throws on invalid signature)
app.post('/webhooks/peptidepay', express.raw({ type: '*/*' }), (req, res) => {
  const event = pp.webhooks.constructEvent(
    req.body,
    req.headers['x-peptidepay-signature'],
    process.env.PEPTIDEPAY_WEBHOOK_SECRET,
  );
  // event.event === 'order.paid' (currently the only event delivered)
  res.sendStatus(200);
});

Flat — la comisión completa de Peptide-Pay. Sin suscripción, sin cuota mensual, sin fees de chargeback. Las comisiones del on-ramp de tarjeta (~4.5% cobrados por el procesador upstream) son pass-through — las paga el cliente, nunca tocan tu payout.

Desglose completo con ejemplos en /fees.

Cada cuenta nueva de merchant recibe gratis — el 3% completo se reembolsa a tu wallet en 24h. Úsalos para ensayar el flujo entero end-to-end (tarjeta real, USDC real, webhook real) antes de ir a producción.

• Modo sandbox es automático: las 3 primeras sesiones pagadas por merchant se marcan y califican para auto-refund.
• Tarjeta de dev de MoonPay: , cualquier expiración futura, cualquier CVV, ZIP 10001.
• Testing local de webhook: expón localhost con ngrok, pega la URL en el campo por sesión.

Loop local completo (ngrok)

# 1. Expose your local webhook endpoint
ngrok http 3000

# 2. Copy the https://xxxx.ngrok-free.app URL and paste it into
#    Dashboard → Webhooks → Endpoint URL, OR send it inline:
curl -X POST 'https://peptide-pay.com/api/v1/checkout/init' \
  -H "Authorization: Bearer $PEPTIDEPAY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "amount_cents": 100,
    "currency": "EUR",
    "customer_email": "test+sandbox@yours.com",
    "success_url": "https://yours.com/success",
    "cancel_url":  "https://yours.com/cart",
    "webhook_url": "https://xxxx.ngrok-free.app/webhooks/peptidepay"
  }'

# 3. Open the returned `url`, hit MoonPay's dev test card
#    4242 4242 4242 4242 (any future exp, any CVV).
# 4. Your local endpoint receives the signed POST within ~30s of payment.

Todos los errores comparten la forma . Los status codes son REST estándar.

La sesión está 'paid' en el dashboard pero mi webhook nunca se disparó

Comprueba que webhook_url es accesible por HTTPS pública (cúrlalo desde fuera de tu LAN). Si es correcta, haz polling GET /sessions/{id} para confirmar el status — el dashboard /app muestra stats de entrega (tasa de éxito, conteos). Seis intentos en 42h antes del dead-letter; siempre puedes re-sincronizar por polling.

HMAC mismatch — la firma siempre es inválida

El 99% de las veces: estás hasheando un body re-serializado en vez de los bytes raw. Los frameworks auto-parsean JSON antes de tu handler; necesitas el buffer raw. Next.js: req.text() antes de cualquier .json(). Express: app.use('/webhooks', express.raw({ type: '*/*' }), …). Rails: request.raw_post. Verifica también que computas `HMAC(whsec_secret, t + '.' + rawBody)` — NO solo `HMAC(whsec_secret, rawBody)`. El prefijo del timestamp es obligatorio.

MoonPay dice 'service unavailable in your country'

MoonPay restringe ~20 países (Irán, Corea del Norte, Cuba, lista completa en su web). El provider por defecto es 'gateway' — el smart picker hace auto-fallback a Revolut, Transak o Banxa, que cubren geografías distintas. Si fijaste un provider específico con provider: 'moonpay', quítalo y deja que el router elija.

Mi wallet no recibió USDC tras un evento 'paid'

Revisa polygonscan.com/address/<tu-wallet> por transferencias de USDC (Polygon POS). El settlement llega 97% a ti y 3% a Peptide-Pay - si no ves el 97% entrando, puede que hayas pegado la wallet equivocada en la llamada a init. Re-confirma con GET /sessions/{id} - el campo txid apunta a la transferencia on-chain real.

El cliente fue cobrado dos veces

No debería pasar. Cada sesión tiene un único addressIn de settlement; un segundo pago a la misma dirección se convierte en una sesión separada en nuestro lado y solo acreditamos el primero a tu pedido. Si pasa, captura los dos txids de polygonscan + el id de sesión y escribe a hi@peptide-pay.com - devolvemos el duplicado desde nuestra treasury.

Me sale 502 'Payment infrastructure temporarily unavailable'

Nuestro upstream de settlement está degradado (< 0.5% de las requests). Reintenta en 30s con la misma Idempotency-Key - nuestro cache devuelve la respuesta original en cuanto la wallet mintea. Mira /status para incidentes en vivo.