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. Crea una cuenta y completa el onboarding.
- 2. Genera una API key TEST en Integración.
- 3. Llama a POST /v1/payments con Idempotency-Key y monto en centavos.
- 4. Comparte el checkoutUrl o renderiza tu propia UI.
- 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.
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.
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"
}'{
"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.
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.
| HTTP | Código | Significado |
|---|---|---|
| 401 | unauthorized | Falta la API key o es inválida. |
| 403 | forbidden | La IP no está permitida o el rol no alcanza. |
| 404 | not_found | El recurso no existe o no es tuyo. |
| 409 | conflict | Idempotencia reutilizada o límite alcanzado. |
| 429 | rate_limited | Superaste 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 '{}'