Create a session

Every session picks one of two fiat gates. Construct the client once (see Install & initialize), then mint a session with pulse.collectionSessions.create(payload, { idempotencyKey }).

Naira gate
USD gate

The naira gate carries per-user identity: add user_ref and an account block — { provision: true, bvn, nin } for a first-time customer, so Pulse provisions their named virtual account, or { provision: false, virtual_account_ref } for a returning one.

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

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

// Naira gate — first-time customer (Pulse provisions the virtual account)
const session = await pulse.collectionSessions.create(
  {
    gate: 'naira',
    target: { currency: 'NGN', amount: '1000000.00' },
    asset: 'USDT',
    network: 'base',
    user_ref: 'your_user_123',
    account: { provision: true, bvn: '...', nin: '...' },
  },
  { idempotencyKey: `fund-${depositId}` },
);

// Returning customer:
// account: { provision: false, virtual_account_ref: "va_..." }

BVN/NIN are sensitive — they travel server-to-server only in this call and never reach the browser.

The usd gate is the simplest path — no user_ref, no account block; funds land in your omnibus rather than a per-user account.

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

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

// USD gate — no user_ref, no account block; funds land in your omnibus.
const session = await pulse.collectionSessions.create(
  {
    gate: 'usd',
    target: { currency: 'USD', amount: '100.00' },
    asset: 'USDT',
    network: 'base',
  },
  { idempotencyKey: `fund-${depositId}` },
);

Idempotency

Pass an idempotencyKey (e.g. keyed off your own deposit/order id) so a retried request — a network blip, a duplicate click — mints the same session instead of a second one.

The returned shape

// {
//   session_token,   // 'cs_…' — hand this to the frontend, never the sk_ key
//   order_id,
//   deposit_address,
//   qr_payload,      // Solana Pay / EIP-681
//   quote,           // rate, asset_amount, locked_until
//   status,
// }

Return only session.session_token to your frontend — it is the only Pulse credential the browser ever holds. See Render the payment moment for how the client consumes it, and Webhooks for how you confirm settlement.

Get started

Concepts

Backend integration

Render the payment moment

Testing & go-live

Idempotency

The returned shape

​Idempotency

​The returned shape

Idempotency

The returned shape