Saltar al contenido principal

SDK de Node.js

Usa el SDK oficial de Node.js de OrcaRail para aceptar pagos cripto con muy poco código de integración. El SDK se encarga de la autenticación, el formato de las peticiones y la verificación de las firmas de los webhooks.

Instalación​

Instala el paquete desde npm:

npm install @orcarail/node

Configuración​

Crea un cliente de OrcaRail con tu clave y tu secreto de API. Opcionalmente, define una URL base personalizada (por ejemplo, para el desarrollo local) y un tiempo de espera.

import OrcaRail from '@orcarail/node'

const orcarail = new OrcaRail(
  process.env.ORCARAIL_API_KEY!, // e.g., "ak_live_xxx"
  process.env.ORCARAIL_API_SECRET!, // e.g., "sk_live_xxx"
  {
    baseUrl: 'https://api.orcarail.com/api/v1', // optional; default
    timeout: 30000, // optional; ms, default 30000
  }
)

Para el desarrollo local, apunta baseUrl a tu API:

const orcarail = new OrcaRail(apiKey, apiSecret, {
  baseUrl: 'http://127.0.0.1:3000/api/v1',
  timeout: 65000, // /complete can take up to ~65s
})

Live frente a sandbox​

Las claves de una organización sandbox empiezan por ak_test_ (testnets, sin fondos reales). Con ellas, orcarail.livemode es false, y await orcarail.paymentIntents.simulate(id) completa un pago sandbox sin wallet. Los eventos de webhook llevan livemode: nunca completes pedidos reales a partir de eventos con livemode: false.

Comisión (reparte y obtén tu parte)​

Las claves de API pueden tener un porcentaje de comisión opcional (0–100). Defínelo en Panel → Claves de API o mediante PATCH /api/v1/api-keys/:id con commissionPercent. Los pagos creados con esa clave incluirán la comisión en la cotización (visible para el pagador) y el importe de la comisión se envía a la dirección de tu configuración de retiros cuando se retiran los fondos.

Payment Intents​

Crear un Payment Intent​

Crea un payment intent con importe, moneda, token, red y URLs de retorno/cancelación.

const intent = await orcarail.paymentIntents.create({
  amount: '100.00',
  currency: 'usd',
  payment_method_types: ['crypto'],
  tokenId: 1, // e.g., USDC
  networkId: 1, // e.g., Ethereum
  return_url: 'https://yourapp.com/success',
  cancel_url: 'https://yourapp.com/cancel',
  description: 'Order #12345',
  metadata: { order_id: '12345' },
  withdrawal_address: '0x...', // optional: override where funds are withdrawn; omit to use your account default
})

console.log(intent.id) // e.g., "550e8400-e29b-41d4-a716-446655440000"
console.log(intent.client_secret)
console.log(intent.payment_link?.link)

Confirmar y redirigir al pago​

Confirma el intent para obtener la URL de pago alojada y redirige al cliente:

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

// Redirect user to confirmed.pay_url or nextAction.redirectToUrl.url

Obtener un Payment Intent​

Obtén el estado actual de un payment intent:

const intent = await orcarail.paymentIntents.retrieve(
  '550e8400-e29b-41d4-a716-446655440000'
)
console.log(intent.status)

Actualizar un Payment Intent​

Actualiza el importe, los metadatos, las URLs o la dirección de retiro antes de que pague el cliente:

const updated = await orcarail.paymentIntents.update(
  '550e8400-e29b-41d4-a716-446655440000',
  {
    amount: '150.00',
    metadata: { order_id: '12345' },
    withdrawal_address: '0x...', // optional: override withdrawal address for this payment
  }
)

Cancelar un Payment Intent​

Cancela cuando el usuario abandone o llegue a tu URL de cancelación:

const canceled = await orcarail.paymentIntents.cancel(
  '550e8400-e29b-41d4-a716-446655440000'
)

Completar un Payment Intent​

Cuando el usuario llegue a tu URL de éxito/retorno, marca el intent como en procesamiento (esto lanza el webhook payment_intent.processing):

const completed = await orcarail.paymentIntents.complete(
  '550e8400-e29b-41d4-a716-446655440000'
)

