@pulsebyshiga/node - Pulse Collect

The server-side SDK. It holds your secret key, mints single-order sessions, looks up order ground truth, previews rates, and verifies signed webhooks. Methods return the value directly and throw typed errors — see Error handling for the catch pattern.

This surface reflects the @pulsebyshiga/node types — the working view of the API until the canonical Pulse OpenAPI contract is published. Wire shapes (snake_case JSON, decimal-string amounts) are stable; a few fields are still being reconciled and are flagged where they appear.

Client construction

Construct the client once with an auth descriptor and optional settings.

import Pulse, { useApiKey } from '@pulsebyshiga/node';

const pulse = new Pulse(useApiKey(process.env.PULSE_API_KEY!), {
  webhookSecret: process.env.PULSE_WEBHOOK_SECRET,
});

The constructor is new Pulse(auth, options). auth is either a bare API-key string (treated as useApiKey) or an auth descriptor from one of the two helpers below.

Auth helpers

PulseAuth

Full engine access with the partner’s root secret. Server-side only — the client throws PulseAccessError if an API key is constructed where window is defined.

PulseAuth

Scope every call to one order’s short-lived session token (cs_*). Browser-safe. The session token is a scoped-down delegate the API key mints, so a caller holds one or the other, never both.

Options

string

Default secret for webhooks.verify() / verifyOnce(). Can also be passed per call.

ProcessedEventStore

Backing store for verifyOnce() de-duplication. Defaults to an in-memory store (single process). Supply a shared store (Redis, a database table) implementing has(eventId) / add(eventId) for multi-instance deployments.

string

Override the API host (e.g. a local or sandbox test server). Otherwise the live engine host is used.

number

default:"2"

Retries on network errors, 429, and 5xx.

number

default:"250"

Base backoff delay, doubled per attempt.

FetchLike

Custom fetch implementation.

collectionSessions.create

const session = await pulse.collectionSessions.create(params, { idempotencyKey });

Creates a collection order plus the single-order session token the hosted flow is opened with. See Create a session for the naira and USD gate walkthrough.

Parameters

The payload is a discriminated union on gate. Provide exactly one of target (fiat side) or source (crypto side).

"naira" | "usd"

required

Which fiat gate the session settles through.

"offramp" | "onramp"

default:"offramp"

Value direction. offramp = crypto in → fiat out; onramp = fiat in → crypto out.

TargetAmount

Fiat side — provide this OR source.

Show TargetAmount

"NGN" | "USD"

required

string

required

Decimal string, e.g. "1000000.00".

SourceAmount

Crypto side (offramp) — the amount of asset to send; the fiat target is derived from it.

Show SourceAmount

"USDC" | "USDT"

required

string

required

"USDC" | "USDT"

required

Network

required

Lowercase network name (see Types).

string

Your own reference for this order.

string

Naira gate only. Your stable reference for the end user.

NairaAccount

Naira gate only. Either provisions a named virtual account on first use, or references an existing one.

Show NairaAccount

boolean

required

true to provision a new account, false to reference an existing one.

string

When provision: true. Sensitive — server-to-server only; never reaches the hosted flow.

string

When provision: true. Sensitive — server-to-server only; never reaches the hosted flow.

string

When provision: false.

The USD gate carries no user_ref and no account block — funds land in your omnibus rather than a per-user account.

Options

string

Client idempotency key; auto-generated when omitted. Key it off your own deposit/order id so a retried request mints the same session.

Response — CollectionSession

string

Short-lived single-order token (cs_*) for the hosted flow. Returned once — hand this to the frontend, never the secret key.

string

Unique per order — the attribution key.

string

Solana Pay URI (solana) or EIP-681 URI (EVM).

SessionQuote

Show SessionQuote

string

Fiat per 1 asset unit, decimal string.

"USDC" | "USDT"

string

Exact stablecoin amount the user must send.

string

OrderStatus

string

collectionOrders

const order = await pulse.collectionOrders.retrieve(orderId);
const orders = await pulse.collectionOrders.list({ gate: 'naira', status: 'awaiting_payment' });
const refreshed = await pulse.collectionOrders.refreshQuote(orderId);

Ground truth for an order — a fallback when a webhook is missed, and the partner-scoped listing for reconciliation. See Orders.

retrieve(orderId) → CollectionOrder
list(params?) → Page<CollectionOrder>
refreshQuote(orderId) → CollectionOrder — re-lock the quote for an expired order on a new window; does not create a new order.

list parameters

"naira" | "usd"

OrderStatus

string

number

string

Response — CollectionOrder

string

"naira" | "usd"

"offramp" | "onramp"

OrderStatus

AmountStatus

TargetAmount

"USDC" | "USDT"

Network

string | null

string

Offramp: where the user sends crypto. Onramp: unused (see pay_account).

