Stock and Forex Data and Realtime Quotes

La estandarización de la conexión con cualquier banco en tiempo real.

# Introduction The Business Registries API is built on HTTP. The API is RESTful. It has predictable resource URIs. The API is documented in OpenAPI format. In addition to the standard OpenAPI syntax we use a few vendor extensions. # Overview The following sections describe the resources that make up the Business Registries REST API. ## Current Version By default, all requests to https://api.abr.ato.gov.au receive the `v1` version of the REST API. We encourage you to explicitly request this version via the `Accept` header. Accept: application/vnd.abr-ato.v1+json ## Schema All API access is over HTTPS, and accessed from https://api.abr.ato.gov.au. All data is sent and received as JSON. Blank fields are included. All dates use the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: YYYY-MM-DD For example: `2017-07-01` (the 1st of July 2017) All timestamps use the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: YYYY-MM-DDTHH:MM:SSZ For example: `2017-07-01T11:05:06+10:00` ## Timezones Some requests allow for specifying timestamps or generate timestamps with time zone information. We apply the following rules, in order of priority, to determine timezone information for API calls. ### Explicitly provide an ISO 8601 timestamp with timezone information For API calls that allow for a timestamp to be specified, we use that exact timestamp. For example: `2017-07-01T11:05:06+10:00` ## Pagination Information about pagination is provided in the [Link](https://tools.ietf.org/html/rfc5988#page-6) header. For example: Link: ; rel="next", ; rel="last" `rel="next"` states that the next page is `page=2`. This makes sense, since by default, all paginated queries start at page `1`. `rel="last"` provides some more information, stating that the last page of results is on `page 34`. Accordingly, we have 33 more pages of information that we can consume. ## Parameters Many API methods take optional parameters: GET /individuals/1234/addresses/?addressType='Mailing' In this example, the '1234' value is provided for the `:partyId` parameter in the path while `:addressType` is passed in the query string. For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of 'application/json'. ## Metadata The API provides **metadata services** that you can use to discover information about the classifcation schemes and values used by the Registry. For example: GET /classifications/roles Sample response: [ { "id": "123e4567-e89b-12d3-a456-426655440001", "role": "Director", "roleDescription": "An individual responsible for managing a company's ...", "relationship": "Directorship", "reciprocalRole": "Company", "reciprocalRoleDescription": "An incorporated legal entity." }, { ... } ] ## Root Endpoint You can issue a GET request to the root endpoint (also known as the service root) to get all the endpoint categories that the REST API supports: curl https://api.abr.ato.gov.au ## Authentication The Business Registries API supports API Key authentication. When you sign up for an account, you are given your first API key. You can generate additional API keys, and delete API keys (as you may need to rotate your keys in the future). You authenticate to the Business Registries API by providing your secret key in the request header. **Note:** Some requests will return `404 Not Found`, instead of `403 Permission Denied`. This is to prevent the accidental leakage of information to unauthorised users.

https://www.beanstream.com/api/v1

