@pouchpay/sdk

Official TypeScript SDK for PouchPay - the easiest way to add crypto on/off-ramps to your application.

Features

• ✅ 5-line integration - Payment URLs in seconds
• ✅ Stateless architecture - No database, instant routing
• ✅ Pre-authentication - Skip email/OTP for known users
• ✅ Screen skipping - Fast-track users straight to payment
• ✅ Fully typed - Complete TypeScript support
• ✅ Framework agnostic - Works everywhere

Installation

npm install @pouchpay/sdk
# or
yarn add @pouchpay/sdk

Quick Start

1. Generate a Payment URL

Server-only. PaymentUrlBuilder / generatePaymentUrl sign JWTs with your secret and are imported from the @pouchpay/sdk/url-builder subpath, not the main entry. They depend on Node's Buffer/crypto; importing them into a browser bundle would both leak your jwtSecret and crash at load. Keep them on your server. The main @pouchpay/sdk entry (PouchPayClient, types) is browser-safe.

import { PaymentUrlBuilder } from '@pouchpay/sdk/url-builder';

const builder = new PaymentUrlBuilder({
  partnerId: 'ptr_abc123',
  jwtSecret: process.env.POUCH_JWT_SECRET
});

const url = builder
  .onramp()
  .network('TRC20')
  .asset('USDT')
  .amount(100)
  .currency('local')
  .countryCode('NG')
  .walletAddress('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb')
  .freezeAmount(true)
  .brandColor('#6366f1')
  .build();

// Send user to payment page
// https://pay.pouchfinance.xyz/pay?source=ptr_abc123&signature=eyJ...&type=onramp&...

That's it! Your user can now buy crypto directly from their bank account.

2. Pre-authenticate Users (Optional)

Skip email/OTP by pre-authenticating users:

import { PouchPayClient } from '@pouchpay/sdk';

const client = new PouchPayClient({
  apiKey: process.env.POUCH_API_KEY
});

// Generate 90-day access token
const { accessToken } = await client.generateAccessToken(
  '[email protected]',
  'NG'
);

// Include in payment URL
const url = builder
  .onramp()
  .network('TRC20')
  .asset('USDT')
  .amount(100)
  .walletAddress('0x...')
  .accessToken(accessToken) // User skips email/OTP
  .build();

3. Fast-Track to Payment Instructions

Provide all parameters + access token to skip ALL screens:

const url = builder
  .onramp()
  .network('TRC20')
  .asset('USDT')
  .amount(100)
  .currency('local')
  .countryCode('NG')
  .walletAddress('0x...')
  .accessToken(accessToken) // User must have verified KYC
  .quoteId('quote_xyz') // Lock exchange rate
  .build();

// User lands directly on payment instructions!
// Ready to pay within 2 seconds of clicking the link

Payment URL Builder API

Configuration

new PaymentUrlBuilder({
  partnerId: string;      // Your partner ID (required)
  jwtSecret: string;      // Your payment signing secret from the dashboard
                          // (Settings → Payment signing secret). NOT your
                          // webhook secret or API key. Required. Server-side only.
  baseUrl?: string;       // Default: 'https://pay.pouchfinance.xyz'
  signatureExpiry?: string; // Default: '1h' (JWT expiry; API accepts up to 24h)
})

Transaction Details

| Method | Description | Example | |--------|-------------|---------| | .onramp() | Fiat → Crypto | builder.onramp() | | .offramp() | Crypto → Fiat | builder.offramp() | | .network(string) | Blockchain network | .network('TRC20') | | .asset(string) | Crypto asset | .asset('USDT') | | .amount(number) | Transaction amount | .amount(100) | | .currency('local' \| 'crypto') | Amount interpretation | .currency('local') | | .countryCode(string) | ISO 3166-1 alpha-2 | .countryCode('NG') | | .walletAddress(string) | User's wallet address | .walletAddress('0x...') |

Authentication

| Method | Description | |--------|-------------| | .accessToken(string) | Pre-auth token (skip email/OTP) |

User Experience

| Method | Description | |--------|-------------| | .freezeAmount(boolean) | Lock amount input | | .freezeWallet(boolean) | Lock wallet address | | .quoteId(string) | Lock exchange rate |

Branding

| Method | Description | |--------|-------------| | .title(string) | Custom page title | | .logoUrl(string) | Your logo URL | | .brandColor(string) | Brand color (hex) | | .successUrl(string) | Redirect after completion | | .callbackUrl(string) | Webhook URL for events |

