Usage

Creating an API context

In order to start making calls with the bunq API, you must first register your API key and device, and create a session. In the SDKs, we group these actions and call it "creating an API context". The context can be created by using the following code snippet:

// For sandbox environment
var apiContext = ApiContext.Create(ApiEnvironmentType.SANDBOX, apiKey, deviceDescription);

// For production
var apiContext = ApiContext.Create(ApiEnvironmentType.PRODUCTION, apiKey, deviceDescription);

// Load the API context into the global BunqContext
BunqContext.LoadApiContext(apiContext);

// Save the context for later use
apiContext.Save("bunq-context.conf");

Please note: initializing your application is a heavy task, therefore, all calls in the example above except for LoadApiContext should be executed once.

After saving the context, you can restore it at any time:

// Restore context from file
var apiContext = ApiContext.Restore("bunq-context.conf");

// Ensure the session is active
apiContext.EnsureSessionActive();

// Load into global context
BunqContext.LoadApiContext(apiContext);

Tip: both saving and restoring the context can be done without any arguments. In this case the context will be saved to/restored from the bunq.conf file in the same folder with your executable.

Example

For an example, see this tinker snippet

PSD2

It is possible to create an ApiContext as PSD2 Service Provider. Although this might seem a complex task, we wrote some helper implementations to get you started. You need to create a certificate and private key to get you started. Our sandbox environment currently accepts all certificates, if these criteria are met:

• Up to 64 characters

• PISP and/or AISP used in the end.

Make sure you have your unique eIDAS certificate number and certificates ready when you want to perform these tasks on our production environment. Due to the implementation used in this SDK, you should create a .pfx credentials file containing your certificate and private key. Creating a pfx file can be done with the following command:

openssl pkcs12 -inkey private.pem -in chain.cert -export -out credentials.pfx

Creating a PSD2 context is very easy:

// Create context for PSD2 application
ApiContext apiContext = ApiContext.CreateForPsd2(
    ApiEnvironmentType.SANDBOX,
    SecurityUtils.GetCertificateFromFile("credentials.pfx", "password"),
    SecurityUtils.GetCertificateCollectionFromAllPath(new[] {"chain.cert"}),
    "PSD2 Device Description",
    new List<string>() // OAuth scopes
);

// Save for later use
apiContext.Save("psd2-context.conf");

// Load into global context
BunqContext.LoadApiContext(apiContext);

This context can be saved the same way as a normal ApiContext. After creating this context, create an OAuth client to get your users to grant you access.

Safety considerations

The file storing the context details (i.e. bunq.conf) is a key to your account. Anyone having access to it is able to perform any Public API actions with your account. Therefore, we recommend choosing a truly safe place to store it.

Basic Operations

Monetary Accounts

Create a Monetary Account

// Create a new monetary account with EUR currency
var newAccountId = MonetaryAccountBankApiObject.Create("EUR", "My Account Description").Value;

Get a Monetary Account

// Get account by ID
var account = MonetaryAccountBankApiObject.Get(accountId).Value;

// Get primary accountvar primary
Account = BunqContext.UserContext.PrimaryMonetaryAccountBank;

Close a Monetary Account

MonetaryAccountBankApiObject.Update(
    accountId,     
    status: "CANCELLED",     
    subStatus: "REDEMPTION_VOLUNTARY",     
    reason: "OTHER",    
    reasonDescription: "No longer needed"
);

Payments

Make a Payment

// Create payment to another Bunq user
PaymentApiObject.Create(
    new AmountObject("10.00", "EUR"),     // Amount and currency    
    new PointerObject("EMAIL", "[email protected]"),  // Recipient    
    "Payment description"                 // 
    Description
);

// Make payment to another monetary account
PaymentApiObject.Create(
    new AmountObject("5.00", "EUR"),    
    recipientAccount.Alias.First(),  // The alias of the recipient account    
    "Transfer between accounts"
);

List Payments

// Get all payments
var payments = PaymentApiObject.List().Value;

// List with pagination
var pagination = new Pagination { Count = 10 };
var paymentsPage = PaymentApiObject.List(urlParams: pagination.UrlParamsCountOnly).Value;

Navigate Through Paged Results

// Get first page (most recent payments)
var firstPage = PaymentApiObject.List(urlParams: new Pagination { Count = 5 }.UrlParamsCountOnly);

// Get previous page (older payments)
var previousPage = PaymentApiObject.List(urlParams: firstPage.Pagination.UrlParamsPreviousPage);

// Get next page (newer payments)
var nextPage = PaymentApiObject.List(urlParams: firstPage.Pagination.UrlParamsNextPage);

Payment Requests

