Node SDK API Reference

This page lists all public methods and types of the @orcarail/node SDK. For installation, configuration, and examples, see the Node.js SDK guide.

Client

new OrcaRail(apiKey, apiSecret, config?)

Creates a new OrcaRail client. All API calls use HTTP Basic Auth with the given key and secret.

Parameters:

• apiKey (string) — Your OrcaRail API key (e.g. ak_live_xxx).
• apiSecret (string) — Your OrcaRail API secret (e.g. sk_live_xxx).
• config (optional) — OrcaRailConfig:
  • baseUrl (string) — API base URL. Default: https://api.orcarail.com/api/v1.
  • apiVersion (string) — API version. Default: v1.
  • timeout (number) — Request timeout in ms. Default: 30000.

Example:

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 }
)

Resources

orcarail.paymentIntents

Payment Intents resource. See Payment Intents overview and REST reference.

Method	Description
create(params)	Create a payment intent. Params: PaymentIntentCreateParams (amount, currency, tokenId, networkId, return_url, withdrawal_address, etc.). Returns PaymentIntent.
retrieve(id)	Get a payment intent by ID (e.g. 550e8400-e29b-41d4-a716-446655440000). Returns PaymentIntent.
cancel(id)	Cancel a payment intent (e.g. when user hits cancel_url). Returns PaymentIntent.
confirm(id, params)	Confirm and redirect to hosted pay. Params: PaymentIntentConfirmParams (client_secret, return_url). Does not send API key. Returns PaymentIntent.
complete(id)	Mark intent as processing when user lands on success/return URL. Returns PaymentIntent.
update(id, params)	Update amount, metadata, URLs, or withdrawal address. Params: PaymentIntentUpdateParams. Returns PaymentIntent.

Networks and Tokens: The SDK does not expose list methods for networks or tokens. Use the REST API to get IDs: GET Payments: List Networks and GET Payments: List Tokens by Network. Pass the returned UUIDs as networkId and tokenId in paymentIntents.create(params).

orcarail.pay

Pay by payment-link slug. See Pay API.

Method	Description
get(slug)	Get pay (payment intent) by slug. Returns PaymentIntent & Record<string, unknown>.
cancel(slug)	Cancel by slug. Returns canceled intent and optional cancel_url.

orcarail.subscriptions

Subscription collection routes infer organization from the authenticated API key; item routes remain top-level by subscription id.

Method	Description
create(params)	Create a subscription in the API key's organization. Params: SubscriptionCreateParams. Returns Subscription.
list(params?)	List subscriptions in the API key's organization. Params: SubscriptionListParams. Returns SubscriptionListResponse.
retrieve(id)	Get a subscription by ID. Returns Subscription.
update(id, params)	Update a subscription by ID. Params: SubscriptionUpdateParams. Returns Subscription.
cancel(id, params?)	Cancel a subscription by ID. Params: SubscriptionCancelParams. Returns Subscription.
resume(id)	Resume a paused subscription by ID. Returns Subscription.
listPaymentLinks(id, params?)	List payment links for a subscription. Returns { data, has_more }.

orcarail.price

Fiat quote and supported currencies. See Price API for full endpoint details (including GET /price/fiat-quote and GET /price/currencies).

Method	Description
getFiatQuote(params)	Get fiat-to-USD/USDC quote. Params: FiatQuoteParams ({ amount: string, currency: string }). Returns FiatQuote.
getCurrencies(options?)	List supported fiat currencies. Options: { active?: boolean }. Returns Currency[].

Types: FiatQuoteParams, FiatQuote (amountUsd, amountUsdc, sourceAmount, sourceCurrency), Currency (id, code, name, symbol, decimals, isActive, etc.). See Price API for response fields.

orcarail.webhooks

Webhook signature verification and event parsing. See Webhooks and Signatures.

Method	Description
verifySignature(rawBody, signature, secret)	Returns true if x-webhook-signature matches HMAC-SHA256 of raw body with secret; otherwise false.
constructEvent(rawBody, signature, secret)	Verifies signature and parses body as WebhookEvent. Throws OrcaRailSignatureVerificationError if invalid.

Error classes

Import from @orcarail/node:

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

Class	When thrown
OrcaRailError	Base class for all SDK errors.
OrcaRailAPIError	API returned non-2xx. Has statusCode, type, details.
OrcaRailAuthenticationError	401 — invalid API key or secret.
OrcaRailSignatureVerificationError	Webhook signature invalid or body parse failed. Has signature.

Types

The SDK exports TypeScript types for requests and responses. Import from @orcarail/node:

• Config: OrcaRailConfig
• Payment Intents: PaymentIntent, PaymentIntentStatus, PaymentIntentCreateParams, PaymentIntentUpdateParams, PaymentIntentConfirmParams
• Pay / links: PaymentLink, LatestTransaction
• Webhooks: WebhookEvent, WebhookEventType, WebhookEventData
• Price: FiatQuoteParams, FiatQuote, Currency
• Subscriptions: Subscription, SubscriptionStatus, SubscriptionInterval, SubscriptionCollectionMethod, SubscriptionCreateParams, SubscriptionUpdateParams, SubscriptionCancelParams, SubscriptionListParams, SubscriptionListResponse, SubscriptionPaymentLinksListParams

For usage examples and request/response shapes, see the Node.js SDK guide and the API Reference.