310 lines
9.1 KiB
Markdown
310 lines
9.1 KiB
Markdown
# @apiclient.xyz/bunq
|
|
A full-featured TypeScript/JavaScript client for the bunq API
|
|
|
|
## Availabililty and Links
|
|
* [npmjs.org (npm package)](https://www.npmjs.com/package/@apiclient.xyz/bunq)
|
|
* [gitlab.com (source)](https://gitlab.com/mojoio/bunq)
|
|
* [github.com (source mirror)](https://github.com/mojoio/bunq)
|
|
* [docs (typedoc)](https://mojoio.gitlab.io/bunq/)
|
|
|
|
## Status for master
|
|
|
|
Status Category | Status Badge
|
|
-- | --
|
|
GitLab Pipelines | [](https://lossless.cloud)
|
|
GitLab Pipline Test Coverage | [](https://lossless.cloud)
|
|
npm | [](https://lossless.cloud)
|
|
Snyk | [](https://lossless.cloud)
|
|
TypeScript Support | [](https://lossless.cloud)
|
|
node Support | [](https://nodejs.org/dist/latest-v10.x/docs/api/)
|
|
Code Style | [](https://lossless.cloud)
|
|
PackagePhobia (total standalone install weight) | [](https://lossless.cloud)
|
|
PackagePhobia (package size on registry) | [](https://lossless.cloud)
|
|
BundlePhobia (total size when bundled) | [](https://lossless.cloud)
|
|
Platform support | [](https://lossless.cloud) [](https://lossless.cloud)
|
|
|
|
## 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
|
|
|
|
```bash
|
|
npm install @apiclient.xyz/bunq
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
// 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
|
|
|
|
```typescript
|
|
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](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :)
|
|
|
|
For further information read the linked docs at the top of this readme.
|
|
|
|
> MIT licensed | **©** [Lossless GmbH](https://lossless.gmbh)
|
|
| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy)
|
|
|
|
[](https://maintainedby.lossless.com)
|