API de cupones
de tarjeta Waycard

1Cómo funciona

• Con el saldo a 0, /emitir responde 402 SIN_SALDO y no se crea nada.
• Si anulas un cupón antes de que se canjee, vuelve a tu saldo. Uno ya canjeado no se puede anular.
• El cupón es al portador: quien tenga el código puede canjearlo. Entrégalo por un canal seguro.

2Credenciales

El secreto se muestra una sola vez. Si lo pierdes, pide una rotación: las credenciales anteriores dejan de funcionar al instante.

Opcionalmente puedes darnos las IPs desde las que llamarás (lista blanca) y una URL de webhook.

3Firma de las peticiones

Todas las peticiones llevan tres cabeceras:

X-Cupon-Key:  <key>
X-Cupon-Ts:   <unix epoch, seconds, UTC>
X-Cupon-Sign: HMAC_SHA256(secret, rawBody + X-Cupon-Ts)   // hex

• rawBody es exactamente el texto JSON que envías (los mismos bytes). Serializa una vez, firma ese texto y envía ese mismo texto.
• En GET no hay cuerpo: se firma solo el timestamp.
• Se admiten ±5 minutos de desvío. Si recibes «X-Cupon-Ts fuera de ventana», revisa el reloj de tu servidor (NTP).
• Content-Type: application/json en las peticiones POST.

Ejemplos

import crypto from 'crypto';

const BASE = 'https://api.waycard.info/v2/cupon';
const KEY = process.env.WAYCARD_CUPON_KEY;
const SECRET = process.env.WAYCARD_CUPON_SECRET;

async function call(method, path, body) {
  const raw = body ? JSON.stringify(body) : '';
  const ts = String(Math.floor(Date.now() / 1000));
  const sign = crypto.createHmac('sha256', SECRET).update(raw + ts).digest('hex');
  const res = await fetch(BASE + path, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'X-Cupon-Key': KEY, 'X-Cupon-Ts': ts, 'X-Cupon-Sign': sign,
    },
    body: body ? raw : undefined,
  });
  return { status: res.status, ...(await res.json()) };
}

// Issue a coupon after charging order 12345
const r = await call('POST', '/emitir', { origen_ref: 'order-12345' });
if (r.ok) console.log(r.codigo_visible, r.caduca, r.cupo_restante);
else if (r.status === 402) console.log('No balance left: top up with Waycard');

function waycardCoupon(string $method, string $path, ?array $body = null): array {
    $raw  = $body === null ? '' : json_encode($body, JSON_UNESCAPED_UNICODE);
    $ts   = (string)time();
    $sign = hash_hmac('sha256', $raw . $ts, getenv('WAYCARD_CUPON_SECRET'));
    $ch = curl_init('https://api.waycard.info/v2/cupon' . $path);
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 15,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'X-Cupon-Key: '  . getenv('WAYCARD_CUPON_KEY'),
            'X-Cupon-Ts: '   . $ts,
            'X-Cupon-Sign: ' . $sign,
        ],
        CURLOPT_POSTFIELDS     => $body === null ? null : $raw,
    ]);
    $res  = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    return ['status' => $code] + (json_decode($res, true) ?: []);
}

$r = waycardCoupon('POST', '/emitir', ['origen_ref' => 'order-12345']);

import hmac, hashlib, json, os, time, requests

BASE = 'https://api.waycard.info/v2/cupon'
KEY, SECRET = os.environ['WAYCARD_CUPON_KEY'], os.environ['WAYCARD_CUPON_SECRET']

def call(method, path, body=None, params=None):
    raw = json.dumps(body, separators=(',', ':')) if body is not None else ''
    ts = str(int(time.time()))
    sign = hmac.new(SECRET.encode(), (raw + ts).encode(), hashlib.sha256).hexdigest()
    r = requests.request(method, BASE + path, params=params, data=raw or None, timeout=15,
                         headers={'Content-Type': 'application/json',
                                  'X-Cupon-Key': KEY, 'X-Cupon-Ts': ts, 'X-Cupon-Sign': sign})
    return r.status_code, r.json()

status, r = call('POST', '/emitir', {'origen_ref': 'order-12345'})

4Endpoints

{
  "ok": true,
  "codigo": "WAY9WZJA3K7M2P5R8T",
  "codigo_visible": "WAY-9WZJ-A3K7-M2P5-R8T",
  "caduca": "2027-09-28",
  "estado": "EMITIDO",
  "reemitido": false,
  "cupo_restante": 41,
  "marca": "acme"
}

{ "ok": true, "anulado": true, "cupo_restante": 42 }

{
  "ok": true,
  "origen": "acme",
  "prepago": true,
  "cupo_restante": 42,
  "caduca_dias_defecto": 365,
  "marca": "acme",
  "cupones": { "total": 58, "sin_usar": 20, "canjeados": 35, "anulados": 3, "caducados": 0 }
}

{
  "ok": true, "existe": true, "origen_ref": "order-12345",
  "codigo": "WAY9WZJA3K7M2P5R8T", "codigo_visible": "WAY-9WZJ-A3K7-M2P5-R8T",
  "estado": "CANJEADO",
  "caduca": "2027-09-28",
  "canjeado_el": "2026-10-02 18:41:07",
  "creado": "2026-09-28 12:00:00",
  "marca": "acme"
}

5Webhook de canje

Si nos das una URL https, te avisamos cuando se canjee uno de tus cupones, firmado con tus credenciales:

POST <your webhook>
X-Cupon-Key:  <your key>
X-Cupon-Ts:   <epoch>
X-Cupon-Sign: HMAC_SHA256(your secret, body + ts)

{ "codigo": "WAY9WZJA3K7M2P5R8T", "canjeado_el": "2026-10-02 18:41:07" }

Verifica la firma igual que nosotros verificamos la tuya. Se envía una vez, sin reintentos: si necesitas certeza, consulta /estado.

6Buenas prácticas

• Idempotencia: usa siempre el mismo origen_ref para el mismo cobro. Ante un timeout, repite la llamada tal cual.
• Secreto: en variables de entorno o en un gestor de secretos, nunca en el código ni en el front.
• Saldo: consulta /saldo antes de una campaña grande y avisa a Waycard con antelación para recargar.
• Reloj: mantén NTP en tu servidor; la firma caduca a los 5 minutos.
• Códigos: no los envíes por canales abiertos ni los guardes en logs. Son al portador.