Desarrolladores
Tres llamadas y un webhook.
Gateway es un checkout alojado, así que la integración es deliberadamente pequeña: crea un pedido, envía al cliente a la página y verifica el resultado firmado. Esto es toda la superficie: la interfaz de pago, la lógica de los métodos, 3-D Secure, los wallets y los recibos los construimos y mantenemos al día nosotros.
A grandes rasgos
Contra qué te integras.
- REST sobre HTTPS
- JSON de entrada, JSON de salida
- Claves de API Bearer
- Claves de idempotencia
- Webhooks firmados
- Protección contra replay
- Modo de prueba y modo real
- SDK para iOS y Android
- Plugins para tiendas
- Campos integrados
Inicio rápido
De cero a un pedido pagado.
Todo el camino feliz. Los importes van en unidades menores, las referencias son tuyas y la URL de checkout es a la que rediriges al cliente. La URL base de la API se entrega con tus claves de sandbox: expórtala como PROTOCORE_API_BASE y las llamadas de abajo funcionan tal cual.
Crea el pedido
Una sola llamada con el importe, la divisa y tu propia referencia. La clave de idempotencia la generas tú: una petición repetida devuelve el pedido original en lugar de crear un segundo.
curl -X POST "$PROTOCORE_API_BASE/v1/orders" \
-H "Authorization: Bearer $PROTOCORE_API_KEY" \
-H "Idempotency-Key: 9F21-0716" \
-H "Content-Type: application/json" \
-d '{
"amount": 4900,
"currency": "EUR",
"reference": "9F21-0716",
"line_items": [
{ "name": "Brand identity sprint", "amount": 3850 },
{ "name": "Typeface licensing", "amount": 600 },
{ "name": "Rush delivery", "amount": 400 }
],
"return_url": "https://arcstudio.ro/thanks"
}'Envía al cliente al checkout
La respuesta incluye una URL de checkout en tu propio host de checkout: el que se emite con tu sandbox o tu propio dominio cuando lo apuntes hacia nosotros. Redirige al cliente o ábrela en el SDK; en esa página viven los métodos de pago, los wallets y 3-D Secure, así que no hay nada que construir por tu parte.
{
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"status": "pending",
"checkout_url": "https://<your-checkout-host>/c/2h4Kq9wRz"
}Verifica el resultado firmado
Cuando el pago se completa, llega un evento firmado a tu endpoint. Verifica la firma con tu secreto de webhook antes de fiarte de nada y después gestiona el pedido con la referencia que ya conoces.
{
"type": "order.paid",
"id": "evt_7Ka2Lm",
"created": "2026-07-23T09:41:02Z",
"data": {
"id": "ord_2h4Kq9wRz",
"reference": "9F21-0716",
"amount": 4900,
"currency": "EUR",
"method": "usdc",
"settlement": { "currency": "EUR", "amount": 4900, "rate": "0.9184" }
}
}Referencia
Los endpoints que realmente usarás.
Hay más en la documentación, pero este es el conjunto del que la mayoría de las integraciones no pasa.
Webhooks
De qué se entera tu backend.
Cada evento incluye la referencia del pedido que creaste, así que tu handler puede reducirse a un switch sobre el tipo y una búsqueda en tu propio sistema.
Comprueba la firma antes de fiarte del cuerpo.
Cada envío lleva una marca de tiempo y una firma HMAC sobre el cuerpo sin procesar. Compara en tiempo constante, rechaza lo que supere tu ventana de tolerancia y trata un id de evento duplicado como ya gestionado: reintentamos ante respuestas distintas de 2xx, así que tu handler también debe ser idempotente.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(rawBody, header, secret) {
const [ts, sig] = header.split(",").map((p) => p.split("=")[1]);
const expected = createHmac("sha256", secret)
.update(`${ts}.${rawBody}`)
.digest("hex");
const a = Buffer.from(sig, "hex");
const b = Buffer.from(expected, "hex");
if (a.length !== b.length || !timingSafeEqual(a, b)) return false;
// Reject replays outside a five-minute window.
return Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}Garantías
Las propiedades sobre las que puedes construir.
Creaciones idempotentes
Toda creación de pedido admite una clave de idempotencia. Una petición repetida —tras un timeout, un despliegue o una reentrega de cola— devuelve el pedido original en lugar de cobrar dos veces.
Eventos firmados y protegidos contra replay
Los webhooks llevan una firma HMAC con marca de tiempo y un id de evento estable. Los envíos se reintentan con backoff hasta que tu endpoint responde 2xx, así que una ventana de despliegue no hace perder ningún pago.
Una referencia, de principio a fin
La referencia que aportas al crear el pedido aparece en el checkout, el recibo, el webhook, la liquidación y cualquier reembolso posterior. No hay un segundo identificador que mapear entre sistemas.
El modo de prueba usa el mismo código
Las claves de prueba ejecutan los mismos flujos contra sesiones de prueba. Lo que pasa en test es lo que se despliega: la diferencia está en las claves que envías, no en los endpoints a los que llamas.
Datos de prueba
Cómo probar los caminos que importan.
Cada vía de abajo lleva asociada una tarjeta de prueba, que se indica junto con tus claves al emitir el sandbox. Los números son específicos de cada sandbox y no se publican aquí, para que sigan siendo válidos cuando cambien los rangos de prueba de las redes. El comportamiento es determinista en cualquier caso: un test puede verificar un rechazo con la misma facilidad que un éxito.
Consigue tus claves y empieza.
Un comercio sandbox con claves de API, secretos de webhook y todos los métodos activados, además de la referencia completa, para que tu equipo integre antes de firmar nada.