Integrar una pasarela de pago en tu app en 10 minutos

Integrar una pasarela de pago conecta tu web o app con un servicio que recibe el pago y avisa a tu backend cuando termina. La integración más simple usa un checkout alojado: tu servidor crea un pago, el cliente paga en la página de la pasarela y un webhook firmado marca el pedido como pagado.

Esta guía recorre ese flujo con la API y los SDKs de OrcaRail, para una app web y una app móvil, en un sandbox sin fondos reales. Los clientes pagan en cripto y tú recibes la stablecoin que elijas, como USDC o USDT.

Cómo funciona la integración con checkout alojado

Paso	Quién	Qué pasa
1. Crear	Tu backend	Crea un payment intent con el importe, el token y la red que recibes, y las URLs de retorno y cancelación
2. Redirigir	Tu app	Envía al cliente a la página de pago alojada
3. Pagar	Cliente	Paga en pay.orcarail.com con su billetera
4. Volver	Tu backend	Completa el intent cuando el cliente llega a tu URL de retorno
5. Webhook	OrcaRail → tu backend	Envía un evento firmado payment_intent.completed; tú entregas el pedido

Tus servidores nunca manejan billeteras, claves privadas ni el monitoreo de la cadena. La redirección del navegador nunca marca un pedido como pagado por sí sola: tu backend consulta la API y solo confía en webhooks firmados.

Antes de empezar

1. Regístrate en app.orcarail.com y completa la configuración guiada.
2. Pulsa Go to sandbox y crea una clave API (ak_test_…). Copia la clave, el secreto y el secreto de firma de webhooks. El secreto se muestra una sola vez. Ver Crear un sandbox.
3. Configura la URL de webhook de la clave, por ejemplo https://yourapp.com/webhooks/orcarail.
4. Elige el token y la red que recibes. Los IDs vienen de GET /payments/networks y GET /payments/networks/:id/tokens. Ver Redes y tokens.

Integra con el SDK de Node.js

Instala el SDK de Node.js:

npm install @orcarail/node

1. Crea un pago y redirige

import OrcaRail from '@orcarail/node'

const orcarail = new OrcaRail(
  process.env.ORCARAIL_API_KEY!, // ak_test_… in the sandbox
  process.env.ORCARAIL_API_SECRET!
)

const intent = await orcarail.paymentIntents.create({
  amount: '100.00',
  currency: 'usd',
  payment_method_types: ['crypto'],
  tokenId: '<token-id>', // e.g. USDC
  networkId: '<network-id>', // e.g. Base
  return_url: 'https://yourapp.com/success',
  cancel_url: 'https://yourapp.com/cancel',
  description: 'Order #12345',
  metadata: { order_id: '12345' },
})

const confirmed = await orcarail.paymentIntents.confirm(intent.id, {
  client_secret: intent.client_secret!,
  return_url: 'https://yourapp.com/success',
})

// Redirect the customer to confirmed.pay_url

2. Completa el pago al volver

Cuando el cliente llega a tu URL de retorno, completa el intent desde tu backend. Esto finaliza el pago y lo hace retirable. Si aún no está confirmado en la cadena, el intent queda en processing; vuelve a llamar a complete más tarde.

const completed = await orcarail.paymentIntents.complete(intent.id)

3. Verifica el webhook

Usa el cuerpo crudo de la petición y la cabecera x-webhook-signature:

app.post(
  '/webhooks/orcarail',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    try {
      const event = orcarail.webhooks.constructEvent(
        req.body,
        req.headers['x-webhook-signature'],
        process.env.ORCARAIL_WEBHOOK_SECRET
      )
      if (event.type === 'payment_intent.completed') {
        // mark the order paid (idempotently)
      }
      res.status(200).json({ received: true })
    } catch (err) {
      res.status(400).send('Invalid signature')
    }
  }
)

Los eventos incluyen livemode. Nunca entregues pedidos reales a partir de eventos con livemode: false. Ver Firmas de webhooks y Eventos de webhooks.

Integra con PHP o Laravel

El mismo flujo funciona con el SDK de PHP, y el paquete Laravel Cashier añade suscripciones cripto a apps Laravel. ¿Sin SDK? Llama directamente a la API REST: ver la referencia de la API.

Pasarela de pago para una app móvil

Una app móvil nunca debe guardar tu secreto de API. Mantén la integración en tu backend:

1. La app pide a tu backend que cree el pago.
2. El backend crea y confirma el intent y devuelve pay_url.
3. La app abre pay_url en un navegador integrado o en el navegador del sistema.
4. El cliente vuelve a tu return_url y tu backend completa el intent.
5. Tu backend recibe el webhook y actualiza la app, por ejemplo con una notificación push o al refrescar.

Prueba la integración en el sandbox

• Las claves de sandbox (ak_test_) solo usan testnets. orcarail.livemode es false.
• Llama a await orcarail.paymentIntents.simulate(id) o pulsa Simulate payment en la página de pago del sandbox para terminar un pago sin billetera. Ver Simular pagos.
• Cuando todo funcione, crea claves live en tu organización live y cambia el token y la red a mainnet. Ver Salir en vivo.

Deja que un agente de IA haga la integración

El servidor MCP de OrcaRail permite que Claude Code, Cursor o Codex creen payment intents, productos y suscripciones por ti, y la documentación está disponible en texto plano para LLMs. Ver Construir con IA.

Preguntas frecuentes

¿Cuánto tarda integrar una pasarela de pago?

Con checkout alojado y un SDK, una integración básica son tres llamadas en el backend y una ruta de webhook. La mayor parte del tiempo se va en probar en el sandbox.

¿Necesito mi propia página de pago?

No. Los clientes pagan en la página alojada. Si no quieres nada de código, inserta un widget de precios; ver Pasarela de pago para tu web.

¿Cómo sé que un pago ocurrió de verdad?

Confía solo en el webhook firmado, o consulta el intent con la API desde tu backend. Nunca confíes solo en la redirección del navegador.

¿Cuánto cuesta?

OrcaRail alojado cobra 0,5 % por transacción completada después de las primeras 100 transacciones gratis. Las comisiones de red van aparte. Ver precios.

¿Puedo cobrar pagos recurrentes?

Sí, con la API de suscripciones. Ver pagos cripto recurrentes y suscripciones de OrcaRail.

---

Empieza en el sandbox · API de pagos con stablecoins · Precios