Build & Reset

| Method | Description | |--------|-------------| | .build() | Generate final URL | | .reset() | Clear all params |

API Client

The SDK also provides a full-featured API client for server-side operations:

import { PouchPayClient } from '@pouchpay/sdk';

const client = new PouchPayClient({
  apiKey: process.env.POUCH_API_KEY,
  baseUrl: 'https://api.pouchfinance.xyz' // optional
});

// Create a payment session
const session = await client.createSession({
  type: 'ONRAMP',
  cryptoCurrency: 'USDT',
  cryptoNetwork: 'TRC20',
  amount: 100,
  currency: 'NGN',
  countryCode: 'NG',
  walletAddress: '0x...'
});

// Get session status
const status = await client.getSession(session.id);

// Generate access tokens
const { accessToken } = await client.generateAccessToken(
  '[email protected]',
  'NG'
);

// Revoke access tokens
await client.revokeAccessToken(accessToken);

See full API documentation for all available methods.

Examples

Basic Onramp

const url = builder
  .onramp()
  .network('TRC20')
  .asset('USDT')
  .amount(100)
  .countryCode('NG')
  .walletAddress('0x...')
  .build();

Offramp with Branding

const url = builder
  .offramp()
  .network('TRC20')
  .asset('USDT')
  .amount(50)
  .currency('crypto')
  .countryCode('KE')
  .walletAddress('0x...')
  .title('Cash Out to Bank')
  .logoUrl('https://yourapp.com/logo.png')
  .brandColor('#10b981')
  .successUrl('https://yourapp.com/success')
  .build();

Pre-authenticated User

// Step 1: Generate access token (one-time)
const { accessToken } = await client.generateAccessToken(
  '[email protected]',
  'NG'
);

// Step 2: Use in payment URL
const url = builder
  .onramp()
  .network('TRC20')
  .asset('USDT')
  .amount(100)
  .walletAddress('0x...')
  .accessToken(accessToken)
  .build();

Fast-Track Payment

// User skips ALL screens, lands on payment instructions
const url = builder
  .onramp()
  .network('TRC20')
  .asset('USDT')
  .amount(100)
  .currency('local')
  .countryCode('NG')
  .walletAddress('0x...')
  .accessToken(accessToken)  // Must have KYC verified
  .quoteId('quote_xyz')      // Lock rate
  .freezeAmount(true)        // Prevent editing
  .build();

Using the Helper Function

import { generatePaymentUrl } from '@pouchpay/sdk/url-builder';

const url = generatePaymentUrl(
  {
    partnerId: 'ptr_abc123',
    jwtSecret: process.env.POUCH_JWT_SECRET
  },
  {
    type: 'onramp',
    network: 'TRC20',
    asset: 'USDT',
    amount: 100,
    currency: 'local',
    countryCode: 'NG',
    walletAddress: '0x...'
  }
);

Screen Skipping Logic

PouchPay automatically routes users based on provided parameters:

| Parameters Provided | User Starts At | |---------------------|----------------| | None | Amount page (manual input) | | Amount + type + network + asset | Wallet address page | | Above + walletAddress | Auth page (email/OTP) | | Above + accessToken | Review page | | Above + quoteId | Payment instructions (instant!) |

Security

• JWT signatures prevent URL tampering
• Replay protection blocks signature reuse
• 1-hour expiry limits signature lifetime (configurable)
• Per-partner secrets isolate security boundaries

Never expose your JWT secret in client-side code. Always generate URLs on your backend.

Environment Variables

# Required
POUCH_API_KEY=pk_live_...        # Your partner API key
POUCH_JWT_SECRET=your-secret-key  # JWT signing secret (get from dashboard)

# Optional
POUCH_BASE_URL=https://pay.pouchfinance.xyz  # Payment page URL
POUCH_API_URL=https://api.pouchfinance.xyz   # API endpoint

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import type {
  PaymentUrlParams,
  PaymentUrlBuilderOptions,
  PaymentType,
  CurrencyType,
  SessionResponse,
  SessionStatus
} from '@pouchpay/sdk';

Support

• Documentation: https://docs.pouchfinance.xyz
• API Reference: https://api.pouchfinance.xyz/docs
• Dashboard: https://dashboard.pouchfinance.xyz
• Issues: https://github.com/pouchpay/pouchpay/issues

License

MIT