Saltar al contenido principal

App de demostración de OrcaRail

Una aplicación de demostración sencilla y de código abierto que muestra cómo aceptar pagos cripto con OrcaRail usando el SDK de Node.js y la página de pago alojada.

Repositorio​

Demos live y sandbox​

La misma demo se ejecuta dos veces: la demo live usa redes y tokens de mainnet, y la demo sandbox usa testnets con tokens de prueba gratuitos. El modo depende de la clave de API (ak_test_ significa sandbox). La demo sandbox muestra un indicador Testnet parpadeante y enlaza con la demo live, y la demo live enlaza de vuelta con la demo de testnet. En la demo sandbox puedes terminar el checkout con Simular pago, sin necesidad de wallet.

Funcionalidades​

  • Reparte y obtén tu comisión: usa una clave de API con un % de comisión para ganar una parte de cada pago; la comisión se muestra en el checkout y se envía a tu dirección de retiro
  • Botón «Pagar con cripto» y tarjeta de producto
  • Creación y confirmación del Payment Intent con el SDK de Node.js (@orcarail/node)
  • Selector de moneda rellenado con orcarail.rates.getCurrencies({ active: true })
  • Cotización fiat mediante orcarail.rates.getFiatQuote({ amount, currency }) para el cuadro de cotización
  • Redirección a la página de pago alojada de OrcaRail
  • Página de éxito con el estado del pago
  • Endpoint de webhook para eventos de pago (con verificación de firma)
  • Lista para desplegar en Vercel

Stack técnico​

  • Framework: Next.js (App Router)
  • SDK: @orcarail/node
  • Estilos: Tailwind CSS

Inicio rápido​

  1. Clona el repositorio

    git clone https://github.com/OrcaRail/demo.git
    cd demo

  2. Instala las dependencias

    npm install

  3. Configura el entorno

    Copia .env.local.example en .env.local y define:

    • ORCARAIL_API_KEY: tu clave de API (por ejemplo ak_live_xxx)
    • ORCARAIL_API_SECRET: tu secreto de API (por ejemplo sk_live_xxx)
    • ORCARAIL_WEBHOOK_SECRET: opcional; para verificar la firma de los webhooks
    • NEXT_PUBLIC_APP_URL: la URL de tu app (por ejemplo http://localhost:3001)

    El token y la red se eligen en la interfaz de la demo (o se envían en el cuerpo de la petición a /api/pay). Opcionalmente, puedes enviar withdrawal_address en el cuerpo para cambiar adónde se retiran los fondos de ese pago.

    Para el desarrollo local con una API local:

    • ORCARAIL_API_BASE_URL: por ejemplo http://127.0.0.1:3000/api/v1

  4. Ejecuta la demo

    npm run dev

    Abre la app (por defecto: http://localhost:3001), haz clic en «Pagar con cripto» y completa el flujo en la app de pago alojada.

Flujo​

  1. El usuario hace clic en «Pagar con cripto» → el frontend llama a /api/pay.
  2. El backend usa el SDK para crear y confirmar un Payment Intent.
  3. El usuario es redirigido a la página de pago alojada de OrcaRail.
  4. El usuario completa el pago on-chain.
  5. El usuario es redirigido a la página de éxito; la app llama a /api/complete y /api/status para marcar el intent como en procesamiento y mostrar el estado.
  6. Tu webhook en /api/webhooks recibe eventos como payment_intent.completed y payment_intent.processing.

Webhooks​

La demo incluye una ruta de webhook en /api/webhooks que:

  • Verifica la cabecera x-webhook-signature con tu secreto de webhook
  • Gestiona los eventos: payment_intent.completed, payment_intent.processing, payment_intent.canceled, payment_intent.requires_payment_method, payment_intent.requires_confirmation

Configura la URL de tu webhook en el panel de OrcaRail (por ejemplo https://your-app.vercel.app/api/webhooks).

Desplegar en Vercel​

  1. Sube la demo a tu GitHub e importa el proyecto en Vercel.
  2. Añade las mismas variables de entorno en la configuración del proyecto de Vercel.
  3. Define NEXT_PUBLIC_APP_URL con tu URL de Vercel.
  4. Despliega. Vercel detectará Next.js y configurará la compilación.

Consulta también​