Documentación

Integra railpay en tu backend

Crea pagos, muestra el checkout y verifica webhooks firmados. Todo lo que necesitas para empezar en TEST.

Quickstart

Cinco pasos para tu primer pago confirmado en sandbox.

  1. 1. Crea una cuenta y completa el onboarding.
  2. 2. Genera una API key TEST en Integración.
  3. 3. Llama a POST /v1/payments con Idempotency-Key y monto en centavos.
  4. 4. Comparte el checkoutUrl o renderiza tu propia UI.
  5. 5. Recibe payment.finished en tu webhook y verifica la firma.

Autenticación

Envía x-api-key: sk_test_... en cada request. Nunca expongas la clave en el navegador.

Base URL
https://railpay-api.kabasys.com

# API key (TEST)
x-api-key: sk_test_...

Idempotencia

Toda creación de pago exige Idempotency-Key. Reutilizar la clave con otro cuerpo devuelve 409.

Crear un pago

El monto va en centavos. La API devuelve la dirección, el monto cripto y el checkout.

Request · POST /v1/payments
curl https://railpay-api.kabasys.com/v1/payments \
  -H "x-api-key: sk_test_..." \
  -H "Idempotency-Key: order-123" \
  -H "content-type: application/json" \
  -d '{
    "amountCents": 1500,
    "asset": "USDT",
    "network": "TRON",
    "externalId": "order-123"
  }'
Response · 201
{
  "id": "01a1fa06-...",
  "status": "AWAITING_PAYMENT",
  "publicStatus": "waiting",
  "amountCents": 1500,
  "asset": "USDT",
  "network": "TRON",
  "cryptoAmount": "15.00000000",
  "address": "T...",
  "checkoutUrl": "https://railpay.../checkout/..."
}

Webhooks

Un endpoint por entorno. Firma HMAC-SHA512 de timestamp.body en x-railpay-signature.

1) Lee x-railpay-signature. 2) Separa t y v1. 3) Calcula HMAC-SHA512 de `${t}.${rawBody}`. 4) Compara en tiempo constante. 5) Rechaza timestamps de más de 5 minutos.

Verificar la firma (Node)
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(",").map((item) => item.split("=")),
  );
  const expected = createHmac("sha512", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

Errores

La API devuelve JSON con code y message. Los errores 5xx son reintentables con backoff.

HTTPCódigoSignificado
401unauthorizedFalta la API key o es inválida.
403forbiddenLa IP no está permitida o el rol no alcanza.
404not_foundEl recurso no existe o no es tuyo.
409conflictIdempotencia reutilizada o límite alcanzado.
429rate_limitedSuperaste el límite de requests.

Límites

5 claves por entorno, 1 webhook por entorno, 120 requests por minuto por clave.

  • · 5 API keys por entorno · 10 por comercio
  • · 1 webhook activo por entorno
  • · 120 requests/min por API key

Sandbox

Usa una clave TEST y POST /v1/sandbox/payments/{id}/pay para simular la confirmación sin red.

curl -X POST https://railpay-api.kabasys.com/v1/sandbox/payments/{id}/pay \
  -H "x-api-key: sk_test_..." \
  -H "content-type: application/json" \
  -d '{}'