# Budgea Development Guides Welcome to **Budgea**'s documentation. This documentation is intended to get you up-and-running with our APIs and advise on the implementation of some regulatory aspects of your application, following the DSP2's guidelines. ## Getting Started **IMPORTANT** Depending on your status with regard of the DSP2 regulation, **agent** or **partner**, you may call our APIs or simply use our Webview and callbacks to get the financial data of your users. As an **agent**, you are allowed to call directly our APIs and implement your own form to get the user's credentials. As a **partner**, you cannot manipulate the credentials, and have to delegate this step to us through our webview. The sections below will document how to use our APIs, make sure you have the **agent** status to do so. For the **partner**, please refer to the section *Webview* and *Callbacks* of this documentation. ### Overview Your API is a REST API which requires a communication through https to send and receive JSON documents. During your tests, we recommend to make calls to the API with curl or any other HTTP client of your choice. You can watch a video demonstration on this [URL](https://asciinema.org/a/FsaFyt3WAPyDm7sfaZPkwal3V). For the examples we'll use the demo API with address `https://demo.biapi.pro`, you should change that name to your API's name. ### Hello World Let's start by calling the service `/banks` which lists all available banks. ``` curl https://demo.biapi.pro/2.0/banks/ ``` To log in to a bank webpage, you'll need to know for a given bank, the fields your user should fill in the form. Let's call a specific bank and ask for an additional resource *fields*. ``` curl https://demo.biapi.pro/2.0/banks/59?expand=fields ``` The response here concerns only 1 bank (since we specified an id) and the resource _Fields_ is added to the response thanks to the query parameter `expand`. To get more interesting things done, you'll need to send authenticated requests. ### Authentication The way to authenticate is by passing the `Authorization: Bearer ` header in your request. At the setup a _manage token_ have been generated, you can use this token for now, when creating your user we'll see how to generate a user's token. ``` curl https://demo.biapi.pro/2.0/config \ -H 'Authorization: Bearer ' ``` This endpoint will list all the parameters you can change to adapt Budgea to your needs. We've covered the very first calls. Before diving deeper, let's see some general information about the APIs. ## Abstract ### API URL `https://demo.biapi.pro/2.0` ### Requests format Data format: **application/x-www-form-urlencoded** or **application/json** (suggested) Additional headers: Authorization: User's token (private) ### Responses format Data format: **application/json** ([http://www.json.org](http://www.json.org/)) Charset: **UTF-8** ### Resources Each call on an endpoint will return resources. The main resources are: | Resource | Description | | ---------------------|:------------------------------------------------------------------------------------------------------------------ | |Users |Represent a user | |Connection |A set of data used to authenticate on a website (usually a login and password). There is 1 connection for each website| |Account |A bank account contained in a connection | |Transaction |An entry in a bank account | |Investment |An asset in a bank account | The chain of resources is as follow: **Users ∈ Connections ∈ Accounts ∈ Transactions or Investments** ### RESTful API This API is RESTful, which means it is stateless and each resource is accessed with an unique URI. Several HTTP methods are available: | Method | Description | | ------------------------|:-------------------------------| | GET /resources | List resources | | GET /resources/{ID} | Get a resource from its ID | | POST /resources | Create a new resource | | POST /resources/{ID} | Update a resource | | PUT /resources /{ID} | Update a resource | | DELETE /resources | Remove every resources | | DELETE /resources/{ID} | Delete a resource | Each resource can contain sub-resources, for example: `/users/me/connections/2/accounts/23/transactions/48` ### HTTP response codes | Code | Message | Description | | ----------- |:---------------------:|-----------------------------------------------------------------------------------------------| | 200 | OK |Default response when a GET or POST request has succeed | | 202 | Accepted |For a new connection this code means it is necessary to provide complementary information (2FA)| | 204 | No content |Default response when a POST request succeed without content | | 400 | Bad request |Supplied parameters are incorrect | | 403 | Forbidden |Invalid token | | 500 | Internal Servor Error |Server error | | 503 | Service Unavailable |Service is temporarily unavailable | ### Errors management In case an error occurs (code 4xx or 5xx), the response can contain a JSON object describing this error: ```json { "code": "authFailure", "message": "Wrong password" // Optional } ``` If an error is displayed on the website, Its content is returned in error_message field. The list of all possible errors is listed further down this page. ### Authentication A user is authenticated by an access_token which is sent by the API during a call on one of the authentication services, and can be supplied with this header: `Authorization: Bearer YYYYYYYYYYYYYYYYYYYYYYYYYYY` There are two user levels: - Normal user, which can only access to his own accounts - Administrator, with extended rights ### Default filters During a call to an URI which lists resources, some filters can be passed as query parameters: | Parameter | Type | Description | | ----------- |:---------:|-----------------------------------------------------------| | offset | Integer |Offset of the first returned resource | | limit | Integer |Limit number of results | | min_date | Date |Minimal date (if supported by service), format: YYYY-MM-DD | | max_date | Date |Maximal date (if supported by service), format: YYYY-MM-DD | ### Extend requests During a GET on a set of resources or on a unique resource, it is possible to add a parameter expand to the request to extend relations with other resources: `GET /2.0/users/me/accounts/123?expand=transactions[category],connection` ```json { "id" : 123 "name" : "Compte chèque" "balance" : 1561.15 "transactions" : [ { "id" : 9849, "simplified_wording" : "HALL'S BEER", "value" : -513.20, ... "category" : { "id" : 561, "name" : "Sorties / Bar", ... } }, ... ], "id_user" : 1, "connection" : { "id" : 1518, "id_bank" : 41, "id_user" : 1, "error" : null, ... } } ``` ### Request example ```http GET /2.0/banks?offset=0&limit=10&expand=fields Host: demo.biapi.pro Accept: application/json Authorization: Bearer ``` ```http HTTP/1.1 200 OK Content-Type: application/json Content-Length: 3026 Server: Apache Date: Fri, 14 Mar 2014 08:24:02 GMT { "banks" : [ { "id_weboob" : "bnp", "name" : "BNP Paribas", "id" : 3, "hidden" : false, "fields" : [ { "id" : 1, "id_bank" : 3, "regex" : "^[0-9]{5,10}$", "name" : "login", "type" : "text", "label" : "Numéro client" }, { "id" : 2, "id_bank" : 3, "regex" : "^[0-9]{6}$", "name" : "password", "type" : "password", "label" : "Code secret" } ] }, ... ] "total" : 41 } ``` ### Constants #### List of bank account types | Type |Description | | ----------- |-----------------------------------| | checking |Checking account | | savings |Savings account | | deposit |Deposit accounts | | loan |Loan | | market | Market accounts | | joint |Joint account | | card |Card | | lifeinsurance |Life insurance accounts | | pee |Plan Épargne Entreprise | | perco |Plan Épargne Retraite | | article83 |Article 83 | | rsp |Réserve spéciale de participation | | pea |Plan d'épargne en actions | | capitalisation|Contrat de capitalisation | | perp |Plan d'épargne retraite populaire | | madelin |Contrat retraite Madelin | | unknown |Inconnu | #### List of transaction types | Type |Description | | ----------- |-----------------------------------| |transfer |Transfers | |order |Orders | |check |Checks | |deposit |Cash deposit | |payback |Payback | |withdrawal |Withdrawal | |loan_payment |Loan payment | |bank |Bank fees | |card |Card operation | |deferred_card |Deferred card operation | |card_summary |Mensual debit of a deferred card | #### List of synchronization errors ##### Error on Connection object The error field may take one of the below values in case of error when accessing the user space. | Error |Description | | ----------------------- |--------------------------------------------------------------------------------------------------| |wrongpass |The authentication on website has failed | |additionalInformationNeeded |Additional information is needed such as an OTP | |websiteUnavailable |The website is unavailable, for instance we get a HTTP 503 response when requesting the website | |actionNeeded |An action is needed on the website by the user, scraping is blocked | |SCARequired |An SCA process must be done by updating the connection | |decoupled |Requires a user validation (ex: digital key)| |passwordExpired |The password has expired and needs to be changed on the website. | |webauthRequired |A complete authentication process is required by update the connection via redirect | |bug |A bug has occurred during the synchronization. An alert has been sent to Budget Insight | #### Error on Account object Errors can be filled at the account level in case we access the user's dashboard but some account related data cannot be retrieved. For instance, we may not access the transactions or investments for a specific account. Getting an error during an account synchronization does not impact the scraping of other acccounts. | Error |Description | | ----------------------- |--------------------------------------------------------------------------------------------------| |websiteUnavailable |The website or a page is unavailable | |actionNeeded |An action is needed on the website by the user, scraping is blocked | |bug |A bug has occurred during the synchronization. An alert has been sent to Budget Insight | Now you know the basics of Budgea API - Basic call to retrieve resources - Add query parameters to aplly filters - Expand resources - Authenticated calls We're good for the basics! Now let's see how to integrate Budgea in your app and create your first user. ## Integrate Budgea *(protocol or Webview)* ### The workflow Users of your application exist in the Budgea API. Every User is identified by an access_token which is the shared secret between your application and our API. The workflow is as below: 1. The user is on your application and wants to share his bank accounts or invoices. 2. A call is made **client side** (browser's javascript or desktop application) to create a temporarily token which will be used to make API calls. 3. A form is built, allowing the user to select the connector to use (bank or provider, depending on context). Every connector requires different kind of credentials. 4. A call on the API is made with the temporarily token to add a **Connection** with the credentials supplied by user. 5. In case of success, the user chooses what bank accounts (**Account**) or subscriptions (**Subscription**) he wants to share with your application. 6. When he validates the share, the temporarily token is transmitted to your server. This one will call the Budgea API with this token to get a permanent token. **Note** In case your application works without a server (for example a desktop application), the permanent token can be obtained on the 1st step, by supplying a client_secret to /auth/init and the step 6 is omitted. To get more information, read the protocol. There are 3 steps to integrate Budgea in your application: 1. Provide a way for your users to share their credentials with you 2. Get the data scraped from Budgea 3. Be sure to follow the good practices before going into production ### Get credentials from users You have 2 options here: - Integrate the Budget Insight's Webview, a turnkey solution to get user's credentials - Create your own form following the protocol (must have the *agent* status) ### Budgea webview The Budgea webview complements REST API endpoints with web-based services to handle sensitive or complex operations: - add a connection (to a bank or a provider), or edit/repare access to a connection; - manage connections (add/remove/edit); - edit and validate bank transfers (alpha preview). Usage of the webview is mandatory if you don't hold an Agent status, since you are not allowed to use API endpoints carrying user credentials, and optional otherwise. #### Implementation guidelines ##### Base URL The base URL of all services must be customized: `https://{{domain}}.biapi.pro/2.0/auth/webview/` `https://{{domain}}.biapi.pro/2.0/auth/webview/{{lang}}/` - `{{domain}}`: substitute with you API domain; - `{{lang}}`: optionally specify the language of the webview, `en` or `fr` (if not specified, an automatic redirection will be performed following the language of the browser). ##### Browser integration Services available as part of the webview are designed as parameterized URLs intended to be opened in a web browser. A callback URI must be specified by callers to be notified at the end of the operation flow, similar to OAuth 2 specification. You are encouraged to integrate web-based steps in your product following UX best practices: - in a web environment, perform a full-page redirect to the URL (using either [HTTP redirect](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/302) or [scripting](https://developer.mozilla.org/fr/docs/Web/API/Location)), and avoid new tabs or popups; - in a native Android app, prefer opening the default browser or relying on [Chrome Custom Tabs](https://developer.chrome.com/multidevice/android/customtabs) to integrating a WebView; - in a native iOS app, prefer using a [SFSafariViewController](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller) to integrating a WKWebView. ##### Callback handling Most flows redirect to a callback URI at the end of the process. Query parameters are added to the URI to identify successful or failed operations. Successful parameters are specific to each flow. In case of an error, the following parameters are added: | Parameter | Description | | - | - | | `error` | An lowercase string error code identifying the kind of error that occurred. When the parameter is not present, the response is successful. | | `error_description` | A longer string description of the error (not intended for user display). | Common error codes include: | Code | Description | | - | - | | `access_denied` | The user explicitly cancelled the flow. | | `server_error` | Oops, a technical failure occurred during the process. | **Forward compatibility requirement**: Additional error codes may be added in the future to describe specific cases. When implementing error codes handling, always fallback to a generic case for unknown codes. ##### Browser compatibility The webview is designed and tested to work with browsers supported by the Angular framework: https://angular.io/guide/browser-support ##### Privacy / GDPR status The webview itself does not use any kind of long-term data persistence mechanism such as cookies or local storage, but some authentication or authorization steps may delegate to third-party web services that may implement them. #### Configuration You can configure the appearance and behaviour of the webview by configuring the associated *Client Application* in the console: | Key | Format | Description | | - | - | - | | `primary_color` | String | Optional. An accent color (hexadecimal string without '#' prefix) to personalize the UI elements of the webview. If absent, the default color is grey. | | `redirect_uri` | String | Optional. A recommended security whitelist configuration. The `redirect_uri` parameter sent to any endpoint of the webview is checked against the configuration, if any. | | `config.disable_connector_hints` | Boolean | Optional. This flags hides the list of most-used entries in the connector selection step. The default is `false`, i.e. the list is shown. | | `config.use_app_layout` | Boolean | Optional. Use this flag to enable presenting your log as an app icon. The default value is ` false`, i.e. the logo is shown in the top bar of the UI. | | `config.disable_accounts_pre_check` | Boolean | Optional. An optional boolean flag to prevent bank accounts to be automatically pre-checked when the user enters the activation step. The default value is ` false`, i.e. the bank accounts are pre-checked. | #### Endpoints reference ##### Add connection flow ``` https://{{domain}}.biapi.pro/2.0/auth/webview/{{lang}}/connect ``` This flow allows an end-user to add a new connection to the API. The flow handles the following steps: - selecting a connector; - authenticating & authorizing with the connector, by collecting credentials or delegating; - managing consent to aggregate accounts/subscriptions; - collecting required information for professional accounts. ###### Endpoint parameters | Parameter | Description | | - | - | | `client_id` | Required. The ID of the requesting client application. You can manage client applications of your domain in the admin console. | | `redirect_uri` | Required. An absolute callback URI. The webview will redirect to it at the end of the flow. | | `code` | Optional. A user-scoped temporary code to use with the Budgea API.
If you don't provide a code, a new anonymous user will be created before the connection is added, and you will be returned an access token code scoped to it with the success callback. | | `state` | Optional. An opaque string parameter that you can use to carry state across the flow. The parameter will be set "as is" on the callback URI. Make sure that the `state` you provide is properly URL-encoded. | | `connector_ids` | Optional. A comma-separated list of connector IDs available to pick from.
If the parameter is omitted, all active connectors are available.
If you pass a single value, the user is not prompted to choose the connector.
This parameter is mutually exclusive with `connector_uuids`. | | `connector_uuids` | Optional. A comma-separated list of connector UUIDs available to pick from.
If the parameter is omitted, all active connectors are available.
If you pass a single value, the user is not prompted to choose the connector.
This parameter is mutually exclusive with `connector_ids`. | | `connector_capabilities` | Optional. A comma-separated list of capabilities to filter available connectors.
If the parameter is omitted, `bank` is inferred.
If multiple values are provided, only connectors that expose all the requested capabilities are available.
To request a bank connection, use `bank`.
To request a provider connection, use `document`. | | `account_ibans` | Optional. A comma-separated list of IBANs to filter accounts available for activation in a bank connection context. Other accounts will not be selectable. | | `account_types` | Optional. A comma-separated list of account types to filter accounts available for activation in a bank connection context. Other accounts will not be selectable. | | `account_usages` | Optional. A comma-separated list of account usages to filter accounts available for activation in a bank connection context. Other accounts will not be selectable. | ###### Successful callback parameters | Parameter | Description | | - | - | | `connection_id` | The id of the newly created connection. Please note that when redirecting to the callback URI, the accounts and/or subscriptions are available in the API, but bank transactions or documents may still be syncing in background. | | `code` | Optional. If a `code` was *not* initially specified, an API code that you must exchange to obtain a permanent access token associated with the newly-created anonymous user holding the connection. The parameter is URL-encoded, make sure to handle it accordingly. | | `state` | Optional. Identical to the `state` parameter that was initially specified. | ###### Additional error codes | Code | Description | | - | - | | `tos_declined` | The end-user refused to validate the terms of service. | ##### Re-auth / edit connection credentials flow ``` https://{{domain}}.biapi.pro/2.0/auth/webview/{{lang}}/reconnect ``` This flow allows an end-user to re-authenticate against a bank or a provider in order to recover an existing connection, or to completely reset credentials associated with a connection. ###### Endpoint parameters | Parameter | Description | | - | - | | `client_id` | Required. The ID of the requesting client application. You can manage client applications of your domain in the admin console. | | `redirect_uri` | Required. An absolute callback URI. The webview will redirect to it at the end of the flow. | | `code` | Required. A user-scoped temporary code to use with the Budgea API. | | `connection_id` | Required. The id of the existing connection. | | `state` | Optional. An opaque string parameter that you can use to carry state across the flow. The parameter will be set "as is" on the callback URI. Make sure that the `state` you provide is properly URL-encoded. | | `reset_credentials` | Optional. In the default mode (`false`), the service will try to recover the connection and prompt the user only with outdated or transient information (new password, OTP...).
Set the parameter to `true` to force resetting all the credentials associated with the connection. This parameter may not apply to all connectors. | ###### Successful callback parameters This flow adds no parameter to the callback URI in case of success, except from `state`. ##### Manage connections ``` https://{{domain}}.biapi.pro/2.0/auth/webview/{{lang}}/manage ``` This flow allows an end-user to manage the connections associated with his account in the API. The user can add new connections, remove existing ones, fix connection errors, reset credentials or activate/deactivate bank accounts. Support of `redirect_uri` in this flow is optional, as it can be integrated or presented as a terminal step, without relying on a final redirection. ###### Endpoint parameters | Parameter | Description | | - | - | | `client_id` | Required. The ID of the requesting client application. You can manage client applications of your domain in the admin console. | | `code` | Required. A user-scoped temporary code to use with the Budgea API. | | `redirect_uri` | Optional. An absolute callback URI. When provided, the webview will display a close button that redirects to it. | | `state` | Optional. An opaque string parameter that you can use to carry state across the flow when providing a `redirect_uri`. The parameter will be set "as is" on the callback URI. Make sure that the `state` you provide is properly URL-encoded. | | `connector_capabilities` | Optional. A comma-separated list of capabilities to filter available connectors when adding a new connection.
If the parameter is omitted, `bank` is inferred.
If multiple values are provided, only connectors that expose all the requested capabilities are available.
To request a bank connection, use `bank`.
To request a provider connection, use `document`. | | `account_types` | Optional. A comma-separated list of account types to filter accounts available for activation on adding a new bank connection or updating existing connections. Other accounts will not be selectable. | | `account_usages` | Optional. A comma-separated list of account usages to filter accounts available for activation in a bank connection context. Other accounts will not be selectable. | ###### Callback parameters This flow adds no parameter to the callback URI, except from `state`. ##### Execute a bank transfer (preview) **Disclaimer**: Transfer or payment services are available as a preview, protocols and parameters are subject to change in upcoming beta/final releases. ``` https://{{domain}}.biapi.pro/2.0/auth/webview/{{lang}}/transfer ``` This flow allows an end-user to execute a bank transfer. The flow handles the following steps: - if the transfer is not already created, all steps to authenticate with a bank, select the recipient, the emitter account, the amount and label; - executing the transfer, including managing SCAs for recipient registration and/or transfer validation. ###### Endpoint parameters | Parameter | Description | | - | - | | `client_id` | Required. The ID of the requesting client application. You can manage client applications of your domain in the admin console. | | `redirect_uri` | Required. An absolute callback URI. The webview will redirect to it at the end of the flow. | | `code` | Required. A user-scoped temporary code to use with the Budgea API.
If you don't provide a code, a new anonymous user will be created before a connection is added and the transfer is executed, and you will be returned an access token code scoped to it with the success callback. | | `state` | Optional. An opaque string parameter that you can use to carry state across the flow. The parameter will be set "as is" on the callback URI. Make sure that the `state` you provide is properly URL-encoded. | | `transfer_id`| Optional. The ID of an prepared transfer to be validated in the webview. The user cannot edit anything on the transfer before validation. | ###### Successfull callback parameters | Parameter | Description | | - | - | | `transfer_id` | The ID of the transfer that was created and executed. | | `code` | Optional. If a `code` was *not* initially specified, an API code that you can exchange to obtain a permanent access token associated with the newly-created anonymous user holding the transfer. The parameter is URL-encoded, make sure to handle it accordingly. | | `state` | Optional. Identical to the `state` parameter that was initially specified. | ###### Additional error codes | Code | Description | | - | - | | `tos_declined` | The end-user refused to validate the terms of service. | #### Migrating from v3 We provide a full backward compatibility layer with current implementations of the webview v3 to ease the transition. All endpoints remains accessible, with the same parameters and callback behaviour. Migration instructions are provided below. *The v3 compatibility mode is expected to be removed on 31 December 2019.* You should migrate your implementation a soon as possible to new endpoints and parameters. ##### Add connection flow / Edit connection credentials ``` /connect/select ``` This endpoint has been superseded by `/connect` (no suffix) for adding a new connection, and `/reconnect` for resetting or updating an existing connection. | Endpoint parameter | Migration instructions | | - | - | | `client_id` | No change. | | `redirect_uri`, `state` | No change. | | `response_type` | This parameter is not used anymore. | | `id_connector`, `connectors` | Superseded by `connector_ids` sent to the `/connect` endpoint. | | `types` | Superseded by `connector_capabilities` sent to the `/connect` endpoint.
Use`connector_capabilities=bank` (bank connection) or `connector_capabilities=document` (provider connection). | | `id_connection` | Superseded by `connection_id` sent to the `/reconnect` endpoint. | Passing the code or access token as an URL fragment is no longer supported, use the `code` query parameter. | Callback parameter | Migration instructions | | - | - | | `id_connection` | Superseded by `connection_id`.
In the `/reconnect` flow, this parameter is not returned anymore. | | `code` | Still named `code`, but in the `/connect` flow the parameter is now **only** added if an anonymous user was created, i.e. the `code` parameter was **not** provided as a query parameter or fragment.
In the `/reconnect` flow, this parameter is not returned anymore. | | `state` | No change. | ##### Manage connections ``` /accounts ``` This endpoint has been superseded by `/manage`, that now fully allows users to add/remove connections, reset their credentials or recover from error states. | Endpoint parameter | Migration instructions | | - | - | | `client_id` | No change. | | `redirect_uri`, `state` | No change, these parameters are now optional. | | `response_type` | This parameter is not used anymore. | | `types` | Superseded by `connector_capabilities`.
Use`connector_capabilities=bank` (bank connection) or `connector_capabilities=document` (provider connection). | Passing the code or access token as an URL fragment is no longer supported, use the `code` query parameter. | Callback parameter | Migration instructions | | - | - | | `code` | This parameter is not returned anymore. | | `state` | No change. | ##### Behaviour change In v3, the `/accounts` flow used to redirect to the `redirect_uri` after a connection addition. This is no longer the case in v4, where redirection is only performed when the user explicitly closes the flow. If you need to perform actions when a connection is added or removed, you should rely on webhooks. #### Protocol This section describes the protocol used to set bank and provider accounts of a user, in case you don't want to use the webview. The idea is to call the following services client-side (with AJAX in case of a web application), to ensure the bank and providers credentials will not be sent to your servers. 1. /auth/init ```http POST /auth/init ``` ```json { "auth_token" : "fBqjMZbYddebUGlkR445JKPA6pCoRaGb", "type" : "temporary", "expires_in" : 1800, "id_user": 1 } ``` This service creates a temporarily token, to use in the "Authorization" header in next calls to the API The returned token has a life-time of 30 minutes, and should be transfered to the API then (cf Permanent Token), so that your server can get a permanent access_token. It is possible to generate a permanent token immediately, by calling the service with the manage_token, or by supply parameters client_id and client_secret. 2. /banks or /providers ```http GET /banks?expand=fields Authorization: Bearer ``` ```json { "hidden" : false, "charged" : true, "name" : "American Express", "id" : 30, "fields" : [ { "values" : [ { "label" : "Particuliers/Professionnels", "value" : "pp" }, { "value" : "ent", "label" : "Entreprises" } ], "label" : "Type de compte", "regex" : null, "name" : "website", "type" : "list" }, { "type" : "password", "label" : "Code secret", "name" : "password", "regex" : "^[0-9]{6}$" } ], }, ... ], "total" : 44, } ``` You get a list of connectors, and all associated fields needed to build the form at step 3. You can also use that list to show to your user, all available banks. 3. /users/me/connections Make a POST request and supply the id_bank (ID of the chosen bank) or id_provider (ID of provider), and all requested fields as key/value parameters. For example: ```http POST /users/me/connections Authorization: Bearer -F login=12345678 -F password=123456 -F id_bank=59 ``` You can get the following return codes: |Code |Description | |---------------|------------------------------------------------------------ | |200 |The connection has succeed and has been created | |202 |It is necessary to provide complementary information. This occurs on the first connection on some kind of Boursorama accounts for example, where a SMS is sent to the customer. It is necessary to ask the user to fill fields requested in the fields, and do a POST again on /users/me/connections/ID, with the connection ID in id_connection. | |400 |Unable to connect to the website, the field error in the JSON can be **websiteUnavailable** or **wrongpass** | |403 |Invalid token | 4. Activate accounts The accounts the user wants to aggregate must be activated before any transaction or investment is retrieved. Several accounts can be activated in 1 request by separating the account ids with commas. ```http PUT /users/me/connections//accounts/?all ``` 5. Permanent token If the user validates the share of his accounts, it is necessary to transform the temporary code to a permanent access_token (so that the user won't expire). To do that, make a POST request on /auth/token/access with the following parameters: |Parameter |Description | |---------------------|----------------------------------------------------------------| |code |The temporarily token which will let you get the access_token | |client_id |The ID of your client application | |client_secret |The secret of your client application | ```json POST /auth/token/access { "client_id" : 17473055, "client_secret" : "54tHJHjvodbANVzaRtcLzlHGXQiOgw80", "code" : "fBqjMZbYddebUGlkR445JKPA6pCoRaGb" } ``` ```http HTTP/1.1 200 OK { "access_token" : "7wBPuFfb1Hod82f1+KNa0AmrkIuQ3h1G", "token_type":"Bearer" } ``` ### Update accounts Another important call is when a user wants to add/remove connections to banks or providers, or to change the password on one of them, it is advised to give him a temporarily code from the permanent access_token, with the following call (using the access_token as bearer): ```http POST /auth/token/code Authorization: Bearer ``` ```json { "code" : "/JiDppWgbmc+5ztHIUJtHl0ynYfw682Z", "type" : "temporary", "expires_in" : 1800, } ``` Its life-time is 30 minutes, and let the browser to list connections and accounts, via `GET /users/me/connections?expand=accounts` for example. To update the password of a connection, you can do a POST on the *connection* resource, with the field *password* in the data. The new credentials are checked to make sure they are valid, and the return codes are the same as when adding a connection. ## Getting the data (Webhooks) You have created your users and their connections, now it's time to get the data. There are 2 ways to retrieve it, the 2 can be complementary: - make regular calls to the API - use the webhooks (recommended) ### Manual Synchronization It is possible to do a manual synchronization of a user. We recommend to use this method in case the user wants fresh data after logging in. To trigger the synchronization, call the API as below: `PUT /users/ID/connections` The following call is blocking until the synchronization is terminated. Even if it is not recommended, it's possible to fetch synchronously new data. To do that, you can use the *expand* parameter: ` /users/ID/connections?expand=accounts[transactions,investments[type]],subscriptions` ```json { "connections" : [ { "accounts" : [ { "balance" : 7481.01, "currency" : { "symbol" : "€", "id" : "EUR", "prefix" : false }, "deleted" : null, "display" : true, "formatted_balance" : "7 481,01 €", "iban" : "FR76131048379405300290000016", "id" : 17, "id_connection" : 7, "investments" : [ { "code" : "FR0010330902", "description" : "", "diff" : -67.86, "id" : 55, "id_account" : 19, "id_type" : 1, "label" : "Agressor PEA", "portfolio_share" : 0.48, "prev_diff" : 2019.57, "quantity" : 7.338, "type" : { "color" : "AABBCC", "id" : 1, "name" : "Fonds action" }, "unitprice" : 488.98, "unitvalue" : 479.73, "valuation" : 3520.28 } ], "last_update" : "2015-07-04 15:17:30", "name" : "Compte chèque", "number" : "3002900000", "transactions" : [ { "active" : true, "application_date" : "2015-06-17", "coming" : false, "comment" : null, "commission" : null, "country" : null, "date" : "2015-06-18", "date_scraped" : "2015-07-04 15:17:30", "deleted" : null, "documents_count" : 0, "formatted_value" : "-16,22 €", "id" : 309, "id_account" : 17, "id_category" : 9998, "id_cluster" : null, "last_update" : "2015-07-04 15:17:30", "new" : true, "original_currency" : null, "original_value" : null, "original_wording" : "FACTURE CB HALL'S BEER", "rdate" : "2015-06-17", "simplified_wording" : "HALL'S BEER", "state" : "parsed", "stemmed_wording" : "HALL'S BEER", "type" : "card", "value" : -16.22, "wording" : "HALL'S BEER" } ], "type" : "checking" } ], "error" : null, "expire" : null, "id" : 7, "id_user" : 7, "id_bank" : 41, "last_update" : "2015-07-04 15:17:31" } ], "total" : 1, } ``` ### Background synchronizations & Webhooks Webhooks are callbacks sent to your server, when an event is triggered during a synchronization. Synchronizations are automatic, the frequency can be set using the configuration key `autosync.frequency`. Using webhooks allows you to get the most up-to-date data of your users, after each synchronization. The automatic synchronization makes it possible to recover new bank entries, or new invoices, at a given frequency. You have the possibility to add webhooks on several events, and choose to receive each one on a distinct URL. To see the list of available webhooks you can call the endpoint hereunder: ``` curl https://demo.biapi.pro/2.0/webhooks_events \ -H 'Authorization: Bearer ' ``` The background synchronizations for each user are independent, and their plannings are spread over the day so that they do not overload any website. Once the synchronization of a user is over, a POST request is sent on the callback URL you have defined, including all webhook data. A typical json sent to your server is as below: ```http POST /callback HTTP/1.1 Host: example.org Content-Length: 959 Accept-Encoding: gzip, deflate, compress Accept: */* User-Agent: Budgea API/2.0 Content-Type: application/json; charset=utf-8 Authorization: Bearer sl/wuqgD2eOo+4Zf9FjvAz3YJgU+JKsJ { "connections" : [ { "accounts" : [ { "balance" : 7481.01, "currency" : { "symbol" : "€", "id" : "EUR", "prefix" : false }, "deleted" : null, "display" : true, "formatted_balance" : "7 481,01 €", "iban" : "FR76131048379405300290000016", "id" : 17, "id_connection" : 7, "investments" : [ { "code" : "FR0010330902", "description" : "", "diff" : -67.86, "id" : 55, "id_account" : 19, "id_type" : 1, "label" : "Agressor PEA", "portfolio_share" : 0.48, "prev_diff" : 2019.57, "quantity" : 7.338, "type" : { "color" : "AABBCC", "id" : 1, "name" : "Fonds action" }, "unitprice" : 488.98, "unitvalue" : 479.73, "valuation" : 3520.28 } ], "last_update" : "2015-07-04 15:17:30", "name" : "Compte chèque", "number" : "3002900000", "transactions" : [ { "active" : true, "application_date" : "2015-06-17", "coming" : false, "comment" : null, "commission" : null, "country" : null, "date" : "2015-06-18", "date_scraped" : "2015-07-04 15:17:30", "deleted" : null, "documents_count" : 0, "formatted_value" : "-16,22 €", "id" : 309, "id_account" : 17, "id_category" : 9998, "id_cluster" : null, "last_update" : "2015-07-04 15:17:30", "new" : true, "original_currency" : null, "original_value" : null, "original_wording" : "FACTURE CB HALL'S BEER", "rdate" : "2015-06-17", "simplified_wording" : "HALL'S BEER", "state" : "parsed", "stemmed_wording" : "HALL'S BEER", "type" : "card", "value" : -16.22, "wording" : "HALL'S BEER" } ], "type" : "checking" } ], "bank" : { "id_weboob" : "ing", "charged" : true, "name" : "ING Direct", "id" : 7, "hidden" : false }, "error" : null, "expire" : null, "id" : 7, "id_user" : 7, "id_bank" : 41, "last_update" : "2015-07-04 15:17:31" } ], "total" : 1, "user" : { "signin" : "2015-07-04 15:17:29", "id" : 7, "platform" : "sharedAccess" } } ``` The authentication on the callback is made with the access_token of the user (which is a shared secret between your server and the Budgea API). When you are in production, it is needed to define a HTTPS URL using a valid certificate, delivered by a recognized authority. If this is not the case, you can contact us to add your CA (Certificate Authority) to our PKI (Public Key Infrastructure). Important: it is necessary to send back a HTTP 200 code, without what we consider that data is not correctly taken into account on your system, and it will be sent again at the next user synchronization. ## Guidelines for production Now you should have integrated the API inside your application. Make sure your Webhooks URLs are in HTTPS, if so you can enable the production state of the API. To make things great, here are some good practices, please check you have respected them: - You have provided to your users a way to configure their accounts - You have provided to your users a way to change their account passwords - You consider the **error** field of Connections, to alert the user in case the state is **wrongpass** - You map IDs of Accounts, Subscriptions, Transactions and Documents in your application, to be sure to correctly match them - When the deleted field is set on a bank transaction, you delete it in your database - You don't loop on all users to launch synchronizations, this might saturate the service If you have questions about above points, please contact us. Otherwise, you can put into production! ### Going further If you want to raise the bar for your app and add features such as the ability to do transfers, get invoices, aggregate patrimony and more, please refer to the sections below. We'll discuss complementary APIs building upon the aggregation, allowing for the best of financial apps. ## Budgea API Pay This API allows for the emition of transfers between the aggregated accounts. Just like the simple aggregation, BI provides a webview or a protocol to follow, to implement this feature. ### API pay protocol This section describes how the transfer and recipient protocol work, in case you don't want to integrate the webview. The idea is to do following calls client side (with AJAX in case of a web application), so that the interaction with the Budgea API is transparent. #### Executing a transfer 1. /auth/token/code If you do calls client side, get a new temporary code for the user, from the access_token. This will prevent security issues. ``` curl -d '' \ https://demo.biapi.pro/2.0/auth/token/code \ -H 'Authorization: Bearer ' ``` ```json { "code": "/JiDppWgbmc+5ztHIUJtHl0ynYfw682Z", "type": "temporary", "expires_in": 1800 } ``` The returned token has a life-time of 30 minutes. 2. /users/me/accounts?able_to_transfer=1 List all the accounts that can do transfers. Authenticate the call with the code you got at step 1. ``` curl https://demo.biapi.pro/2.0/users/me/accounts?able_to_transfer=1 \ -H 'Authorization: Bearer /JiDppWgbmc+5ztHIUJtHl0ynYfw682Z' ``` ```json { "accounts" : [ { "display" : true, "balance" : 2893.36, "id_type" : 2, "number" : "****1572", "type" : "checking", "deleted" : null, "bic" : "BNPAFRPPXXX", "bookmarked" : false, "coming" : -2702.74, "id_user" : 1, "original_name" : "Compte de chèques", "currency" : { "symbol" : "€", "id" : "EUR", "prefix" : false }, "name" : "lol", "iban" : "FR7630004012550000041157244", "last_update" : "2016-12-28 12:31:04", "id" : 723, "formatted_balance" : "2893,36 €", "able_to_transfer" : true, "id_connection" : 202 } ], "total" : 1 } ``` 3. /users/me/accounts/ID/recipients List all available recipients for a given account. ``` curl https://demo.biapi.pro/2.0/users/me/accounts/723/recipients?limit=1 \ -H 'Authorization: Bearer /JiDppWgbmc+5ztHIUJtHl0ynYfw682Z' ``` ```json { "total" : 27, "recipients" : [ { "bank_name" : "BNP PARIBAS", "bic" : "BNPAFRPPXXX", "category" : "Interne", "deleted" : null, "enabled_at" : "2016-10-31 18:52:53", "expire" : null, "iban" : "FR7630004012550003027641744", "id" : 1, "id_account" : 1, "id_target_account" : 2, "label" : "Livret A", "last_update" : "2016-12-05 12:07:24", "time_scraped" : "2016-10-31 18:52:54", "webid" : "2741588268268091098819849694548441184167285851255682796371" } ] } ``` 4. /users/me/accounts/ID/recipients/ID/transfers Create the transfer ``` curl \ https://demo.biapi.pro/2.0/users/me/accounts/1/recipients/1/transfers \ -H 'Authorization: Bearer /JiDppWgbmc+5ztHIUJtHl0ynYfw682Z' \ -F amount=10, \ -F label="Test virement", \ -F exec_date="2018-09-12" // optional ``` ```json { "account_iban" : "FR7630004012550000041157244", "amount" : 10, "currency" : { "id" : "EUR", "prefix" : false, "symbol" : "€" }, "exec_date" : "2018-09-12", "fees" : null "formatted_amount" : "10,00 €", "id" : 22, "id_account" : 1,, "id_recipient" : 1, "label" : "Test virement", "recipient_iban" : "FR7630004012550003027641744", "register_date" : "2018-09-12 10:34:59", "state" : "created", "webid" : null } ``` 5. /users/me/transfers/ID Execute the transfer ``` curl \ https://demo.biapi.pro/2.0/users/me/transfers/22 \ -H 'Authorization: Bearer /JiDppWgbmc+5ztHIUJtHl0ynYfw682Z' \ -F validated=true ``` ```json { "account_iban" : "FR7630004012550000041157244", "amount" : 10, "currency" : { "id" : "EUR", "prefix" : false, "symbol" : "€" }, "exec_date" : "2016-12-19", "fees" : null, "fields" : [ { "label" : "Code secret BNP Paribas", "type" : "password", "regex" : "^[0-9]{6}$", "name" : "password" } ], "formatted_amount" : "10,00 €", "id" : 22, "id_account" : 1, "id_recipient" : 1, "label" : "Test virement", "recipient_iban" : "FR7630004012550003027641744", "register_date" : "2016-12-19 10:34:59", "state" : "created", "webid" : null } ``` Here, an authentication step asks user to enter his bank password. The transfer can be validated with: ``` curl \ https://demo.biapi.pro/2.0/users/me/transfers/22 \ -H 'Authorization: Bearer /JiDppWgbmc+5ztHIUJtHl0ynYfw682Z' \ -F validated=true \ -F password="123456" ``` ```json { "account_iban" : "FR7630004012550000041157244", "currency" : { "id" : "EUR", "prefix" : false, "symbol" : "€" }, "amount" : 10, "exec_date" : "2016-12-19", "fees" : 0, "formatted_amount" : "10,00 €", "id" : 22, "id_account" : 1, "id_recipient" : 1, "label" : "Test virement", "recipient_iban" : "FR7630004012550003027641744", "register_date" : "2016-12-19 10:34:59", "state" : "pending", "webid" : "ZZ10C4FKSNP05TK95" } ``` The field state is changed to *pending*, telling that the transfer has been correctly executed on the bank. A connection synchronization is then launched, to find the bank transaction in the movements history. In this case, the transfer state will be changed to *done*. #### Adding a recipient 1. /auth/token/code Get a temporary token for the user. Same procedure than step 1 for a transfer. 2. /users/me/accounts?able_to_transfer=1 List accounts allowing transfers. Same procedure than step 2 for a transfer. 3. /users/me/accounts/ID/recipients/ Add a new recipient. ``` curl \ https://demo.biapi.pro/2.0/users/me/accounts/1/recipients \ -H 'Authorization: Bearer /JiDppWgbmc+5ztHIUJtHl0ynYfw682Z' \ -F iban=FR7613048379405300290000355 \ -F label="Papa", \ -F category="Famille" // optional ``` ```json { "bank_name" : "BNP PARIBAS", "bic" : "BNPAFRPPXXX", "category" : "Famille", "deleted" : null, "enabled_at" : null, "expire" : "2017-04-29 16:56:20", "fields" : [ { "label" : "Veuillez entrer le code reçu par SMS", "type" : "password", "regex" : "^[0-9]{6}$", "name" : "sms" } ], "iban" : "FR7613048379405300290000355", "id" : 2, "id_account" : 1, "id_target_account" : null, "label" : "Papa", "last_update" : "2017-04-29 16:26:20", "time_scraped" : null, "webid" : null } ``` It is necessary to post on the object Recipient with the requested fields (here sms), until the add is validated: ``` curl \ https://demo.biapi.pro/2.0/users/me/accounts/1/recipients/2 \ -H 'Authorization: Bearer /JiDppWgbmc+5ztHIUJtHl0ynYfw682Z' \ -F sms="123456" ``` ```json { "bank_name" : "BNP PARIBAS", "bic" : "BNPAFRPPXXX", "category" : "Famille", "deleted" : null, "enabled_at" : "2017-05-01 00:00:00", "expire" : null, "iban" : "FR7613048379405300290000355", "id" : 2, "id_account" : 1, "id_target_account" : null, "label" : "Papa", "last_update" : "2017-04-29 16:26:20", "time_scraped" : null, "webid" : "2741588268268091098819849694548441184167285851255682796371" } ``` If the field enabled_at is in the future, it means that it isn't possible yet to execute a transfer, as the bank requires to wait a validation period. ### API Pay Webview This section describes how to integrate the webview of the Budgea Pay API inside your application, to let your users do transfers to their recipients. #### User redirection To redirect the user to the webview, it is necessary to build a URI authenticated with a temporary token. This can be done from our library, or by calling the endpoint `/auth/token/code` (see the protocol section for an example). If the parameter **redirect_uri** is supplied, the user will be redirected to that page once the transfer is done. #### List of pages Here are a list a pages you may call to redirect your user directly on a page of the process: |Path |Description of the page | |-------------------------------------|----------------------------------------------------------------------------------| |/transfers |List Transfers | |/transfers/accounts |List emitter accounts | |/transfers/accounts/id/recipients |List recipients | |/transfers/accounts/id/recipients/id |Initialization of a transfer between the account and the recipient | |/transfers/id |Detail of a given transfer | ## Deprecated This section lists all the deprecated features in Budgea API. The associated date is the date of its removal. **Do not use them**. ### Key Investments (**2019-06-24**) Adding a temporary new key "all_investments" that will include deleted investments in the **webhooks**. ### No automatic expand on User objects (**2019-07-30**) In the API responses, by default, User objects won't display the keys "config", "alert_settings" and "invites" anymore. You will still be able to access this data by expanding the request. Example: GET /users/me/?expand=alert_settings,config ### Renaming of "type" field for jwt tokens (**2019-07-30**) For user's tokens in the jwt format, the "type" field will be renamed from "shared_access" to "sharedAccess".

