UnblockPay SDK

TypeScript SDK for the UnblockPay API - a stablecoin banking API for seamless fiat-to-crypto and crypto-to-fiat transactions.

Installation

npm install @idh/unblockpay-sdk

Quick Start

import { UnblockSDK } from '@idh/unblockpay-sdk';

const sdk = new UnblockSDK({
  apiKey: 'your-secret-token',
});

// Create a customer
const customer = await sdk.customers.create({
  type: 'individual',
  first_name: 'Satoshi',
  last_name: 'Nakamoto',
  email: '[email protected]',
  date_of_birth: '1990-01-01',
  identity_documents: [{
    type: 'national_id',
    value: '12345678900',
    country: 'BRA'
  }]
});

// Create a wallet
const wallet = await sdk.wallets.create(customer.id, {
  name: 'My Wallet',
  blockchain: 'solana'
});

// Get wallet balance
const balance = await sdk.wallets.getBalance(customer.id, wallet.id);

Configuration

Basic Configuration

const sdk = new UnblockSDK({
  apiKey: 'your-secret-token',
});

Advanced Configuration

const sdk = new UnblockSDK({
  apiKey: 'your-secret-token',
  baseUrl: 'https://api.unblockpay.com', // optional, defaults to production
  timeout: 30000, // milliseconds
  retryConfig: {
    maxRetries: 3,
    retryDelay: 1000,
    retryOn: [429, 500, 502, 503, 504],
  },
});

API Resources

Customers

Manage individual and business customers with KYC/KYB verification.

// Create an individual customer
const customer = await sdk.customers.create({
  type: 'individual',
  first_name: 'John',
  last_name: 'Doe',
  email: '[email protected]',
  date_of_birth: '1990-01-01',
  identity_documents: [{
    type: 'passport',
    value: 'AB123456',
    country: 'USA'
  }]
});

// Create a business customer
const business = await sdk.customers.create({
  type: 'business',
  business_legal_name: 'Acme Corp',
  email: '[email protected]',
  identity_documents: [{
    type: 'tax_id',
    value: '123456789',
    country: 'USA'
  }]
});

// List customers
const customersResponse = await sdk.customers.list({ limit: 10 });
console.log(`Found ${customersResponse.data.length} customers`);
if (customersResponse.has_more) {
  // Fetch next page using customersResponse.next_cursor
}

// Get customer by ID
const customer = await sdk.customers.get('customer-id');

Wallets

Create and manage stablecoin wallets across multiple blockchains.

// Create a wallet
const wallet = await sdk.wallets.create(customerId, {
  name: 'My USDC Wallet',
  blockchain: 'solana' // or 'ethereum', 'polygon'
});

// List wallets for a customer
const walletsResponse = await sdk.wallets.list(customerId);
const wallets = walletsResponse.data;

// Get wallet details
const wallet = await sdk.wallets.get(customerId, walletId);

// Get wallet balance
const balance = await sdk.wallets.getBalance(customerId, walletId);

External Accounts

Link bank accounts for fiat transactions.

// Create a US bank account
const account = await sdk.externalAccounts.create(customerId, {
  type: 'united_states',
  routing_number: '110000000',
  account_number: '000123456789',
  account_type: 'checking'
});

// Create a European (SEPA) account
const sepaAccount = await sdk.externalAccounts.create(customerId, {
  type: 'europe',
  iban: 'GB82WEST12345698765432',
  bic: 'WESTGB22'
});

// List external accounts
const accountsResponse = await sdk.externalAccounts.list(customerId);
const accounts = accountsResponse.data;

Transactions

Process pay-ins, payouts, and wallet transfers.

// Create a payin (fiat to stablecoin)
const payin = await sdk.transactions.create({
  type: 'payin',
  customer_id: customerId,
  amount: 1000,
  currency: 'USD',
  wallet_id: walletId
});

// Create a payout (stablecoin to fiat)
const payout = await sdk.transactions.create({
  type: 'payout',
  customer_id: customerId,
  amount: 500,
  currency: 'USDC',
  wallet_id: walletId,
  external_account_id: accountId
});

// Create a wallet transfer
const transfer = await sdk.transactions.create({
  type: 'wallet_transfer',
  customer_id: customerId,
  amount: 100,
  currency: 'USDC',
  from_wallet_id: walletId1,
  to_wallet_id: walletId2
});

// List transactions
const transactionsResponse = await sdk.transactions.list({
  customer_id: customerId,
  type: 'payin',
  status: 'completed'
});
const transactions = transactionsResponse.data;

Webhooks

Configure webhooks to receive real-time event notifications.

// Create a webhook
const webhook = await sdk.webhooks.create({
  url: 'https://your-app.com/webhooks',
  events: [
    'payin.completed',
    'payout.completed',
    'payout.failed'
  ]
});

// List webhooks
const webhooksResponse = await sdk.webhooks.list();
const webhooks = webhooksResponse.data;

// Get a specific webhook by ID (if you know the ID)
const webhook = await sdk.webhooks.get(webhookId);

// Update webhook
const updated = await sdk.webhooks.update(webhookId, {
  events: ['payin.completed'],
  active: true
});

Error Handling

The SDK provides specific error types for different scenarios:

import { 
  APIError, 
  ValidationError, 
  AuthenticationError, 
  NotFoundError, 
  RateLimitError 
} from '@idh/unblockpay-sdk';

try {
  const customer = await sdk.customers.create({ /* ... */ });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message, error.details);
  } else if (error instanceof AuthenticationError) {
    console.error('Authentication failed');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited. Retry after:', error.retryAfter);
  } else if (error instanceof APIError) {
    console.error('API error:', error.status, error.message);
  }
}

Supported Blockchains and Stablecoins

• Solana: USDC
• Ethereum: USDC, USDT
• Polygon: USDC, USDT

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint

Documentation

For detailed API documentation, visit https://docs.unblockpay.com.

License

MIT