@apiclient.xyz/bunq

A full-featured TypeScript/JavaScript client for the bunq API

Availabililty and Links

• npmjs.org (npm package)
• gitlab.com (source)
• github.com (source mirror)
• docs (typedoc)

Status for master

Status Category	Status Badge
GitLab Pipelines
GitLab Pipline Test Coverage
npm
Snyk
TypeScript Support
node Support
Code Style
PackagePhobia (total standalone install weight)
PackagePhobia (package size on registry)
BundlePhobia (total size when bundled)
Platform support

Features

• Complete bunq API implementation
• TypeScript support with full type definitions
• Automatic session management and renewal
• Request signing and response verification
• Support for all account types (personal, business, joint)
• Payment and transaction management
• Card management and controls
• Scheduled and draft payments
• File attachments and exports
• Webhook support
• OAuth authentication
• Sandbox environment support

Installation

npm install @apiclient.xyz/bunq

Quick Start

import { BunqAccount } from '@apiclient.xyz/bunq';

// Initialize bunq client
const bunq = new BunqAccount({
  apiKey: 'your-api-key',
  deviceName: 'My App',
  environment: 'PRODUCTION' // or 'SANDBOX'
});

// Initialize the client
await bunq.init();

// Get all monetary accounts
const accounts = await bunq.getAccounts();
console.log('My accounts:', accounts);

// Get transactions for an account
const transactions = await accounts[0].getTransactions();
console.log('Recent transactions:', transactions);

// Clean up when done
await bunq.stop();

Usage Examples

Making Payments

import { BunqPayment } from '@apiclient.xyz/bunq';

// Simple payment
const payment = BunqPayment.builder(bunq, monetaryAccount)
  .amount('10.00', 'EUR')
  .toIban('NL91ABNA0417164300', 'John Doe')
  .description('Coffee payment')
  .create();

// Batch payment
const batch = new BunqBatchPayment(bunq, monetaryAccount);
batch
  .addPayment({
    amount: { value: '5.00', currency: 'EUR' },
    counterparty_alias: { type: 'IBAN', value: 'NL91ABNA0417164300' },
    description: 'Payment 1'
  })
  .addPayment({
    amount: { value: '15.00', currency: 'EUR' },
    counterparty_alias: { type: 'EMAIL', value: 'friend@example.com' },
    description: 'Payment 2'
  });
await batch.create();

Managing Cards

import { BunqCard } from '@apiclient.xyz/bunq';

// List all cards
const cards = await BunqCard.list(bunq);

// Activate a card
await cards[0].activate('activation-code');

// Update spending limit
await cards[0].updateLimit('100.00', 'EUR');

// Block a card
await cards[0].block('LOST');

// Order a new card
const newCard = await BunqCard.order(bunq, {
  secondLine: 'Travel Card',
  nameOnCard: 'JOHN DOE',
  type: 'MASTERCARD'
});

Scheduled Payments

import { BunqScheduledPayment } from '@apiclient.xyz/bunq';

// Create a recurring payment
const scheduled = BunqScheduledPayment.builder(bunq, monetaryAccount)
  .amount('50.00', 'EUR')
  .toIban('NL91ABNA0417164300', 'Landlord')
  .description('Monthly rent')
  .scheduleMonthly('2024-01-01T10:00:00Z', '2024-12-31T10:00:00Z')
  .create();

// List scheduled payments
const schedules = await BunqScheduledPayment.list(bunq, monetaryAccount.id);

Request Money

import { BunqRequestInquiry } from '@apiclient.xyz/bunq';

// Create a payment request
const request = BunqRequestInquiry.builder(bunq, monetaryAccount)
  .amount('25.00', 'EUR')
  .fromEmail('friend@example.com', 'My Friend')
  .description('Dinner split')
  .allowBunqme()
  .create();

// The request will include a bunq.me URL for easy sharing
console.log('Share this link:', request.bunqmeShareUrl);

File Attachments

import { BunqAttachment } from '@apiclient.xyz/bunq';

// Upload a file
const attachment = new BunqAttachment(bunq);
const attachmentUuid = await attachment.uploadFile('/path/to/receipt.pdf', 'Receipt');

// Attach to a payment
const payment = BunqPayment.builder(bunq, monetaryAccount)
  .amount('99.99', 'EUR')
  .toIban('NL91ABNA0417164300')
  .description('Purchase with receipt')
  .attachments([attachmentUuid])
  .create();

Export Statements

import { BunqExport, ExportBuilder } from '@apiclient.xyz/bunq';

// Export last month's transactions as PDF
await new ExportBuilder(bunq, monetaryAccount)
  .asPdf()
  .lastMonth()
  .downloadTo('/path/to/statement.pdf');

// Export custom date range as CSV
await new ExportBuilder(bunq, monetaryAccount)
  .asCsv()
  .dateRange('2024-01-01', '2024-03-31')
  .regionalFormat('EUROPEAN')
  .downloadTo('/path/to/transactions.csv');

Webhooks

import { BunqWebhookServer, BunqNotification } from '@apiclient.xyz/bunq';

// Setup webhook server
const webhookServer = new BunqWebhookServer(bunq, {
  port: 3000,
  publicUrl: 'https://myapp.com'
});

// Register handlers
webhookServer.getHandler().onPayment((payment) => {
  console.log('New payment:', payment.amount.value, payment.description);
});

webhookServer.getHandler().onCard((card) => {
  console.log('Card event:', card.status);
});

// Start server and register with bunq
await webhookServer.start();
await webhookServer.register();

Sandbox Testing

// Create a sandbox account
const sandboxBunq = new BunqAccount({
  apiKey: '', // Will be generated
  deviceName: 'Sandbox Test',
  environment: 'SANDBOX'
});

// Create a sandbox user with API key
const apiKey = await sandboxBunq.createSandboxUser();
console.log('Sandbox API key:', apiKey);

// Now reinitialize with the API key
const bunq = new BunqAccount({
  apiKey: apiKey,
  deviceName: 'Sandbox Test',
  environment: 'SANDBOX'
});
await bunq.init();

API Reference

Core Classes

• BunqAccount - Main entry point for the API
• BunqMonetaryAccount - Represents a bank account
• BunqTransaction - Represents a transaction
• BunqUser - User management

Payment Classes

• BunqPayment - Create and manage payments
• BunqBatchPayment - Create multiple payments at once
• BunqScheduledPayment - Schedule recurring payments
• BunqDraftPayment - Create draft payments requiring approval
• BunqRequestInquiry - Request money from others

Other Features

• BunqCard - Card management
• BunqAttachment - File uploads and attachments
• BunqExport - Export statements in various formats
• BunqNotification - Webhook notifications
• BunqWebhookServer - Built-in webhook server

Security

• All requests are signed with RSA signatures
• Response signatures are verified
• API keys are stored securely
• Session tokens are automatically refreshed
• Supports IP whitelisting

Error Handling

try {
  await payment.create();
} catch (error) {
  if (error instanceof BunqApiError) {
    console.error('bunq API error:', error.errors);
  } else {
    console.error('Unexpected error:', error);
  }
}

Requirements

• Node.js 10.x or higher
• TypeScript 3.x or higher (for TypeScript users)

Contribution

We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can contribute one time or contribute monthly. :)

For further information read the linked docs at the top of this readme.

MIT licensed | © Lossless GmbH | By using this npm module you agree to our privacy policy