This is a Billingo API v3 documentation. Our API based on REST software architectural style. API has resource-oriented URLs, accepts JSON-encoded request bodies and returns JSON-encoded responses. To use this API you have to generate a new API key on our [site](https://app.billingo.hu/api-key). After that, you can test your API key on this page.

BIN lookup API, the free api service from bintable.com to lookup card information using it's BIN. the service maintains updated database based on the comunity and other third party services to make sure all BINs in the database are accurate and up to date.

API Interface to retrieve company data and products from business registers

***UPDATE:*** *We have released a [beta version of the new bunq API documentation.](https://beta.doc.bunq.com)* ***NOTICE:*** *We have updated the sandbox base url to `https://public-api.sandbox.bunq.com/v1/`. Please update your applications accordingly. Check here: for more info.* ***PSD2 NOTICE:*** *The second Payment Services Directive (PSD2) may affect your current or planned usage of our public API, as some of the API services are now subject to a permit. Please be aware that using our public API without the required PSD2 permit is at your own risk and take notice of our updated API Terms and Conditions on for more information.* # Introduction Welcome to bunq! - The bunq API is organised around REST. JSON will be returned in almost all responses from the API, including errors but excluding binary (image) files. - Please configure your implementation to send its API requests to `https://public-api.sandbox.bunq.com/v1/` - There is a version of the [Android app](https://appstore.bunq.com/api/android/builds/bunq-android-sandbox-master.apk) that connects to the bunq Sandbox environment. To create accounts for the Sandbox app, please follow the steps in the [Android Emulator](#android-emulator) section. ## Getting started Before you start sending API requests, you need to get an API key and activate it. API activation happens when you install the API key and link your IP address and device to it *(create an API context)*. The steps below will guide you through what you need to do to start sending custom API requests. Here is an overview of what you can use to get started with the bunq API: 1. **Create an API key.** You can do it either in our [developer portal](https://developer.bunq.com) or in the bunq app *(Profile → Security & Settings → Developers → API keys)*. If you want to test our sandbox first, our [bunq Developer ](https://developer.bunq.com)is the best place to start. 2. **Register a device.** A device can be a phone (private), computer or a server (public). You can register a new device by using the `POST /installation` and `POST /device-server` calls. This will activate your API key. You only need to do this once. 3. **Open a session.** Sessions are temporary and expire after the auto-logout time set for the user account. It can be changed by the account owner in the bunq app. 4. **Make your first call!**  ## Versioning Developments in the financial sector, changing regulatory regimes and new feature requests require us to be flexible. This means we can iterate quickly to improve the API and related tooling. Therefore, we have chosen not to attach any version numbers to the changes just yet. We will inform you in a timely manner of any important changes we make before they are deployed on together.bunq.com. You can also [subscribe to our API newsletter](https://bunq.us8.list-manage.com/subscribe?u=c00d0d6daea4e1cf7c863d52e&id=b08680cdc7) to make sure you don't miss any important updates. # OAuth ## What is OAuth? [OAuth 2.0](https://www.oauth.com/oauth2-servers/getting-ready/) is a protocol that will let your app connect to bunq users in a safe and easy way. Please be aware that if you will gain access to the account information of other bunq users or initiate a payment for them, [you may require a PSD2 permit](https://beta.doc.bunq.com/other/faq#can-we-use-the-bunq-api-to-offer-services-to-third-parties). ## Get started with OAuth for bunq To initiate authorization into the bunq user accounts, you need to create an OAuth Client and register at least 1 redirect URL for it. You can have 1 OAuth Client at a time. Reuse your OAuth credentials for every authorization request. The list of steps below will help you to get started: 1. Register an OAuth Client by creating an app in [bunq Developer](https://developer.bunq.com/portal)_._ 2. Add one or more Redirect URLs. 3. Get your `client_id` and `secret` from your app information tab in [bunq Developer](https://developer.bunq.com/portal). 4. Redirect your users to the [OAuth authorization request URL](#oauth-authorization-request). 5. If the user accepts the authorization request, they will be redirected to the previously specified `redirect_uri` with an authorization `code` parameter. 6. Use the [token endpoint](#oauth-token-exchange) to exchange the authorization `code` for an `access_token`. 7. Use the `access_token` as a normal API Key. Open a session or use [our SDKs](https://github.com/bunq) to get started. You can set up an OAuth Client and add redirect URLs to it using the dedicated endpoints too. Follow the flow below to do it programmatically. ℹ️ As a PSD2 user, you cannot log in to the bunq app. You need to follow the flow below to register an OAuth Client for your application.  ## What can my apps do with OAuth? We decided to launch OAuth with a default permission that allows you to perform the following actions: - read and create Monetary Accounts; - read Payments & Transactions; - create Payments between Monetary Accounts of the same user; - create Draft-Payments (the user will need to approve the payment using the bunq app); - assign a Monetary account to a Card; - read, create and manage Cards; - read and create Request-Inquiries - read Request-Responses. As a PSD2-licensed developer, you are limited to the permission scopes of your role. ## Authorization request Your web or mobile app should redirect users to the following URL: `https://oauth.bunq.com/auth` The following parameters should be passed: - `response_type` - bunq supports the authorization code grant, provide `code` as parameter (required) - `client_id` - your Client ID, get it from the bunq app (required) - `redirect_uri` - the URL you wish the user to be redirected after the authorization, make sure you register the Redirect URL in the bunq app (required) - `state` - a unique string to be passed back upon completion (optional) Use `https://oauth.sandbox.bunq.com/auth` in the sandbox environment. **Authorization request example:** ``` https://oauth.bunq.com/auth?response_type=code &client_id=1cc540b6e7a4fa3a862620d0751771500ed453b0bef89cd60e36b7db6260f813 &redirect_uri=https://www.bunq.com &state=594f5548-6dfb-4b02-8620-08e03a9469e6 ``` **Authorization request response:** ``` https://www.bunq.com/?code=7d272be434a75933f40c13d56aef6c31496005b653074f7d6ac57029d9995d30 &state=594f5548-6dfb-4b02-8620-08e03a9469e6 ```  ## Token exchange If the authorization request is accepted by the user, you get the authorization `code`_._ Exchange it for an `access_token`. Make a `POST` call to `https://api.oauth.bunq.com/v1/token` . Pass the following parameters as `GET` variables: - `grant_type` - the grant type used, `authorization_code` for now (required) - `code` - the authorization code received from bunq (required) - `redirect_uri` - the same Redirect URL used in the authorisation request (required) - `client_id` - your Client ID (required) - `client_secret` - your Client Secret (required) Use `https://api-oauth.sandbox.bunq.com/v1/token` in the sandbox environment. **Token request example:** ``` https://api.oauth.bunq.com/v1/token?grant_type=authorization_code &code=7d272be434a75933f40c13d56aef6c31496005b653074f7d6ac57029d9995d30 &redirect_uri=https://www.bunq.com/ &client_id=1cc540b6e7a4fa3a862620d0751771500ed453b0bef89cd60e36b7db6260f813 &client_secret=184f969765f6f74f53bf563ae3e9f891aec9179157601d25221d57f2f1151fd5 ``` Note: The request should only contain URL parameters. No body is expected. **Example successful response:** ```json { "access_token": "8baec0ac1aafca3345d5b811042feecfe0272514c5d09a69b5fbc84cb1c06029", "token_type": "bearer", "state": "594f5548-6dfb-4b02-8620-08e03a9469e6" } ``` **Example error response:** ```json { "error": "invalid_grant", "error_description": "The authorization code is invalid or expired." } ``` ## What's next? To start sending calls to the account of the user who has accepted your authorization request, create an API context for the `access_token` you have received as the result of the token exchange. The `access_token` can be used as a normal API key. Please continue with [Authentication](#authentication). **NOTE:** When connecting to a bunq user's account using OAuth, you create a new user \(`userApiKey`\) that has its own `id` and `access_token` . When sending a request on behalf of a user connected to your app via OAuth, use the `id` of `userApiKey` as `userId` and the item `id`s of the bunq user \(`grantedByUser`\). **Example of a successful request URL:** ```text https://api.bunq.com/user/{userApiKey's userId}/monetary-account/{grantedByUser's monetary-accountId}/payment ``` When calling `GET /user/{userID}`, you might expect to get `UserPerson` or `UserCompany`. Instead, you will get the `UserApiKey` object, which contains references to both the user that requested access *(you)* and the user that granted access *(the bunq user account that you connected to)*. .jpg?alt=media&token=d1f212a2-3105-4f0e-a980-34b04a12998a) ## Using the Connect button All good? Ready to connect to your bunq users? Refer to our style guide and use the following assets when implementing the **Connect to bunq** button. - [Style guide](https://bunq.com/info/oauth-styleguide) - [Connect button assets](https://bunq.com/info/oauth-connect-buttons) Visit us on together.bunq.com, share your creations, ask question and build your very own bunq app! # Authentication - All requests must use HTTPS. HTTP calls will fail. - You should use SSL Certificate Pinning and Hostname Verification to ensure your connection with bunq is secure. - The auto logout time that you set in the app applies to all your sessions including the API ones. If a request is made 30 minutes before a session expires, the session will automatically be extended. - We use extra signing on top of HTTPS encryption that you must implement yourself if you are not using the SDKs. ℹ️ *We use asymmetric cryptography for signing requests and encryption.* - The client (you) and the server (bunq) must have a pair of keys: a private key and a public key. You need to pre-generate your own pair of 2048-bit RSA keys in the PEM format aligned with the PKCS #8 standard. - The parties (you and bunq) exchange their public keys in the first step of the API context creation flow. All the following requests must be signed by both your application and the server. Pass your signature in the `X-Bunq-Client-Signature` header, and the server will return its signature in the `X-Bunq-Server-Signature` header. ## Device registration Before you can start calling the bunq API, you must activate your API key, which covers the following steps: * register your API key, device, and IP address\(es\) _\(only once to activate your API key\);_ * create a session via `POST /session-server`. We call this sequence of steps "creating an API context." If you are using OAuth to access a user account, you need to create an API context for the `access_token` you receive upon [authorization token exchange](https://doc.bunq.com/#/oauth) too. ### Using our SDKs 1. Go to our [GitHub](https://github.com/bunq) page. 2. Choose the SDK in your language of choice. 3. Find and use the part dedicated to creating an API context. [Run Tinker](https://developer.bunq.com/tinker-command-line-banking) to see a sample project using bunq SDKs in action. ### Using our API directly 1. Create an _Installation_ by calling `POST v1/installation` and passing your pre-generated public key. You will receive an installation _Token._ Use it when making the two following API calls. 2. Create a _DeviceServer_ via `POST v1/device-server`. Provide a description and a secret \(API key in this case\). 3. Create a _SessionServer_ by executing `POST v1/session-server`. You will receive an authentication _Token._ Use it in the API requests in this active session.​ [Import our Postman collection](https://github.com/bunq/postman) to see our pre-setup API context creation calls. It will automatically generate and pre-fill everything in the API calls that create context so you can inspect the process. ### IP addresses When using a standard API Key the DeviceServer and Installation that are created in this process are bound to the IP address they are created from. Afterwards it is only possible to add IP addresses via the Permitted IP endpoint. Using a Wildcard API Key gives you the freedom to make API calls from any IP address after the POST device-server. You can switch to a Wildcard API Key by tapping on “Allow All IP Addresses” in your API Key menu inside the bunq app. You can also programatically switch to a Wildcard API Key by passing your current ip and a `*` (asterisk) in the `permitted_ips` field of the device-server POST call. E.g: `["1.2.3.4", "*"]`. # Connect as a PSD2 service provider As a service provider, either an Account Information Service Provider (AISP), Payment Initiation Service Provider (PISP), or Card Based Payment Instrument Issuer (CBPII), you have obtained or are planning to obtain a license from your local supervisor. You will need your unique eIDAS certificate number to start using the PSD2-compliant bunq API on production. We accept pseudo certificates in the sandbox environment so you could test the flow. You can generate a test certificate using the command below. ⚠️ Make sure to include AISP and/or PISP in the name to generate a certificate with the roles. ``` openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -subj '/CN=My App PISP AISP/C=NL' ``` ## Register as a service provider Before you can read the information on bunq users or initiate payments, you need to register a PSD2 account and receive credentials that will enable you to access the bunq user accounts. 1. Execute `POST v1/installation` and get your installation *Token* with a unique random key pair. 1. Use the installation *Token* and your unique PSD2 certificate to call `POST v1/payment-service-provider-credential`. This will register your software. 1. Receive your API key in return. It will identify you as a PSD2 bunq API user. You will use it to start an OAuth flow. The session will last 90 days. After it closes, start a new session using the same API key. 1. Register a device by using `POST v1/device-server` using the API key for the secret and passing the installation *Token* in the `X-Bunq-Client-Authentication` header. 1. Create your first session by executing `POST v1/session-server`. Provide the installation *Token* in the `X-Bunq-Client-Authentication` header. You will receive a session *Token*. Use it in any following request in the `X-Bunq-Client-Authentication` header. **NOTE.** The first session will last 1 hour. Start a new session within 60 minutes.  ## Register your OAuth application Before you can start authenticating on behalf of a bunq user, you need to get *Client ID* and *Client Secret*, which will identify you in authorization requests to the user accounts. 1. Call `POST /v1/user/{userID}/oauth-client` to create an OAuth Client. 2. Add a redirect URL to the OAuth Client via `POST /user/{userID}/oauth-client/{oauth-clientID}/callback-url`. 3. Call `GET /v1/user/{userID}/oauth-client/{oauth-clientID}`. We will return your _Client ID_ and _Client Secret_. 4. You are ready to [initiate authorization requests](#oauth-authorization-request). The flow below will guide you through the full OAuth connection process. Note that you only need to create OAuth credentials once.  ## Access user accounts as an AISP As an AISP, you are allowed to authenticate in a user’s account and access \(read\) the following account information: 1. legal name 2. IBAN 3. nationality 4. card validity data 5. transaction history 6. account balance To read the user's information, you need to establish a connection with their bunq account. You can do it using an [authorization request](#oauth-authorization-request). Once a bunq user has confirmed the authorization request and you have done the [token exchange](#oauth-token-exchange), you can activate the Access Token \(use it as an API key\). Token activation happens when you create an API context \(install it and link your IP adrress and device to it\). See the [OAuth](https://beta.doc.bunq.com/basics/oauth) page for the full flow illustration. An active Access Token allows you to communicate with the bunq user’s account. You can use it to start a session to interact with the monetary accounts the user allows you to access.  ## Make payments as a PISP As a PISP, you are allowed to authenticate in a user’s account with the following permissions: read account information \(via`GET /user`\): * legal name; * IBAN; 2. initiate payments \(create draft payments via either `POST /user/{userID}/monetary-account/{monetary-accountID}/draft-payment` or `POST /user/{userID}/payment-service-provider-draft-payment`\) and read their statuses; 3. confirm that the account balance is sufficient for covering the payment \(via`POST /user/{userID}/confirmation-of-funds`\). The bunq API provides endpoints for different scenarios of the implementation of the payment initiation functionality. In particular, as a PISP user, you can build applications that initiate and authorize one-off or multiple incoming payments. Depending on the use case you are intending to deploy, you might need to initiate the OAuth authorization either before or after the payment initiation. ### Authorization of multiple (scheduled) payments It is possible to initiate payments from a bunq user's account having previously established an OAuth connection between your application and the bunq user's account. The bunq user will receive push notifications for each initiated payment. Once a bunq user has [confirmed they want to make payments via your application](https://beta.doc.bunq.com/psd2/connect-as-a-psd2-service-provider#register-your-application), you can initiate the payment confirmation flow. 1. Create a draft payment via `POST /user/{userID}/monetary-account/{monetary-accountID}/draft-payment`passing the following parameters: * `monetary-accountId and userId` (`userApiKey`'s `id`; see [OAuth](https://beta.doc.bunq.com/basics/oauth#user-id-vs-item-ids) for more information) in the endpoint URL; * the customer’s email address, phone number, or IBAN in the `counterparty_alias` field of the request body. 2. If the user confirms their intent to make the payment, bunq carries out the transaction. 3. Check the status of the payment via `GET /user/{userID}/monetary-account/{monetary-accountID}/draft-payment` using the draft payment `id` parameter returned in the previous step.  ### Single payment authorization It is possible to initiate payments having only the IBAN of the payer using `POST /user/{userID}/payment-service-provider-draft-payment`. In this case, the bunq user will accept the payment along with the authorization request. No additional push notifications are sent to the user. 1. Collect the bunq user's IBAN (and name) in the UI of your application. 2. Create a draft payment via `POST /user/{userID}/payment-service-provider-draft-payment`. 3. Initiate an [authorization request.](https://beta.doc.bunq.com/basics/oauth#authorization-request) Upon the QR-code scan, the bunq user will see and be able to either accept or reject the payment authorization request. 4. Check the status of the payment.  ## Confirm available funds as a CBPII As a CBPII, you are allowed to authenticate in a user’s account to validate the availability of funds for the payment in question. 1. Collect an alias for the bunq user's account (their name and IBAN, email address, or phone number). 2. Check the availability of funds via `POST /user/{userID}/confirmation-of-funds` passing the following information: * your `userId`; * the amount of money needed for the payment; * the name of the bunq user and the IBAN of the account (email address or phone number pointing at the user are also possible). # Signing ⚠️ **NOTE:** We deprecated the signing of the entire API request (the URL, headers and body). You only need to sign the request body. Requests with full request signatures are no longer validated. We are legally required to protect our users and their data from malicious attacks and intrusions. That is why we beyond having a secure https connection, we use [asymmetric cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography) for signing requests that create a session or payment. The use of signatures ensures the data is coming from the trusted party and was not modified after sending and before receiving. Request body signing is only mandatory for the following operations: - open a session; - create a payment; - create a scheduled payment; - any other operation that executes a payment such as the following: - accept a draft payment; - accept a scheduled payment; - accept a draft scheduled payment; - accept a payment request. You will know that the API call must be encrypted if you get the 466 error code. The signing mechanism is implemented in our [SDKs](https://github.com/bunq) so if you are using them you don't have to worry about the details described below. The signatures are created using the SHA256 cryptographic hash function and included (encoded in base 64) in the `X-Bunq-Client-Signature` request header and `X-Bunq-Server-Signature` response header. The data to sign is the following: - For requests: the body only. - For responses: the body only. For signing requests, the client must use the private key corresponding to the public key that was sent to the server in the installation API call. That public key is what the server will use to verify the signature when it receives the request. In that same call the server will respond with a server side public key, which the client must use to verify the server's signatures. The generated RSA key pair must have key lengths of 2048 bits and adhere to the PKCS #8 standard. ## Request signing example Consider the following request, a `POST` to `/v1/user/126/monetary-account/222/payment` (the JSON is formatted with newlines and indentations to make it more readable):

Header	Value
Cache-Control:	no-cache
User-Agent:	bunq-TestServer/1.00 sandbox/0.17b3
X-Bunq-Client-Authentication:	f15f1bbe1feba25efb00802fa127042b54101c8ec0a524c36464f5bb143d3b8b

```json { "amount": { "value": "12.50", "currency": "EUR" }, "counterparty_alias": { "type": "EMAIL", "value": "bravo@bunq.com" }, "description": "Payment for drinks." } ``` Let's sign that request. First create a variable `$dataToSign` containing the body of the request: ```json { "amount": { "value": "12.50", "currency": "EUR" }, "counterparty_alias": { "type": "EMAIL", "value": "bravo@bunq.com" }, "description": "Payment for drinks." } ``` Next, create the signature of `$dataToSign` using the SHA256 algorithm and the private key `$privateKey` of the Installation's key pair. In PHP, use the following to create a signature. The signature will be passed by reference into `$signature`. `openssl_sign($dataToSign, $signature, $privateKey, OPENSSL_ALGO_SHA256);` Encode the resulting `$signature` using base64, and add the resulting value to the request under the `X-Bunq-Client-Signature` header. You have just signed your request, and can send it! ## Response verifying example The response to the previous request is as follows (the JSON is formatted with newlines and indentations to make it more readable):

Header	Value
Access-Control-Allow-Origin:	*
Content-Type:	application/json
Date:	Thu, 07 Apr 2016 08:32:04 GMT
Server:	APACHE
Strict-Transport-Security:	max-age=31536000
Transfer-Encoding:	chunked
X-Bunq-Client-Response-Id:	89dcaa5c-fa55-4068-9822-3f87985d2268
X-Bunq-Client-Request-Id:	57061b04b67ef
X-Bunq-Server-Signature:	ee9sDfzEhQ2L6Rquyh2XmJyNWdSBOBo6Z2eUYuM4bAOBCn9N5vjs6k6RROpagxXFXdGI9sT15tYCaLe5FS9aciIuJmrVW/SZCDWq/nOvSThi7+BwD9JFdG7zfR4afC8qfVABmjuMrtjaUFSrthyHS/5wEuDuax9qUZn6sVXcgZEq49hy4yHrV8257I4sSQIHRmgds4BXcGhPp266Z6pxjzAJbfyzt5JgJ8/suxgKvm/nYhnOfsgIIYCgcyh4DRrQltohiSon6x1ZsRIfQnCDlDDghaIxbryLfinT5Y4eU1eiCkFB4D69S4HbFXYyAxlqtX2W6Tvax6rIM2MMPNOh4Q==
X-Frame-Options:	SAMEORIGIN

```json { "Response": [ { "Id": { "id": 1561 } } ] } ``` We need to verify that this response was sent by the bunq server and not from a man-in-the-middle: - Create a `$dataToSign` variable containing the body of the request. **NOTE:** We started to only sign the response body on April 28, 2020. Please make sure you validate our new response signature. So for our example above the response to sign will look like this: ``` {"Response":[{"Id":{"id":1561}}]} ``` Now, verify the signature of `$dataToVerify` using the SHA256 algorithm and the public key `$publicKey` of the server. In PHP, use the following to verify the signature. `openssl_sign($dataToVerify, $signature, $publicKey, OPENSSL_ALGO_SHA256);` ## Troubleshooting If you get an error telling you "The request signature is invalid", please check the following: - There are no redundant characters (extra spaces, trailing line breaks, etc.) in the data to sign. - Make sure the body is appended to the data to sign exactly as you're adding it to the request. - You have added the full body to the data to sign. - You use the data to sign to create a SHA256 hash signature. - You have base64 encoded the SHA256 hash signature before adding it to the request under `X-Bunq-Client-Signature`. # Headers HTTP headers allow your client and bunq to pass on additional information along with the request or response. While this is already implemented in our [SDKs](https://github.com/bunq), please follow these instructions to make sure you set appropriate headers for calls if using bunq API directly. ## Request headers ### Mandatory request headers #### Cache-Control `Cache-Control: no-cache` The standard HTTP Cache-Control header is required for all requests. #### User-Agent `User-Agent: bunq-TestServer/1.00 sandbox/0.17b3` The User-Agent header field should contain information about the user agent originating the request. There are no restrictions on the value of this header. #### X-Bunq-Client-Signature **⚠️ UPCOMING CHANGE:** Header and URL signature will stop being validated on April 28, 2020. Please [sign the request body](https://doc.bunq.com/#/signing) only. `X-Bunq-Client-Signature: XLOwEdyjF1d+tT2w7a7Epv4Yj7w74KncvVfq9mDJVvFRlsUaMLR2q4ISgT+5mkwQsSygRRbooxBqydw7IkqpuJay9g8eOngsFyIxSgf2vXGAQatLm47tLoUFGSQsRiYoKiTKkgBwA+/3dIpbDWd+Z7LEYVbHaHRKkEY9TJ22PpDlVgLLVaf2KGRiZ+9/+0OUsiiF1Fkd9aukv0iWT6N2n1P0qxpjW0aw8mC1nBSJuuk5yKtDCyQpqNyDQSOpQ8V56LNWM4Px5l6SQMzT8r6zk5DvrMAB9DlcRdUDcp/U9cg9kACXIgfquef3s7R8uyOWfKLSNBQpdVIpzljwNKI1Q` #### X-Bunq-Client-Authentication `X-Bunq-Client-Authentication: 622749ac8b00c81719ad0c7d822d3552e8ff153e3447eabed1a6713993749440` The authentication *token* is used to authenticate the source of the API call. It is required by all API calls except for `POST /v1/installation`. It is important to note that the device and session calls are using the token from the response of the installation call, while all the other calls use the token from the response of the session-server call: - Pass the **installation *Token*** you get in the response to the `POST /installation` call in the `/device-server` and `/session-server` calls. - Pass the **session *Token*** you get in the response to the `POST /session-server` call in all the other calls. ### Optional request headers #### X-Bunq-Language `X-Bunq-Language: en_US` `en_US` is the default language setting for responses and error descriptions. The X-Bunq-Language header must contain a preferred language indication. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore. Currently only the languages en_US and nl_NL are supported. Anything else will default to en_US. #### X-Bunq-Region `X-Bunq-Region: en_US` `en_US` is the default region for localization formatting. The X-Bunq-Region header must contain the region (country) of the client device. The value of this header is formatted as a ISO 639-1 language code plus a ISO 3166-1 alpha-2 country code, separated by an underscore. #### X-Bunq-Client-Request-Id `X-Bunq-Client-Request-Id: a4f0de` This header has to specify an ID with each request that is unique for the logged in user. There are no restrictions for the format of this ID. However, the server will respond with an error when the same ID is used again on the same DeviceServer. #### X-Bunq-Geolocation `X-Bunq-Geolocation: 4.89 53.2 12 100 NL` `X-Bunq-Geolocation: 0 0 0 0 000` *(if no geolocation is available or known)* This header has to specify the geolocation of the device. It makes it possible for bunq to map the geolocation with the payment. ‌ The format of this value is longitude latitude altitude radius country. The country is expected to be formatted of an ISO 3166-1 alpha-2 country code. When no geolocation is available or known the header must still be included but can be zero valued. ### Attachment headers #### Content-Type `Content-Type: image/jpeg` This header should be used when uploading an attachment to pass its MIME type. Supported types are: image/png, image/jpeg and image/gif. #### X-Bunq-Attachment-Description X-Bunq-Attachment-Description: Check out these cookies. This header should be used when uploading an Attachment's content to give it a description. ## Response headers ### All Responses #### X-Bunq-Client-Request-Id `X-Bunq-Client-Request-Id: a4f0de` The same ID that was provided in the request's X-Bunq-Client-Request-Id header. Is included in the response (and request) signature, so can be used to ensure this is the response for the sent request. #### X-Bunq-Client-Response-Id `X-Bunq-Client-Response-Id: 76cc7772-4b23-420a-9586-8721dcdde174` A unique ID for the response formatted as a UUID. Clients can use it to add extra protection against replay attacks. #### X-Bunq-Server-Signature `X-Bunq-Server-Signature: XBBwfDaOZJapvcBpAIBT1UOmczKqJXLSpX9ZWHsqXwrf1p+H+eON+TktYksAbmkSkI4gQghw1AUQSJh5i2c4+CTuKdZ4YuFT0suYG4sltiKnmtwODOFtu1IBGuE5XcfGEDDSFC+zqxypMi9gmTqjl1KI3WP2gnySRD6PBJCXfDxJnXwjRkk4kpG8Ng9nyxJiFG9vcHNrtRBj9ZXNdUAjxXZZFmtdhmJGDahGn2bIBWsCEudW3rBefycL1DlpJZw6yRLoDltxeBo7MjgROBpIeElh5qAz9vxUFLqIQC7EDONBGbSBjaXS0wWrq9s2MGuOi9kJxL2LQm/Olj2g==` The server's signature for this response. See the signing page for details on how to verify this signature. ### Warning header #### X-Bunq-Warning `X-Bunq-Warning: "You have a negative balance. Please check the app for more details."` Used to inform you on situations that might impact your bunq account and API access. # Errors Familiar HTTP response codes are used to indicate the success or failure of an API request. Generally speaking, codes in the 2xx range indicate success, while codes in the 4xx range indicate an error having to do with provided information (e.g. a required parameter was missing, insufficient funds, etc.). Finally, codes in the 5xx range indicate an error with bunq servers. If this is the case, please stop by the support chat and report it to us. ## Response codes

Code	Error	Description
200	OK	Successful HTTP request
399	NOT MODIFIED	Same as a 304, it implies you have a local cached copy of the data
400	BAD REQUEST	Most likely a parameter is missing or invalid
401	UNAUTHORISED	Token or signature provided is not valid
403	FORBIDDEN	You're not allowed to make this call
404	NOT FOUND	The object you're looking for cannot be found
405	METHOD NOT ALLOWED	The method you are using is not allowed for this endpoint
429	RATE LIMIT	Too many API calls have been made in a too short period
466	REQUEST SIGNATURE REQUIRED	Request signature is required for this operation.
490	USER ERROR	Most likely a parameter is missing or invalid
491	MAINTENANCE ERROR	bunq is in maintenance mode
500	INTERNAL SERVER ERROR	Something went wrong on bunq's end

All errors 4xx code errors will include a JSON body explaining what went wrong. ## Rate limits If you are receiving the error 429, please make sure you are sending requests at rates that are below our rate limits. Our rate limits per IP address per endpoint: - GET requests: 3 within any 3 consecutive seconds - POST requests: 5 within any 3 consecutive seconds - PUT requests: 2 within any 3 consecutive seconds - Callbacks: 2 callback URLs per notification category We have a lower rate limit for `/session-server`: 1 request within 30 consecutive seconds. # API conventions Make sure to follow these indications when using the bunq API or get started with our SDKs. ## Responses All JSON responses have one top level object. In this object will be a Response field of which the value is always an array, even for responses that only contain one object. Example response body ```json { "Response": [ { "DataObject": {} } ] } ``` ## Errors - Error responses also have one top level Error object. - The contents of the array will be a JSON object with an error_description and error_description_translated field. - The error_description is an English text indicating the error and the error_description_translated field can be shown to end users and is translated into the language from the X-Bunq-Language header, defaulting to en_US. - When using bunq SDKs, error responses will be always raised in form of an exception. Example response body ```json { "Error": [ { "error_description": "Error description", "error_description_translated": "User facing error description" } ] } ``` ## Object Type indications When the API returns different types of objects for the same field, they will be nested in another JSON object that includes a specific field for each one of them. Within bunq SDKs a BunqResponse object will be returned as the top level object. In this example there is a field content, which can have multiple types of objects as value such as — in this case — ChatMessageContentText. Be sure to follow this convention or use bunq SDKs instead. ```json { "content": { "ChatMessageContentText": { "text": "Hi! This is an automated security message. We saw you just logged in on an My Device Description. If you believe someone else logged in with your account, please get in touch with Support." } } } ``` ## Time formats Times and dates being sent to and from the API are in UTC. The format that should be used is `YYYY-MM-DD hh:mm:ss.ssssss`, where the letters have the meaning as specified in ISO 8601. For example: `2017-01-13 13:19:16.215235`. # Callbacks Callbacks are used to send information about events on your bunq account to a URL of your choice, so that you can receive real-time updates. ## Notification Filters To receive notifications for certain activities on a bunq account, you have to create notification filters. It is possible to send the notifications to a provided URL and/or the user’s phone as push notifications. Use the `notification-filter-push` resource to create and manage push notification filters. Provide the type of events you want to receive notifications about in the `category` field. ```json { "notification_filters":[ { "category":"SCHEDULE_RESULT" } ] } ``` Use the `notification-filter-url` resource to create and manage URL notification filters. The callback URL you provide in the `notification_target` field must use HTTPS. ```json { "notification_filters":[ { "category":"PAYMENT", "notification_target":"{YOUR_CALLBACK_URL}" } ] } ``` ### Callback categories

Category	Description
BILLING	notifications for all bunq invoices
CARD_TRANSACTION_SUCCESSFUL	notifications for successful card transactions
CARD_TRANSACTION_FAILED	notifications for failed card transaction
CHAT	notifications for received chat messages
DRAFT_PAYMENT	notifications for creation and updates of draft payments
IDEAL	notifications for iDEAL-deposits towards a bunq account
SOFORT	notifications for SOFORT-deposits towards a bunq account
MUTATION	notifications for any action that affects a monetary account’s balance
OAUTH	notifications for revoked OAuth connections
PAYMENT	notifications for payments created from, or received on a bunq account (doesn’t include payments that result out of paying a Request, iDEAL, Sofort or Invoice). Outgoing payments have a negative value while incoming payments have a positive value
REQUEST	notifications for incoming requests and updates on outgoing requests
SCHEDULE_RESULT	notifications for when a scheduled payment is executed
SCHEDULE_STATUS	notifications about the status of a scheduled payment, e.g. when the scheduled payment is updated or cancelled
SHARE	notifications for any updates or creation of Connects (ShareInviteBankInquiry)
TAB_RESULT	notifications for updates on Tab payments
BUNQME_TAB	notifications for updates on bunq.me Tab (open request) payments
SUPPORT	notifications for messages received from us through support chat

### Mutation category A Mutation is a change in the balance of a monetary account. So, for each payment-like object, such as a request, iDEAL-payment or a regular payment, a Mutation is created. Therefore, the `MUTATION` category can be used to keep track of a monetary account's balance. ### Receiving callbacks Callbacks for the sandbox environment will be made from different IP's at AWS. Callbacks for the production environment will be made from `185.40.108.0/22`. *The IP addresses might change*. We will notify you in a timely fashion if such a change would take place. ### Retry mechanism When the execution of a callback fails (e.g. if the callback server is down or the response contains an error) it is tried again for a maximum of 5 times, with an interval of one minute between each try. If your server is not reachable by the callback after the 6th total try, the callback is not sent anymore. ### Removing callbacks To remove callbacks for an object, send a PUT request to the *user-person*, *user-company*, *monetary-account* or *cash-register* resource with the `notification_filters` field of the JSON request body unset. ``` { "notification_filters": [] } ``` ## Certificate pinning We recommend you use certificate pinning as an extra security measure. With certificate pinning, we check the certificate of the server on which you want to receive callbacks against the pinned certificate that has been provided by you and cancel the callback if that check fails. ### How to set up certificate pinning Retrieve the SSL certificate of your server using the following command: 1. `openssl s_client -servername www.example.com -connect www.example.com:443 < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem` 2. `POST` the certificate to the certificate-pinned endpoint. Now every callback that is made will be checked against the pinned certificate that you provided. Note that if the SSL certificate on your server expires or is changed, our callbacks will fail. # Pagination In order to control the size of the response of a `LIST` request, items can be paginated. A `LIST` request is a request for every one of a certain resources, for instance all payments of a certain monetary account `GET /v1/user/1/monetary-account/1/payment`). You can decide on the maximum amount of items of a response by adding a `count` query parameter with the number of items you want per page to the URL. For instance: `GET /v1/user/1/monetary-account/1/payment?count=25` When no `count` is given, the default count is set to 10. The maximum `count` you can set is 200. With every listing, a `Pagination` object will be added to the response, containing the URLs to be used to get the next or previous set of items. The URLs in the Pagination object can be used to navigate through the listed resources. The Pagination object looks like this given a count of 25: ```json { "Pagination": { "future_url": null, "newer_url": "/v1/user/1/monetary-account/1/payment?count=25&newer_id=249", "older_url": "/v1/user/1/monetary-account/1/payment?count=25&older_id=224" } } ``` The `newer_url` value can be used to get the next page. The `newer_id` is always the ID of the last item in the current page. If `newer_url` is `null`, there are no more recent items before the current page. The `older_url` value can be used to get the previous page. The `older_id` is always the ID of the first item in the current page. If `older_url` is `null`, there are no older items after the current page. The `future_url` can be used to refresh and check for newer items that didn't exist when the listing was requested. The `newer_id` will always be the ID of the last item in the current page. `future_url` will be `null` if `newer_id` is not also the ID of the latest item. # Sandbox *The sandbox base URL is https://public-api.sandbox.bunq.com/v1/* We do not use real money and do not allow external transactions in the sandbox environment. ## Sandbox user accounts You need to create a sandbox user to test the bunq API. The easiest way to do it is by using [our developer portal](https://developer.bunq.com/): 1. Log in using your bunq account or [create a free developer account](https://developer.bunq.com/portal/signup) with sandbox-only access. 1. Go to Sandbox Users. 1. Generate up to 5 users. 1. Use the sandbox API key to create an API context and/or use the user credentials to log in to the [sandbox bunq app](https://doc.bunq.com/#/android-emulator). ### Alternative ways to generate sandbox API keys There are 3 other ways you can generate a bunq sandbox API key: * connect to [Tinker](https://lexy.gitbook.io/bunq/quickstart/tinker) *(it will also return login credentials for the sandbox app)*; * create it in the [sandbox app](https://doc.bunq.com/#/android-emulator) *(you need to be logged in as a sandbox user)*; * call the sandbox user endpoints directly, using [our Postman collection](https://github.com/bunq/postman), or by running a cURL command (change `sandbox-user-person` to `sandbox-user-company` to generate a business user): ``` curl https://public-api.sandbox.bunq.com/v1/sandbox-user-person -X POST --header "Content-Type: application/json" --header "Cache-Control: none" --header "User-Agent: curl-request" --header "X-Bunq-Client-Request-Id: $(date)randomId" --header "X-Bunq-Language: nl_NL" --header "X-Bunq-Region: nl_NL" --header "X-Bunq-Geolocation: 0 0 0 0 000" ``` ⚠️ **NOTE:** An API key can only be assigned to an IP within 1 hour after its creation. After the 1 hour, it will become invalid if not assigned. API keys that are created via the sandbox app are wiped with each sandbox reset. Once you have a sandbox API key, create more sandbox users to use as test customer accounts, and start playing with the API. The sandbox base URL is https://public-api.sandbox.bunq.com/v1/. ## Sandbox money Without money, it's not always sunny in the sandbox world. Fortunately, getting money on the bunq sandbox is easy. All you need to do is ask Sugar Daddy for it. Send a `POST v1/request-inquiry` request passing sugardaddy@bunq.com in the counterparty_alias field. Specify the type for the alias and set the `allow_bunqme` field. Request up to €500 at a time. ``` { "amount_inquired": { "value": "100", "currency": "EUR" }, "counterparty_alias": { "type": "EMAIL", "value": "sugardaddy@bunq.com", "name": "Sugar Daddy" }, "description": "You're the best!", "allow_bunqme": false } ``` # Android Emulator In case you do not own an Android device on which you can run our Sandbox app for end-to-end testing, you can set up an emulator to run the bunq Sandbox app for Android. ## Things you will need - The [bunq Sandbox App APK](https://appstore.bunq.com/api/android/builds/bunq-android-sandbox-master.apk) that's optimised for emulating; - [Android Studio](https://developer.android.com/studio/index.html). ## Starting the Android Virtual Device (AVD) Manager 1. Open Android Studio. 2. From the top menu, select “Tools” > "Android" > "AVD Manager". ## Setting up a new virtual device 1. Start the wizard by clicking on "+ Create Virtual Device". 2. Select a device (recommendation: "Pixel 5.0" or "Nexus 6") and press "Next". 3. Select an x86 system image (recommendation: Nougat, API Level 25, Android 7.1.1 with Google APIs) and press "Next". The image needs to have Google Play Services 10.0.1 or higher. 4. In the bottom left corner, select "Show Advanced Settings". 5. Scroll to "Memory and Storage". 6. Change "Internal Storage" to "2048 MB". 7. Change "SD card" to "200 MB". 8. Press "Finish". ## Starting the virtual device 1. On the right side under "Actions", select the green "Play" button. 2. Wait for the device to boot, this may take a few minutes. ## Installing the bunq Sandbox App APK 1. Open the command line. 2. Navigate to your Android SDK platform tools directory (e.g. `cd ~/Library/Android/sdk/platform-tools` on macOS). 3. Make sure that the virtual device is started and has fully booted. 4. Run `./adb install ~/Downloads/bunq-android-sandboxEmulator-public-api.apk`, this may take a few minutes, and should finish with "Success". ## Creating an account or logging in 1. Create a sandbox account in the [developer portal](https://developer.bunq.com/). 1. Log in to the sandbox app using the sandbox user credentials. ℹ️ *You will be asked to verify your phone number when you open the app for the first time. Sandbox does not send actual SMS messages. Enter any valid phone number and use the default verification code `992266`*. If you couldn't generate a sandbox account in the developer portal, use Tinker: 1. Install [Tinker](https://beta.doc.bunq.com/quickstart/tinker). 1. Run `tinker/user-overview` to create a sandbox account. The output of the command will include the login credentials for the sandbox account. ⚠️ **NOTE:** It is **not** possible to create accounts using the regular signup in the app, bunq is not reviewing Sandbox applications. # Moving to Production Have you tested your bunq integration to the fullest and are you now ready to introduce it to the world? Then the time has come to move it to a production environment! To get started you'll need some fresh API keys for the production environment, which you can create via your bunq app. You can create these under "Profile" by tapping the "Security" menu. We do, however, highly recommend using a standard API Key instead of a Wildcard API Key. The former is significantly safer and it protects you from intrusions and possible attacks. There's only a few things to do before your beautiful bunq creation can be moved to production. You're going to have to change your API Key and redo the sequence of calls to open a session. The bunq Public API production environment is hosted at `https://api.bunq.com`. Do you have any questions or remarks about the process, or do you simply want to show off with your awesome creations? Don't hesitate to drop us a line on [together.bunq.com](https://together.bunq.com). Please be aware that if you will gain access to account information of other bunq users or initiate a payment for them, you maybrequire a PSD2 permit. # Quickstart: Opening a Session ## Goal So, you want to start using the bunq API, awesome! To do this, you have to open a session in which you will be making those calls. ## Getting an API key To connect to the API, you have to make sure you have received an API key. **For production:** 1. create an app in the [developer portal](http://developer.bunq.com/), or 1. generate it in the bunq app *(Profile → Security & Settings → Developers → API keys)*. **For sandbox** You can use one of the following ways: - create a sandbox user in the [developer portal](http://developer.bunq.com/); - generate an API key in the [sandbox app](#android-emulator) *(Profile → Security & Settings → Developers → API keys)*; - get an API key from [Tinker](https://beta.doc.bunq.com/quickstart/tinker); - run a cURL request: `curl https://public-api.sandbox.bunq.com/v1/sandbox-user-person -X POST --header "Content-Type: application/json" --header "Cache-Control: none" --header "User-Agent: curl-request" --header "X-Bunq-Client-Request-Id: $(date)randomId" --header "X-Bunq-Language: nl_NL" --header "X-Bunq-Region: nl_NL" --header "X-Bunq-Geolocation: 0 0 0 0 000"`. Use `sandbox-user-company` to generate a business user. Note that production API key is only usable on production and sandbox key is only usable on sandbox. Sandbox key has a `sandbox_` prefix while production key does not have any noticeable prefixes. ## Call sequence The calls you need to perform to set up a session from scratch are the following: ### 1. POST installation Each call needs to be signed with your own private key. An Installation is used to tell the server about the public key of your key pair. The server uses this key to verify your subsequent calls. Start by generating a 2048-bit RSA key pair. You can find examples by looking at the source code of the sdk's located at github. #### Headers On the headers page you can find out about the mandatory headers. Take care that if you are in the sandbox environment, you set an `Authorization` header. Specific to the `POST /installation` call, you shouldn't use the `X-Bunq-Client-Authentication` or the `X-Bunq-Client-Signature` headers. #### Body Post your public key to the Installation endpoint (use `\n` for newlines in your public key). #### Response Save the Installation token and the bunq API's public key from the response. This token is used in the `Authentication` header to register a `DeviceServer` and to start a `SessionServer`. The bunq API's public key should be used to verify future responses received from the bunq API. ### 2. POST device-server Further calls made to the server need to come from a registered device. `POST /device-server` registers your current device and the IP address(es) it uses to connect to the bunq API. #### Headers Use the token you received from `POST /installation` in the `X-Bunq-Client-Authentication` header. Make sure you sign your call, passing the call signature in `X-Bunq-Client-Signature` header. #### Body For the secret, use the API key you received. If you want to create another API key, you can do so in the bunq sandbox app (or production app for the production environment). Login, go to Profile > Security and tap 'API keys'. The freshly created API key can be assigned to one or multiple IP addresses using `POST device-server` within 4 hours before becoming invalid. As soon as you start using your API key, it will remain valid until the next sandbox reset.

 For the secret, use the API key you received. ### 3. POST session-server To make any calls besides `installation` and `device-server`, you need to open a session. #### Headers Use the token you received from `POST /installation` in the `X-Bunq-Client-Authentication` header. Make sure you sign your call, passing the call signature in `X-Bunq-Client-Signature` header. #### Body For the secret, use the API key you received. #### Response The token received in the response to `POST /session-server` should be used to authenticate your calls in this session. Pass this session's token in the `X-Bunq-Client-Authentication` header on every call you make in this session. # Quickstart: Payment Request ## Goal You want to offer bunq payments on a website or in an application. ## Scenario In this use case the consumer and the merchant both have a bunq account. The consumer wants to pay with bunq and enters their alias in the bunq payment field at checkout. The merchant sends the request for payment to the consumer when the consumer presses enter. The consumer agrees to the request in the bunq mobile app and the merchant has immediate confirmation of the payment. Please be aware that if you will gain access to account information of other bunq users or initiate a payment for them, you require a PSD2 permit. ## Before you start Make sure that you have opened a session and that for any call you make after that, you pass the session’s token in the X-Bunq-Client-Authentication header. ## Call Sequence The consumer is at checkout and selects the bunq payment method. This would be a logical time to open a session on the bunq server. ### 1. LIST monetary-account When a request for payment is accepted, the money will be deposited on the bank account the request for payment is connected to. Let’s start by finding all your available bank accounts. Pick one of them to make the request for payment with and save its `id`. ### 2. POST monetary-account attachment (optional) Optionally, you can attach an image to the request for payment. #### Headers Make sure you set the `Content-Type` header to match the MIME type of the image. It’s also required you pass a description of the image via the `X-Bunq-Attachment-Description` header. #### Body The payload of this request is the binary representation of the image file. Do not use any JSON formatting. #### Response Save the `id` of the posted attachment. You’ll need it to attach it to the request for payment. ### 3. POST request-inquiry Next, create a request inquiry. A request inquiry is the request for payment that your customer can respond to by accepting or rejecting it. #### Body Pass the customer’s email address, phone number or IBAN in the `counterparty_alias`. Make sure you set the correct `type` for the alias, depending on what you pass. When providing an IBAN, a name of the `counterparty_alias` is required. You can provide the `id` of the created attachment. #### Response You will receive the `id` of the created request inquiry in the response. Save this `id`. You will need it to check if the customer has responded to the request yet. ### 4. GET request-inquiry After you’ve sent the request for payment, its status can be checked. #### Response When the `status` is `ACCEPTED`, the customer has accepted and paid the request, and you will have received the money on the connected monetary account. If the `status` is `REJECTED`, the customer did not accept the request. # Quickstart: Create a Tab payment ## Goal You will create a tab that can be paid once by a single user, a so called TagUsageSingle, and explore three different ways to make the Tab visible to your customers: - QR code from the CashRegister - QR code from the Tab. ## Before you start Make sure that you have opened a session and that for any call you make after that, you pass the session’s token in the `X-Bunq-Client-Authentication` header. ## Call sequence ### 1. POST attachment-public Start by creating an attachment that will be used for the avatar for the cash register. #### Header Make sure you set the `Content-Type` header to match the MIME type of the image. It is also required you pass a description of the image via the `X-Bunq-Attachment-Description` header. #### Body The payload of this request is the binary representation of the image file. Do not use any JSON formatting. #### Response Save the `uuid` of the posted attachment. You'll need it to create the avatar in the next step. ### 2. POST avatar Make an avatar using the public attachment you've just created. #### Body The payload of this request is the `uuid` of the attachment public. #### Response In response, you’ll receive the UUID of the avatar created using the attachment. Save this UUID. You’ll use it as the avatar for the cash register you're about to create. ### 3. LIST monetary-account Get a listing of all available monetary accounts. Choose one, and save the id of the monetary account you want your cash register to be connected to. Each paid tab for the cash register will transfer the money to this account. ### 4a. POST cash-register Create a cash register. Use the `id` of the monetary account you want to connect the cash register to in the URL of the request. #### Body In the body provide the `uuid` of the avatar you created for this cash register. Also make sure to provide a unique name for your cash register. Set the status to `PENDING_APPROVAL`. #### Response The response contains the `id` of the cash register you created. Save this `id`. You will need it to create subsequent tabs and tab items. ### 4b. Wait for approval On the production environment, a bunq admin will review and approve your cash register. In the sandbox environment, your cash register will be automatically approved. ### 5. POST tab-usage-single Create a new tab that is connected to your cash register. Use the id of the cash register you want to connect this tab to in the URL of your request. #### Body Give the tab a name in `merchant_reference`. Create the tab with status `OPEN`, and give the tab a starting amount. You can update this amount later. #### Response The response contains the uuid of the tab you created. ### 6. POST tab-item (optional) You can add items to a tab. For instance, if a customer will be paying for multiple products via this tab, you can decide to add an item for each of these. Adding items to a tab is optional, and adding them will not change the total amount of the tab itself. However, if you've added any tab items the sum of the amounts of these items must be equal to the `total_amount` of the tab when you change its status to `WAITING_FOR_PAYMENT`. ### 7. PUT tab-usage-single Update the status of the tab to `WAITING_FOR_PAYMENT` if you want the costumer to pay the tab, and you're done adding any tab items. You can use this request to make the tab visible for your costumers. #### Visibility To decide how you are going to make your tab visible, pass a visibility object in the payload. Setting `cash_register_qr_code` to true will connect this tab to the QR code from the cash register. If this cash register does not have a QR code yet, one will be created. Only one Tab can be connected to the cash register’s QR code at any given time. Setting `tab_qr_code` to true will create a QR code specifically for this tab. This QR code can not be linked to anything else. # Quickstart: Create a TransferWise payment ## Goal You want to send a payment in currency other than euro outside the SEPA zone. ## Before you start Make sure that you have opened a session and that for any call you make after that, you pass the session’s token in the `X-Bunq-Client-Authentication` header. ℹ️ *bunq relies on TransferWise for international, so you need to create a TransferWise account linked to a bunq account to be able to create international transfers. You can do it either from the bunq app or using our API as described below.* ## Get the up-to-date exchange rate (optional) You might want to check the latest currency exchange rate before making a transfer. Here’s how you can do it using the bunq API: 1. Check the list of supported currencies via `GET /user/{userID}/transferwise-currency`. Copy the needed currency code. 2. Create a temporary quote for the currency of your choice via `POST /user/{userID}/transferwise-quote-temporary`. ℹ️ *A quote is the exchange rate at the exact timestamp. Temporary quotes carry solely informative value and cannot be used for creating a transfer.* 3. Read the temporary quote via `GET /user/{userID}/transferwise-quote-temporary/{transferwise-quote-temporaryID}`. ## Create a TransferWise account You need a TransferWise account linked to your bunq account to make TransferWise payments via the bunq API. Create one via `POST /user/{userID}/transferwise-user`, and save its ID. ℹ️ *You cannot use an existing TransferWise account.* ## Create a quote 1. Create a quote via POST /user/{userID}/transferwise-quote and save its ID. ℹ️ *Use amount_target to indicate the sum the recipient must get. Amount_source, on the other hand, will indicate the sum you want to send, but it will not necessarily be the final sum the recipient gets.* ℹ️ *Quotes are valid for 30 minutes so if you do not manage to create a transfer within this time, you will need to create another quote.* 2. Get the exchange rate by reading the quote via GET /user/{userID}/transferwise-quote/(transferwise-quoteID). ## Create a recipient If you have sent money via the TransferWise account linked to your bunq account, you can reuse the recipients. You can list their IDs via `GET /user/{userID}/transferwise-quote/{transferwise-quoteID}/transferwise-recipient`. To create a new, previously unused recipient, follow these steps: 1. Retrieve the fields required for creating the recipient as the requirements vary for the type of recipient in each country. Iterate sending the following request pair till there are no more required fields: - `GET /user/{userID}/transferwise-quote/{transferwise-quoteID}/transferwise-recipient-requirement` - `POST /user/{userID}/transferwise-quote/{transferwise-quoteID}/transferwise-recipient-requirement` 2. Create a recipient account using the final request body from the previous step with `POST /user/{userID}/transferwise-quote/{transferwise-quoteID}/transferwise-recipient-requirement` ## Create a transfer Finally, having both the quote ID and the recipient ID, you can create a transfer. 🎉 1. Check if there are any additional transfer requirements via `POST /user/{userID}/transferwise-quote/{transferwise-quoteID}/transferwise-transfer-requirement`. 2. Create a transfer via `POST /user/{userID}/transferwise-quote/{transferwise-quoteID}/transferwise-transfer`. You need to specify the ID of the monetary account from which you want the payment to be made. # Quickstart: Downloading attachments ## Goal Export receipts and invoices attached to payments to your application. ## The scenario you want to achieve 0. The bunq user has accepted the authorization request and your application can read the bunq user’s account information. 1. Your application imports all the transactions and attachments. 2. The bunq user sees the transactions matched with the receipts and invoices in your application. ## Before you start * Make sure that you have opened a session * Make sure you pass the session Token in the X-Bunq-Client-Authentication header in all the following requests of the session. ## Call sequence 1. List the payments of the user via GET /user/{userID}/monetary-account/{monetary-accountID}/payment. 2. Check if the payments have attachments via GET /user/{userID}/monetary-account/{monetary-accountID}/payment/{paymentID}/note-attachment. Save the attachment IDs. 3. Export the raw content of the attachments via GET /user/{userID}/attachment/{attachmentID}/content. ***HINT:** You can use [callbacks](https://doc.bunq.com/#/callbacks) to make sure you don’t miss anything happening on the bunq account.*

# Chaingateway.io REST API to build the bridge between Ethereum and the real world Please check out our [website](https://chaingateway.io?utm_source=postman) for detailed information about this API. To use our API, you need an API Key (Described as Authorization header in the examples below). To get one, please create an account on our [website](https://chaingateway.io/register?utm_source=postman). For our internal documentation, please check out our [Docs Site](https://chaingateway.io/docs?utm_source=postman). If you need help with integrating our API in your application, you can reach us via [email](mailto:support@chaingateway.io) or join our official [Telegram](https://t.me/chaingateway) group.

Processe arquivos de retorno CNAB

A flexible API for pulling accounting data, normalized and aggregated from 20 accounting integrations. Standardize how you connect to your customers’ accounting software. View, create, update, and delete data in the same way for all the leading accounting platforms. [Read more...](https://docs.codat.io/accounting-api/overview) [See our OpenAPI spec](https://github.com/codatio/oas)

Codat's Assess API enable you to make smarter credit decisions on your small business customers. Assess enriches your customer's accounting, commerce and banking data to surface actionable insights you didn't have before. [Read more...](https://www.codat.io/assess/) [See our OpenAPI spec](https://github.com/codatio/oas)

Bank Feeds API enables your SMB users to set up bank feeds from accounts in your application to supported accounting platforms. A bank feed is a connection between a source bank account—in your application—and a target bank account in a supported accounting package. [Read more...](https://docs.codat.io/bank-feeds-api/overview) [See our OpenAPI spec](https://github.com/codatio/oas)

Codat's Banking API allows you to access standardised data from over bank accounts via third party providers. Standardize how you connect to your customers’ bank accounts. Retrieve bank account and bank transaction data in the same way via our partnerships with Plaid and TrueLayer. [Read more...](https://docs.codat.io/banking-api/overview) [See our OpenAPI spec](https://github.com/codatio/oas)

The API for Sync for Expenses. Sync for Expenses is an API and a set of supporting tools. It has been built to enable corporate card and expense management platforms to provide high-quality integrations with multiple accounting platforms through a standardized API. [Read more...](https://docs.codat.io/sync-for-expenses/overview) [See our OpenAPI spec](https://github.com/codatio/oas)

Learn more about home mortgage data, download the data yourself, or build new tools using our API.

[](https://app.getpostman.com/run-collection/80638214aa04722c9203) or View Postman docs # Quickstart Visit [github](https://github.com/EmitKnowledge/Envoice) to view the quickstart tutorial.