Create a Payment Request

// Request money from another user
var requestId = RequestInquiryApiObject.Create(
    new AmountObject("15.00", "EUR"),    
    new PointerObject("EMAIL", "[email protected]"),    
    "Please pay me back",    
    allowBunqMe: false
).Value;

Accept a Payment Request

// Get pending requests
var urlParams = new Dictionary<string, string> { ["status"] = "PENDING" };
var pendingRequests = RequestResponseApiObject.List(monetaryAccountId, urlParams).Value;

// Accept a request by ID
RequestResponseApiObject.Update(
    requestResponseId,    
    status: "ACCEPTED",    
    monetaryAccountId: monetaryAccountId
);

Attachments and Avatars

Upload Attachment

// Read file bytesvar file
Bytes = File.ReadAllBytes("path/to/image.png");

// Upload as public attachment
var customHeaders = new Dictionary<string, string>{
    { ApiClient.HEADER_CONTENT_TYPE, "image/png" },    
    { ApiClient.HEADER_ATTACHMENT_DESCRIPTION, "My attachment" }
};
var attachmentUuid = AttachmentPublicApiObject.Create(fileBytes, customHeaders).Value;

Create Avatar

// Create avatar using attachment UUID
var avatarUuid = AvatarApiObject.Create(attachmentUuid).Value;

Retrieve Attachment

// Get attachment content by UUID
var attachmentContent = AttachmentPublicContentApiObject.List(attachmentUuid).Value;

Cards

Order a New Card

// Set PIN assignment for primary account
var cardPinAssignment = new CardPinAssignmentObject("PRIMARY"){
    PinCode = "1234",    
    MonetaryAccountId = BunqContext.UserContext.PrimaryMonetaryAccountBank.Id
};

// Get an allowed card name
var possibleName = CardNameApiObject.List().Value.First().PossibleCardNameArray.First();

// Create the debit card
var newCard = CardDebitApiObject.Create(
    secondLine: "MY CARD",           // Text on second line    
    nameOnCard: possibleName,        // Name on card    
    cardType: "MASTERCARD",          // Card type    
    productType: "MASTERCARD_DEBIT", // Product type    
    alias: GetAlias(),               // Your alias    
    pinAssignments: new List<CardPinAssignmentObject> { cardPinAssignment }
).Value;

Notification Filters (Webhooks)

Create URL Notification Filter for Account

// Create notification filter for a specific monetary account
var notificationFilter = new NotificationFilterUrlObject("MUTATION", "https://your-callback-url.com");

NotificationFilterUrlMonetaryAccountInternal.CreateWithListResponse(
    monetaryAccountId,    
    new List<NotificationFilterUrlObject> { notificationFilter }
);

Create URL Notification Filter for User

// Create notification filter for the user
var notificationFilter = new NotificationFilterUrlObject("MUTATION", "https://your-callback-url.com");

NotificationFilterUrlUserInternal.CreateWithListResponse(
    new List<NotificationFilterUrlObject> { notificationFilter }
);

Create Push Notification Filter

// Create push notification filter
var pushFilter = new NotificationFilterPushObject("MUTATION");

NotificationFilterPushUserInternal.CreateWithListResponse(
    new List<NotificationFilterPushObject> { pushFilter }
);

Session Management

Delete Current Session

// Log out/delete current session
SessionApiObject.Delete(0);

Create OAuth Client

// Create an OAuth client
int clientId = OauthClientApiObject.Create().Value;
OauthClientApiObject oauthClient = OauthClientApiObject.Get(clientId).Value;

Create OAuth Authorization URI

// Generate authorization URI
string uri = OauthAuthorizationUri.Create(
    OauthResponseType.CODE,    
    "your-redirect-uri",    
    oauthClient,    
    "state-token"
).GetAuthorizationUri();

Making API calls

There is a class for each endpoint. Each class has functions for each supported action. These actions can be Create, Get, Update, Delete and List.

Sometimes API calls have dependencies, for instance MonetaryAccount. Making changes to a monetary account always also needs a reference to a User. These dependencies are required as arguments when performing API calls. Take a look at doc.bunq.com for the full documentation.

The user dependency will always be determined for you by the SDK. For the monetary account, the SDK will use your primary account (the one used for billing) if no monetary account id is provided.

Creating objects

When creating an object, the default response will be the id of the newly created object.

Reading objects

Reading objects can be done via get and list methods. For get a specific object id is needed while for list will return a list of objects.

Updating objects

Updating objects through the API goes the same way as creating objects, except that also the object to update identifier (ID or UUID) is needed.

Deleting objects

When an object has been deleted, the common respinse is an empty response.