Referencia de la API del SDK de Node

Esta página lista todos los métodos y tipos públicos del SDK @orcarail/node. Para la instalación, la configuración y los ejemplos, consulta la guía del SDK de Node.js.

Cliente

new OrcaRail(apiKey, apiSecret, config?)

Crea un nuevo cliente de OrcaRail. Todas las llamadas a la API usan HTTP Basic Auth con la clave y el secreto indicados.

Parámetros:

• apiKey (string): tu clave de API de OrcaRail (por ejemplo ak_live_xxx).
• apiSecret (string): tu secreto de API de OrcaRail (por ejemplo sk_live_xxx).
• config (opcional): OrcaRailConfig:
  • baseUrl (string): URL base de la API. Por defecto: https://api.orcarail.com/api/v1.
  • apiVersion (string): versión de la API. Por defecto: v1.
  • timeout (number): tiempo de espera de la petición en ms. Por defecto: 30000.

Ejemplo:

import OrcaRail from '@orcarail/node'

const orcarail = new OrcaRail(
  process.env.ORCARAIL_API_KEY!,
  process.env.ORCARAIL_API_SECRET!,
  { baseUrl: 'https://api.orcarail.com/api/v1', timeout: 30000 }
)

Recursos

orcarail.paymentIntents

Recurso de Payment Intents. Consulta la visión general de Payment Intents y la referencia REST.

Método	Descripción
create(params)	Crea un payment intent. Parámetros: PaymentIntentCreateParams (amount, currency, tokenId, networkId, return_url, withdrawal_addresses, etc.). Devuelve PaymentIntent.
retrieve(id)	Obtiene un payment intent por ID (por ejemplo 550e8400-e29b-41d4-a716-446655440000). Devuelve PaymentIntent.
cancel(id)	Cancela un payment intent (por ejemplo, cuando el usuario llega a cancel_url). Devuelve PaymentIntent.
confirm(id, params)	Confirma y redirige al pago alojado. Parámetros: PaymentIntentConfirmParams (client_secret, return_url). Envía la autenticación con clave de API. Devuelve PaymentIntent.
complete(id)	Marca el intent como en procesamiento cuando el usuario llega a la URL de éxito/retorno. Devuelve PaymentIntent.
update(id, params)	Actualiza el importe, los metadatos, las URLs o la dirección de retiro. Parámetros: PaymentIntentUpdateParams. Devuelve PaymentIntent.

Redes y tokens: el SDK no expone métodos para listar redes ni tokens. Usa la API REST para obtener los ID: GET Pagos: listar redes y GET Pagos: listar tokens por red. Pasa los UUID devueltos como networkId y tokenId en paymentIntents.create(params).

orcarail.pay

Pago por el slug del enlace de pago. Consulta la API de pago.

Método	Descripción
get(slug)	Obtiene el pago (payment intent) por slug. Devuelve PaymentIntent & Record<string, unknown>.
cancel(slug)	Cancela por slug. Devuelve el intent cancelado y cancel_url opcional.

orcarail.subscriptions

Las rutas de la colección de suscripciones deducen la organización de la clave de API autenticada; las rutas de elementos individuales siguen en el nivel superior por ID de suscripción.

Método	Descripción
create(params)	Crea una suscripción en la organización de la clave de API. Parámetros: SubscriptionCreateParams. Devuelve Subscription.
list(params?)	Lista las suscripciones de la organización de la clave de API. Parámetros: SubscriptionListParams. Devuelve SubscriptionListResponse.
retrieve(id)	Obtiene una suscripción por ID. Devuelve Subscription.
update(id, params)	Actualiza una suscripción por ID. Parámetros: SubscriptionUpdateParams. Devuelve Subscription.
cancel(id, params?)	Cancela una suscripción por ID. Parámetros: SubscriptionCancelParams. Devuelve Subscription.
resume(id)	Reanuda una suscripción en pausa por ID. Devuelve Subscription.
listPaymentLinks(id, params?)	Lista los enlaces de pago de una suscripción. Devuelve { data, has_more }.

orcarail.rates

Cotización fiat y monedas compatibles. Consulta la API de precios para todos los detalles de los endpoints (incluidos GET /rates/fiat-quote y GET /rates/currencies).

Método	Descripción
getFiatQuote(params)	Obtiene una cotización de fiat a USD/USDC. Parámetros: FiatQuoteParams ({ amount: string, currency: string }). Devuelve FiatQuote.
getCurrencies(options?)	Lista las monedas fiat compatibles. Opciones: { active?: boolean }. Devuelve Currency[].

Tipos: FiatQuoteParams, FiatQuote (amountUsd, amountUsdc, sourceAmount, sourceCurrency), Currency (id, code, name, symbol, decimals, isActive, etc.). Consulta la API de precios para los campos de respuesta.

orcarail.webhooks

Verificación de firmas de webhooks y análisis de eventos. Consulta Webhooks y Firmas.

Método	Descripción
verifySignature(rawBody, signature, secret)	Devuelve true si x-webhook-signature coincide con el HMAC-SHA256 del cuerpo en bruto con el secreto; si no, false.
constructEvent(rawBody, signature, secret)	Verifica la firma y analiza el cuerpo como WebhookEvent. Lanza OrcaRailSignatureVerificationError si no es válida.

Clases de error

Impórtalas desde @orcarail/node:

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

Clase	Cuándo se lanza
OrcaRailError	Clase base de todos los errores del SDK.
OrcaRailAPIError	La API devolvió un código distinto de 2xx. Tiene statusCode, type, details.
OrcaRailAuthenticationError	401: clave o secreto de API no válidos.
OrcaRailSignatureVerificationError	Firma de webhook no válida o fallo al analizar el cuerpo. Tiene signature.

Tipos

El SDK exporta tipos de TypeScript para las peticiones y respuestas. Impórtalos desde @orcarail/node:

• Configuración: OrcaRailConfig
• Payment Intents: PaymentIntent, PaymentIntentStatus, PaymentIntentCreateParams, PaymentIntentUpdateParams, PaymentIntentConfirmParams
• Pago / enlaces: PaymentLink, LatestTransaction
• Webhooks: WebhookEvent, WebhookEventType, WebhookEventData
• Tipos de cambio: FiatQuoteParams, FiatQuote, Currency
• Suscripciones: Subscription, SubscriptionStatus, SubscriptionInterval, SubscriptionCollectionMethod, SubscriptionCreateParams, SubscriptionUpdateParams, SubscriptionCancelParams, SubscriptionListParams, SubscriptionListResponse, SubscriptionPaymentLinksListParams

Para ejemplos de uso y formas de petición y respuesta, consulta la guía del SDK de Node.js y la referencia de la API.