Pago por slug​

Si usas enlaces de pago con slug, puedes obtener los datos de pago y cancelar por slug:

// Get pay details by slug
const pay = await orcarail.pay.get('pl_abc123')

// Cancel by slug
await orcarail.pay.cancel('pl_abc123')

Webhooks​

Verifica las firmas de los webhooks y analiza los eventos con el SDK.

Verificar la firma​

Usa el cuerpo de la petición en bruto y la cabecera x-webhook-signature. El secreto es tu secreto de webhook (de tu clave de API / panel).

import OrcaRail from '@orcarail/node'

const orcarail = new OrcaRail(apiKey, apiSecret)
const signature = req.headers['x-webhook-signature']
const rawBody = req.rawBody // must be raw string or Buffer, not parsed JSON

if (!orcarail.webhooks.verifySignature(rawBody, signature, webhookSecret)) {
  return res.status(400).send('Invalid signature')
}

Construir el evento (verificar y analizar)​

Verifica y analiza en un solo paso; lanza una excepción si la firma no es válida:

const event = orcarail.webhooks.constructEvent(
  rawBody,
  req.headers['x-webhook-signature'],
  webhookSecret
)

switch (event.type) {
  case 'payment_intent.completed':
    console.log('Payment succeeded:', event.data.object.id)
    break
  case 'payment_intent.processing':
    console.log('Payment processing:', event.data.object.id)
    break
  case 'payment_intent.canceled':
    console.log('Payment canceled:', event.data.object.id)
    break
  case 'payment_intent.requires_payment_method':
    console.log('Payment needs method:', event.data.object.id)
    break
  default:
    console.log('Unhandled event:', event.type)
}

Ejemplo con Express​

const express = require('express')
const OrcaRail = require('@orcarail/node').default

const app = express()
const orcarail = new OrcaRail(
  process.env.ORCARAIL_API_KEY,
  process.env.ORCARAIL_API_SECRET
)

// Use raw body for signature verification
app.post(
  '/webhooks/orcarail',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-webhook-signature']
    const rawBody = req.body // Buffer

    try {
      const event = orcarail.webhooks.constructEvent(
        rawBody,
        signature,
        process.env.ORCARAIL_WEBHOOK_SECRET
      )
      console.log('Event:', event.type, event.data.object.id)
      res.status(200).json({ received: true })
    } catch (err) {
      res.status(400).send('Invalid signature')
    }
  }
)

Ejemplo con Next.js (App Router)​

En un Route Handler, lee el cuerpo en bruto y verifícalo:

import { NextRequest, NextResponse } from 'next/server'
import OrcaRail from '@orcarail/node'

const orcarail = new OrcaRail(
  process.env.ORCARAIL_API_KEY!,
  process.env.ORCARAIL_API_SECRET!
)

export async function POST(request: NextRequest) {
  const rawBody = await request.text()
  const signature = request.headers.get('x-webhook-signature') ?? ''

  try {
    const event = orcarail.webhooks.constructEvent(
      rawBody,
      signature,
      process.env.ORCARAIL_WEBHOOK_SECRET!
    )
    // Handle event.type and event.data.object
    return NextResponse.json({ received: true })
  } catch {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 })
  }
}

Gestión de errores​

El SDK lanza errores tipados que puedes gestionar:

import OrcaRail, {
  OrcaRailError,
  OrcaRailAPIError,
  OrcaRailAuthenticationError,
  OrcaRailSignatureVerificationError,
} from '@orcarail/node';

try {
  const intent = await orcarail.paymentIntents.create({ ... });
} catch (err) {
  if (err instanceof OrcaRailAuthenticationError) {
    console.error('Invalid API key or secret');
  } else if (err instanceof OrcaRailAPIError) {
    console.error('API error:', err.statusCode, err.message);
  } else if (err instanceof OrcaRailSignatureVerificationError) {
    console.error('Webhook signature invalid');
  } else if (err instanceof OrcaRailError) {
    console.error('OrcaRail error:', err.message);
  }
}

App de demostración​

Para ver un ejemplo de integración completo (crear el intent, redirigir al pago, página de éxito, completar, webhooks), consulta la demo de código abierto:

Consulta también​