Record<string, string>

Optional. Offramp deposit address per chain family/network when the engine returns them, so switching chains reuses the same order. Falls back to deposit_address.

string

PayAccount | null

Onramp: the virtual bank account to pay into. Null on offramp.

Show PayAccount

string

Optional; hidden if it fails to load.

string

Fiat to transfer (equals target.amount), decimal string.

string

SessionQuote

Deposit | null

Show Deposit

string

On-chain detected amount — the credited figure, never the quoted one.

"USDC" | "USDT"

Network

string

string | null

WrongChainDeposit | null

Provisional shape — funds detected on a network other than the order’s.

Show WrongChainDeposit

string

"USDC" | "USDT"

string

Network the funds actually arrived on (may be outside the supported set).

string

Disbursement | null

Show Disbursement

string

"NGN" | "USD"

string

string | null

Naira gate only; null for USD (partner omnibus).

string

The list response wraps orders in a page:

CollectionOrder[]

string | null

rates.preview

const preview = await pulse.rates.preview({ from: 'USDC', to: 'NGN', amount: '100.00' });

Look up the live rate without placing an order. Wraps POST /v1/quotes and reshapes it for display; the returned quoteId proceeds to an order at the same locked price. See Preview a rate.

Parameters — RatePreviewParams

string

required

Source currency/asset, e.g. "USDC".

string

required

Destination currency, e.g. "NGN".

string

required

Decimal amount in the source currency, e.g. "100.00".

EngineNetwork

Uppercase engine network name.

Response — RatePreview

string

Units of to per one unit of from, decimal string.

string

What the user parts with (equals the requested amount), decimal string.

string

What the user gets at this rate, decimal string.

string

When the locked rate expires (ISO 8601).

string

Pass to an order to transact at exactly this locked rate.

rates.preview reshapes the response to camelCase (youSend, expiresAt, quoteId) for display — the only camelCase surface in the SDK. Everything else is snake_case on the wire.

webhooks

const event = pulse.webhooks.verify(rawBody, signatureHeader);
const eventOrNull = await pulse.webhooks.verifyOnce(rawBody, signatureHeader);

Verify a signed Pulse-Signature delivery and get the typed WebhookEvent. payload MUST be the raw request body — a re-serialized JSON object will not match the signature. See Webhooks and the webhook event catalog.

WebhookEvent

Verifies the signature and replay tolerance, returns the typed event. Throws SignatureVerificationError on any mismatch.

Promise<WebhookEvent | null>

Verifies AND de-duplicates on event.id. First sight of an id returns the event; a redelivery returns null (skip it, respond 200). Signature failures still throw before the store is touched.

payload: string | Buffer — the raw body.
secret: optional; falls back to the constructor’s webhookSecret.
options (VerifyOptions): toleranceSeconds (default 300) and now (injectable Unix-seconds clock).

Errors

Every SDK error extends PulseError, so catch (e) { if (e instanceof PulseError) … } catches everything from the SDK.

extends PulseError

The engine responded non-2xx. Fields: status (number), code (string), message (string), requestId (string | null).

extends PulseError

Network failure / timeout after the built-in retries. Field: message.

extends PulseError

A credential was used where it isn’t allowed — e.g. an API key constructed in a browser. Field: message.

extends PulseError

Webhook verification failed — bad signature, replay, or malformed payload. Field: message.

Types

string union

Lowercase, product surface (sessions/orders): ethereum, base, polygon, arbitrum, optimism, celo, plasma. solana and ton are recognised but coming soon.

string union

UPPERCASE, engine quote surface (rates.preview): BASE, POLYGON, ARBITRUM, OPTIMISM, ETHEREUM, BSC.

string union

naira, usd.

string union

USDC, USDT.

string union

NGN, USD.

string union

offramp, onramp.

string union

awaiting_payment, deposit_detected, deposit_confirmed, converting, converted_unsettled, completed, expired, failed.

string union

pending, exact, underpaid, overpaid.

Casing matters. Network (product surface, lowercase) and EngineNetwork (engine quote surface, UPPERCASE) are distinct types with different members — BSC exists only on EngineNetwork; solana/ton/celo/plasma only on Network. Pass the one the method’s signature asks for.

​Client construction

​Auth helpers

​Options

​collectionSessions.create

​Parameters

​Options

​Response — CollectionSession

​collectionOrders

​list parameters

​Response — CollectionOrder

​rates.preview

​Parameters — RatePreviewParams

​Response — RatePreview

​webhooks

​Errors

​Types

Client construction

Auth helpers

Options

collectionSessions.create

Parameters

Options

Response — CollectionSession

collectionOrders

list parameters

Response — CollectionOrder

rates.preview

Parameters — RatePreviewParams

Response — RatePreview

webhooks

Errors

Types