Mock sample for your project: Event Notification API Specification - TPP Endpoints

Swagger for Payment Initiation API Specification

Swagger for Confirmation of Funds API Specification

Swagger for Account and Transaction API Specification

Latest Swagger specification for OpenData

Introduction
Taxrates.io is a global tax rate service that automates the management of monitoring tax rates changes in 181 countries. We monitor over 14,000 US sales tax, VAT, GST rates for you and make updates via our API so you always have the most update tax rates.
You can use Taxrates.io as a virtual sandbox where we provide you with 30 days free trial.
Countries
We currently support the following countries around the world. If you would like to request the addition of a new country, please email us at [email protected]
Afghanistan Gambia Nicaragua
Albania Georgia Niger
Andorra Germany Nigeria
Angola Ghana North Korea
Antigua and Barbuda Greece Norway
Argentina Grenada Pakistan
Armenia Guam Palestine
Aruba Guatemala Panama
Australia Guinea Papua New Guinea
Austria Guyana Paraguay
Azerbaijan Haiti Peru
Bahamas Honduras Philippines
Bangladesh Hungary Poland
Barbados Iceland Portugal
Belarus India Puerto Rico
Belgium Indonesia Republic of the Congo
Belize Iran Romania
Benin Ireland Russian Federation
Bhutan Isle of Man Rwanda
Bolivia Israel Samoa
Bonaire Italy Senegal
Bosnia and Herzegovina Japan Serbia
Botswana Jersey Seychelles
Brazil Jordan Sierra Leone
Bulgaria Jordan Singapore
Burkina Faso Kazakhstan Slovakia
Burundi Kenya Slovenia
Cambodia Kiribati Solomon Islands
Cameroon Kosovo Somalia
Cape Verde Kyrgyzstan South Africa
Central African Republic Laos South Korea
Chad Latvia South Sudan
Chile Lebanon Spain
China Lesotho Sri Lanka
Columbia Liberia St Lucia
Comoros Liechtenstein Sudan
Cook Islands Lithuania Suriname
Costa Rica Luxembourg Swaziland
Cote d'Ivoire Macedonia Sweden
Croatia Madagascar Switzerland
Cuba Malawi Tahiti
Curacao Malaysia Taiwan
Cyprus Maldives Tajikistan
Czech Republic Mali Tanzania
Democratic Republic of the Congo Malta Thailand
Denmark Mauritania Togo
Djbouti Mauritius Tonga
Dominica Mexico Trinidad and Tobago
Dominican Republic Micronesia Tunisia
Ecuador Moldova Turkmenistan
Egypt Monaco Tuvalu
El Salvador Mongolia Uganda
Equatorial Guinea Montenegro Ukraine
Eritrea Morocco United Kingdom
Estonia Mozambique United States
Ethiopia Myanmar Uruguay
Fiji Namibia Vanuatu
Finland Nepal Venezuela
France Netherlands Vietnam
Gabon New Zealand Yemen
Products codes
The Taxrates.io API’s provides product-level tax rates for a subset of product codes. These codes are to be used for products that are either exempt from tax in some jurisdictions or are taxed at reduced rates.
We will be expanding support for additional, less common categories over time. If you would like to request the addition of a new product category, please email us at [email protected]
Please select a product code/s when making a request to the Taxrates.io API
Product code Product Description
C010 Services which are not subject to a service-specific tax
C011 Software - Downloaded
C012 Books - Downloaded
C011 Music - Downloaded
C011 Movies/Digital Video - Downloaded
C011 Other Electronic Goods - Downloaded
C011 Streaming Music/Audio Services new
C011 Streaming Video Services new
C018 Software as a Services, Generally (Remote Access to Hosted Software)
C018 Remote Access to Hosted Software - Personal Use
C018 Remote Access to Hosted Software - Business Use
C021 Remote Access to Hosted Business Custom Applications
C021 Personal Cloud Storage/Backup
C021 Business Cloud Storage/Backup
C021 Business Data Warehouses
C022 Infrastructure as Service, Generally
C022 Ecommerce Site/Webserver Hosting
C022 Provision of Virtual Computing Capacity
C022 Software - package or canned program
C022 Software - modifications to canned program
C022 Software - custom programs - material
C022 Software - custom programs - professional serv.
C022 Information services
C022 Data processing services
C022 Mainframe computer access and processing serv.
C022 Online Data processing services
Filtering
When calling the API endpoints you can use 'filter' parameters to get tax rate for the selected type. You can get the following tax types (Each tax rate will always have one of following types)
US Sales tax Rates
CombinedRate
StateRate
CountyRate
CityRate
SpecialRate
We recommend using Postman when discovering our API. Happy using!
Rate Limiting
We limit API requests.
If you’re exceeding this rate and encountering 429 errors, review the following:
Only make requests in states / regions where you have enabled.
Cache responses if the order details haven’t changed since the last calculation at checkout.
Errors
The Taxrates.io API uses the following error codes:
Code Error Message
400 Bad Request – Your request format is bad.
401 Unauthorized – Your API key is wrong.
404 Not Found – The specified resource could not be found.
405 Method Not Allowed – You tried to access a resource with an invalid method.
429 Too Many Requests – You’re requesting too many resources! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Try again later.
Verify your API token is correct and make sure you’re correctly setting the Authorization header.
If you’re still not sure what’s wrong, contact us and we’ll investigate.
Changelog
Stay on top of new developer-facing features, accuracy improvements, and bug fixes for our API. Have a request? Encounter an issue? We’d love to hear your feedback.
Contact Support:
Name: [email protected]

Professional Cloud Trading Platform for Digital Assets

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. After that, you can test your API key on this page.

Swagger for Payment Initiation API Specification

Portfolio Optimizer is a Web API to optimize the composition of investment portfolios (collection of financial assets such as stocks, bonds, ETFs, crypto-currencies) using modern portfolio theory-like algorithms (mean-variance, etc.).
API General Information
Portfolio Optimizer is based on REST for easy integration, uses JSON for the exchange of data and uses the two most common HTTP verbs (GET, POST) to represent the actions.
Portfolio Optimizer is also as secured as a Web API could be:
256-bit HTTPS Encryption
No usage of cookies
No usage of personal data
API Headers
The following HTTP header(s) are required when calling Portfolio Optimizer endpoints:
Content-type: application/json
This header specifies that the data provided in input to the endpoint is in JSON format
The following HTTP header(s) are optional when calling Portfolio Optimizer endpoints:
X-API-Key:
This header enables authenticated users to provide their private API key in order to benefit from higher API limits
API Key
Portfolio Optimizer is free to use, but not free to run.
In order to obtain an API key and benefit from higher API limits, a small participation to Portfolio Optimizer running costs is required.
This participation takes the form of coffee(s), with one coffee = one month of usage.
Notes:
> * Please make sure not to expose your API key publicly!
API Limits
Portfolio Optimizer comes with fairly reasonable API limits.
For anonymous users:
The API requests are restricted to a subset of all the available endpoints and/or endpoints features
The API requests are limited to 1 request per second for all the anonymous users combined, with concurrent requests rejected
The API requests are limited to 1 second of execution time
The API requests are limited to 20 assets, 100 portfolios, 500 series data points and 5 factors
For authenticated users with an API key:
The API requests have access to all the available endpoints and endpoints features
The API requests are limited to 10000 requests per 24 hour per API key, with concurrent requests queued
The API requests are limited to 2.5 seconds of execution time
The API requests are limited to 100 assets, 500 portfolios, 2500 series data points and 25 factors
> Notes:
> * It is possible to further relax the API limits, or to disable the API limits alltogether; please contact the support for more details.
> * Information on the API rate limits are provided in response messages HTTP headers x-ratelimit-*:
> * x-ratelimit-limit-second, the limit on the number of API requests per second
> * x-ratelimit-remaining-second, the number of remaining API requests in the current second
> * x-ratelimit-limit-minute, the limit on the number of API requests per minute
> * ...
API Regions
Portfolio Optimizer servers are located in Western Europe.
> Notes:
> * It is possible to deploy Portfolio Optimizer in other geographical regions, for example to improve the API latency; please contact the support for more details.
API Response Codes
Standard HTTP response codes are used by Portfolio Optimizer to provide details on the status of API requests.
| HTTP Code | Description | Notes |
| --------- | ----------- | ----- |
| 200 | Request successfully processed | - |
| 400 | Request failed to be processed because of incorrect content | The response message body contains information on the incorrect content |
| 401 | Request failed to be processed because of invalid API key | - |
| 404 | Request failed to be processed because of non existing endpoint | The requested endpoint might exist, but needs to be accessed with another HTTP method (e.g., POST instead of GET) |
| 429 | Request failed to be processed because of API limits violated | The response message HTTP headers x-ratelimit-* contain information on the API limits |
| 500 | Request failed to be processed because of an internal error | Something went wrong on Portfolio Optimizer side, do not hesitate to report the issue |
| 502 | Request failed to be processed because of a temporary connectivity error | Something went wrong on Portfolio Optimizer side, please check the API status and do not hesitate to report the issue |
API Status
Portfolio Optimizer is monitored 24/7 by UptimeRobot.
Support
For any issue or question about Portfolio Optimizer, please do not hesitate to contact the support.

Introduction
Welcome to the reference for the Zuora Billing REST API!
To learn about the common use cases of Zuora Billing REST APIs, check out the API Guides.
In addition to Zuora API Reference; Billing, we also provide API references for other Zuora products:
API Reference: Collect
API Reference: Revenue
The Zuora REST API provides a broad set of operations and resources that:
Enable Web Storefront integration from your website.
Support self-service subscriber sign-ups and account management.
Process revenue schedules through custom revenue rule models.
Enable manipulation of most objects in the Zuora Billing Object Model.
Want to share your opinion on how our API works for you? Tell us how you feel about using our API and what we can do to make it better.
Access to the API
If you have a Zuora tenant, you can access the Zuora REST API via one of the following endpoints:
| Tenant | Base URL for REST Endpoints |
|-------------------------|-------------------------|
|US Production | https://rest.zuora.com |
|US API Sandbox | https://rest.apisandbox.zuora.com|
|US Performance Test | https://rest.pt1.zuora.com |
|US Production Copy | Submit a request at Zuora Global Support to enable the Zuora REST API in your tenant and obtain the base URL for REST endpoints. See REST endpoint base URL of Production Copy (Service) Environment for existing and new customers for more information. |
|US Cloud Production | https://rest.na.zuora.com |
|US Cloud API Sandbox | https://rest.sandbox.na.zuora.com |
|US Central Sandbox | https://rest.test.zuora.com |
|EU Production | https://rest.eu.zuora.com |
|EU API Sandbox | https://rest.sandbox.eu.zuora.com |
|EU Central Sandbox | https://rest.test.eu.zuora.com |
The Production endpoint provides access to your live user data. Sandbox tenants are a good place to test code without affecting real-world data. If you would like Zuora to provision a Sandbox tenant for you, contact your Zuora representative for assistance.
If you do not have a Zuora tenant, go to https://www.zuora.com/resource/zuora-test-drive and sign up for a Production Test Drive tenant. The tenant comes with seed data, including a sample product catalog.
API Changelog
You can find the Changelog of the API Reference: Billing in the Zuora Community.
Authentication
OAuth v2.0
Zuora recommends that you use OAuth v2.0 to authenticate to the Zuora REST API. Currently, OAuth is not available in every environment. See Zuora Testing Environments for more information.
Zuora recommends you to create a dedicated API user with API write access on a tenant when authenticating via OAuth, and then create an OAuth client for this user. See Create an API User for how to do this. By creating a dedicated API user, you can control permissions of the API user without affecting other non-API users.
If a user is deactivated, all of the user's OAuth clients will be automatically deactivated.
Authenticating via OAuth requires the following steps:
Create a Client
Generate a Token
Make Authenticated Requests
Create a Client
You must first create an OAuth client in the Zuora UI. To do this, you must be an administrator of your Zuora tenant. This is a one-time operation. You will be provided with a Client ID and a Client Secret. Please note this information down, as it will be required for the next step.
Note: The OAuth client will be owned by a Zuora user account. If you want to perform PUT, POST, or DELETE operations using the OAuth client, the owner of the OAuth client must have a Platform role that includes the "API Write Access" permission.
Generate a Token
After creating a client, you must make a call to obtain a bearer token using the Generate an OAuth token operation. This operation requires the following parameters:
client_id - the Client ID displayed when you created the OAuth client in the previous step
client_secret - the Client Secret displayed when you created the OAuth client in the previous step
granttype - must be set to clientcredentials
Note: The Client ID and Client Secret mentioned above were displayed when you created the OAuth Client in the prior step. The Generate an OAuth token response specifies how long the bearer token is valid for. You should reuse the bearer token until it is expired. When the token is expired, call Generate an OAuth token again to generate a new one.
Make Authenticated Requests
To authenticate subsequent API requests, you must provide a valid bearer token in an HTTP header:
Authorization: Bearer {bearer_token}
If you have Zuora Multi-entity enabled, you need to set an additional header to specify the ID of the entity that you want to access. You can use the scope field in the Generate an OAuth token response to determine whether you need to specify an entity ID.
If the scope field contains more than one entity ID, you must specify the ID of the entity that you want to access. For example, if the scope field contains entity.1a2b7a37-3e7d-4cb3-b0e2-883de9e766cc and entity.c92ed977-510c-4c48-9b51-8d5e848671e9, specify one of the following headers:
Zuora-Entity-Ids: 1a2b7a37-3e7d-4cb3-b0e2-883de9e766cc
Zuora-Entity-Ids: c92ed977-510c-4c48-9b51-8d5e848671e9
Note: For a limited period of time, Zuora will accept the entityId header as an alternative to the Zuora-Entity-Ids header. If you choose to set the entityId header, you must remove all "-" characters from the entity ID in the scope field.
If the scope field contains a single entity ID, you do not need to specify an entity ID.
Other Supported Authentication Schemes
Zuora continues to support the following additional legacy means of authentication:
Use username and password. Include authentication with each request in the header:
apiAccessKeyId
apiSecretAccessKey
Zuora recommends that you create an API user specifically for making API calls. See Create an API User for more information.
Use an authorization cookie. The cookie authorizes the user to make calls to the REST API for the duration specified in Administration > Security Policies > Session timeout. The cookie expiration time is reset with this duration after every call to the REST API. To obtain a cookie, call the Connections resource with the following API user information:
ID
Password
For CORS-enabled APIs only: Include a 'single-use' token in the request header, which re-authenticates the user with each request. See below for more details.
Entity Id and Entity Name
The entityId and entityName parameters are only used for Zuora Multi-entity. These are the legacy parameters that Zuora will only continue to support for a period of time. Zuora recommends you to use the Zuora-Entity-Ids parameter instead.
The entityId and entityName parameters specify the Id and the name of the entity that you want to access, respectively. Note that you must have permission to access the entity.
You can specify either the entityId or entityName parameter in the authentication to access and view an entity.
If both entityId and entityName are specified in the authentication, an error occurs.
If neither entityId nor entityName is specified in the authentication, you will log in to the entity in which your user account is created.
To get the entity Id and entity name, you can use the GET Entities REST call. For more information, see API User Authentication.
Token Authentication for CORS-Enabled APIs
The CORS mechanism enables REST API calls to Zuora to be made directly from your customer's browser, with all credit card and security information transmitted directly to Zuora. This minimizes your PCI compliance burden, allows you to implement advanced validation on your payment forms, and makes your payment forms look just like any other part of your website.
For security reasons, instead of using cookies, an API request via CORS uses tokens for authentication.
The token method of authentication is only designed for use with requests that must originate from your customer's browser; it should not be considered a replacement to the existing cookie authentication mechanism.
See Zuora CORS REST for details on how CORS works and how you can begin to implement customer calls to the Zuora REST APIs. See HMAC Signatures for details on the HMAC method that returns the authentication token.
Requests and Responses
Request IDs
As a general rule, when asked to supply a "key" for an account or subscription (accountKey, account-key, subscriptionKey, subscription-key), you can provide either the actual ID or the number of the entity.
HTTP Request Body
Most of the parameters and data accompanying your requests will be contained in the body of the HTTP request.
The Zuora REST API accepts JSON in the HTTP request body. No other data format (e.g., XML) is supported.
Data Type
(Actions and CRUD operations only) We recommend that you do not specify the decimal values with quotation marks, commas, and spaces. Use characters of +-0-9.eE, for example, 5, 1.9, -8.469, and 7.7e2. Also, Zuora does not convert currencies for decimal values.
Testing a Request
Use a third party client, such as curl, Postman, or Advanced REST Client, to test the Zuora REST API.
You can test the Zuora REST API from the Zuora API Sandbox or Production tenants. If connecting to Production, bear in mind that you are working with your live production data, not sample data or test data.
Testing with Credit Cards
Sooner or later it will probably be necessary to test some transactions that involve credit cards. For suggestions on how to handle this, see [Going Live With Your Payment Gateway](https://knowledgecenter.zuora.com/CBBilling/MPaymentGateways/CManagingPaymentGateways/BGoingLivePaymentGateways#TestingwithCreditCards "CZuoraUserGuides/ABillingandPayments/MPaymentGateways/CManagingPaymentGateways/BGoingLivePaymentGateways#TestingwithCredit_Cards"
).
Concurrent Request Limits
Zuora enforces tenant-level concurrent request limits. See Concurrent Request Limits for more information.
Timeout Limit
If a request does not complete within 120 seconds, the request times out and Zuora returns a Gateway Timeout error.
Error Handling
If a request to Zuora Billing REST API with an endpoint starting with /v1 (except Actions and CRUD operations) fails, the response will contain an eight-digit error code with a corresponding error message to indicate the details of the error.
The following code snippet is a sample error response that contains an error code and message pair:
The success field indicates whether the API request has succeeded. The processId field is a Zuora internal ID that you can provide to Zuora Global Support for troubleshooting purposes.
The reasons field contains the actual error code and message pair. The error code begins with 5 or 6 means that you encountered a certain issue that is specific to a REST API resource in Zuora Billing. For example, 53100320 indicates that an invalid value is specified for the termType field of the subscription object.
The error code beginning with 9 usually indicates that an authentication-related issue occurred, and it can also indicate other unexpected errors depending on different cases. For example, 90000011 indicates that an invalid credential is provided in the request header.
When troubleshooting the error, you can divide the error code into two components: REST API resource code and error category code. See the following Zuora error code sample:
Note: Zuora determines resource codes based on the request payload. Therefore, if GET and DELETE requests that do not contain payloads fail, you will get 500000 as the resource code, which indicates an unknown object and an unknown field.
The error category code of these requests is valid and follows the rules described in the Error Category Code section.
In such case, you can refer to the returned error message to troubleshoot.
REST API Resource Code
The 6-digit resource code indicates the REST API resource, typically a field of a Zuora object, on which the issue occurs. In the preceding example, 531003 refers to the termType field of the subscription object.
The value range for all REST API resource codes is from 500000 to 679999. See Resource Codes in the Knowledge Center for a full list of resource codes.
Error Category Code
The 2-digit error category code identifies the type of error, for example, resource not found or missing required field.
The following table describes all error categories and the corresponding resolution:
| Code | Error category | Description | Resolution |
|:--------|:--------|:--------|:--------|
| 10 | Permission or access denied | The request cannot be processed because a certain tenant or user permission is missing. | Check the missing tenant or user permission in the response message and contact Zuora Global Support for enablement. |
| 11 | Authentication failed | Authentication fails due to invalid API authentication credentials. | Ensure that a valid API credential is specified. |
| 20 | Invalid format or value | The request cannot be processed due to an invalid field format or value. | Check the invalid field in the error message, and ensure that the format and value of all fields you passed in are valid. |
| 21 | Unknown field in request | The request cannot be processed because an unknown field exists in the request body. | Check the unknown field name in the response message, and ensure that you do not include any unknown field in the request body. |
| 22 | Missing required field | The request cannot be processed because a required field in the request body is missing. | Check the missing field name in the response message, and ensure that you include all required fields in the request body. |
| 30 | Rule restriction | The request cannot be processed due to the violation of a Zuora business rule. | Check the response message and ensure that the API request meets the specified business rules. |
| 40 | Not found | The specified resource cannot be found. | Check the response message and ensure that the specified resource exists in your Zuora tenant. |
| 45 | Unsupported request | The requested endpoint does not support the specified HTTP method. | Check your request and ensure that the endpoint and method matches. |
| 50 | Locking contention | This request cannot be processed because the objects this request is trying to modify are being modified by another API request, UI operation, or batch job process. | Resubmit the request first to have another try. If this error still occurs, contact Zuora Global Support with the returned Zuora-Request-Id value in the response header for assistance. |
| 60 | Internal error | The server encounters an internal error. | Contact Zuora Global Support with the returned Zuora-Request-Id value in the response header for assistance. |
| 70 | Request exceeded limit | The total number of concurrent requests exceeds the limit allowed by the system. | Resubmit the request after the number of seconds specified by the Retry-After value in the response header. Check Concurrent request limits for details about Zuora’s concurrent request limit policy. |
| 90 | Malformed request | The request cannot be processed due to JSON syntax errors. | Check the syntax error in the JSON request body and ensure that the request is in the correct JSON format. |
| 99 | Integration error | The server encounters an error when communicating with an external system, for example, payment gateway, tax engine provider. | Check the response message and take action accordingly. |
Pagination
When retrieving information (using GET methods), the optional pageSize query parameter sets the maximum number of rows to return in a response. The maximum is 40; larger values are treated as 40. If this value is empty or invalid, pageSize typically defaults to 10.
The default value for the maximum number of rows retrieved can be overridden at the method level.
If more rows are available, the response will include a nextPage element, which contains a URL for requesting the next page. If this value is not provided, no more rows are available. No "previous page" element is explicitly provided; to support backward paging, use the previous call.
Array Size
For data items that are not paginated, the REST API supports arrays of up to 300 rows. Thus, for instance, repeated pagination can retrieve thousands of customer accounts, but within any account an array of no more than 300 rate plans is returned.
API Versions
The Zuora REST API are version controlled. Versioning ensures that Zuora REST API changes are backward compatible. Zuora uses a major and minor version nomenclature to manage changes. By specifying a version in a REST request, you can get expected responses regardless of future changes to the API.
Major Version
The major version number of the REST API appears in the REST URL. Currently, Zuora only supports the v1 major version. For example, POST https://rest.zuora.com/v1/subscriptions.
Minor Version
Zuora uses minor versions for the REST API to control small changes. For example, a field in a REST method is deprecated and a new field is used to replace it.
Some fields in the REST methods are supported as of minor versions. If a field is not noted with a minor version, this field is available for all minor versions. If a field is noted with a minor version, this field is in version control. You must specify the supported minor version in the request header to process without an error.
If a field is in version control, it is either with a minimum minor version or a maximum minor version, or both of them. You can only use this field with the minor version between the minimum and the maximum minor versions. For example, the invoiceCollect field in the POST Subscription method is in version control and its maximum minor version is 189.0. You can only use this field with the minor version 189.0 or earlier.
If you specify a version number in the request header that is not supported, Zuora will use the minimum minor version of the REST API. In our REST API documentation, if a field or feature requires a minor version number, we note that in the field description.
You only need to specify the version number when you use the fields require a minor version. To specify the minor version, set the zuora-version parameter to the minor version number in the request header for the request call. For example, the collect field is in 196.0 minor version. If you want to use this field for the POST Subscription method, set the zuora-version parameter to 196.0 in the request header. The zuora-version parameter is case sensitive.
For all the REST API fields, by default, if the minor version is not specified in the request header, Zuora will use the minimum minor version of the REST API to avoid breaking your integration.
Minor Version History
The supported minor versions are not serial. This section documents the changes made to each Zuora REST API minor version.
The following table lists the supported versions and the fields that have a Zuora REST API minor version.
| Fields | Minor Version | REST Methods | Description |
|:--------|:--------|:--------|:--------|
| invoiceCollect | 189.0 and earlier | Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Generates an invoice and collects a payment for a subscription. |
| collect | 196.0 and later | Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Collects an automatic payment for a subscription. |
| invoice | 196.0 and 207.0| Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Generates an invoice for a subscription. |
| invoiceTargetDate | 196.0 and earlier | Preview Subscription |Date through which charges are calculated on the invoice, as yyyy-mm-dd. |
| invoiceTargetDate | 207.0 and earlier | Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Date through which charges are calculated on the invoice, as yyyy-mm-dd. |
| targetDate | 207.0 and later | Preview Subscription |Date through which charges are calculated on the invoice, as yyyy-mm-dd. |
| targetDate | 211.0 and later | Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Date through which charges are calculated on the invoice, as yyyy-mm-dd. |
| includeExisting DraftInvoiceItems | 196.0 and earlier| Preview Subscription; Update Subscription | Specifies whether to include draft invoice items in subscription previews. Specify it to be true (default) to include draft invoice items in the preview result. Specify it to be false to excludes draft invoice items in the preview result. |
| includeExisting DraftDocItems | 207.0 and later | Preview Subscription; Update Subscription | Specifies whether to include draft invoice items in subscription previews. Specify it to be true (default) to include draft invoice items in the preview result. Specify it to be false to excludes draft invoice items in the preview result. |
| previewType | 196.0 and earlier| Preview Subscription; Update Subscription | The type of preview you will receive. The possible values are InvoiceItem(default), ChargeMetrics, and InvoiceItemChargeMetrics. |
| previewType | 207.0 and later | Preview Subscription; Update Subscription | The type of preview you will receive. The possible values are LegalDoc(default), ChargeMetrics, and LegalDocChargeMetrics. |
| runBilling | 211.0 and later | Create Subscription; Update Subscription; Renew Subscription; Cancel Subscription; Suspend Subscription; Resume Subscription; Create Account|Generates an invoice or credit memo for a subscription. Note: Credit memos are only available if you have the Invoice Settlement feature enabled. |
| invoiceDate | 214.0 and earlier | Invoice and Collect |Date that should appear on the invoice being generated, as yyyy-mm-dd. |
| invoiceTargetDate | 214.0 and earlier | Invoice and Collect |Date through which to calculate charges on this account if an invoice is generated, as yyyy-mm-dd. |
| documentDate | 215.0 and later | Invoice and Collect |Date that should appear on the invoice and credit memo being generated, as yyyy-mm-dd. |
| targetDate | 215.0 and later | Invoice and Collect |Date through which to calculate charges on this account if an invoice or a credit memo is generated, as yyyy-mm-dd. |
| memoItemAmount | 223.0 and earlier | Create credit memo from charge; Create debit memo from charge | Amount of the memo item. |
| amount | 224.0 and later | Create credit memo from charge; Create debit memo from charge | Amount of the memo item. |
| subscriptionNumbers | 222.4 and earlier | Create order | Container for the subscription numbers of the subscriptions in an order. |
| subscriptions | 223.0 and later | Create order | Container for the subscription numbers and statuses in an order. |
| creditTaxItems | 238.0 and earlier | Get credit memo items; Get credit memo item | Container for the taxation items of the credit memo item. |
| taxItems | 238.0 and earlier | Get debit memo items; Get debit memo item | Container for the taxation items of the debit memo item. |
| taxationItems | 239.0 and later | Get credit memo items; Get credit memo item; Get debit memo items; Get debit memo item | Container for the taxation items of the memo item. |
| chargeId | 256.0 and earlier | Create credit memo from charge; Create debit memo from charge | ID of the product rate plan charge that the memo is created from. |
| productRatePlanChargeId | 257.0 and later | Create credit memo from charge; Create debit memo from charge | ID of the product rate plan charge that the memo is created from. |
| comment | 256.0 and earlier | Create credit memo from charge; Create debit memo from charge; Create credit memo from invoice; Create debit memo from invoice; Get credit memo items; Get credit memo item; Get debit memo items; Get debit memo item | Comments about the product rate plan charge, invoice item, or memo item. |
| description | 257.0 and later | Create credit memo from charge; Create debit memo from charge; Create credit memo from invoice; Create debit memo from invoice; Get credit memo items; Get credit memo item; Get debit memo items; Get debit memo item | Description of the the product rate plan charge, invoice item, or memo item. |
Version 207.0 and Later
The response structure of the Preview Subscription and Update Subscription methods are changed. The following invoice related response fields are moved to the invoice container:
amount
amountWithoutTax
taxAmount
invoiceItems
targetDate
chargeMetrics
Zuora Billing Object Model
The following diagram is a high-level view of how key business objects are related to one another within Zuora Billing.
Click the diagram to open it in a new tab and zoom in.
For more information about the different sections of the diagram, see
Zuora Billing business object model.
This diagram is intended to provide a conceptual understanding; it does not illustrate a specific way to integrate with Zuora.
The diagram includes the Orders feature and the Invoice Settlement feature.
If your organization does not use either of these features, see
Zuora Billing business object model prior to Orders and Invoice Settlement
for an alternative diagram.
API Names
You can use the Describe object operation to list the fields of each Zuora object that is available in your tenant. When you call the operation, you must specify the API name of the Zuora object.
The following table provides the API name of each Zuora object:
| Object | API Name |
|-----------------------------------------------|--------------------------------------------|
| Account | Account |
| Accounting Code | AccountingCode |
| Accounting Period | AccountingPeriod |
| Amendment | Amendment |
| Application Group | ApplicationGroup |
| Billing Run | BillingRun - API name used in the Describe object operation, Export ZOQL queries, and Data Query. BillRun - API name used in the Actions. See the CRUD oprations of Bill Run for more information about the BillRun object. BillingRun and BillRun have different fields. |
| Contact | Contact |
| Contact Snapshot | ContactSnapshot |
| Credit Balance Adjustment | CreditBalanceAdjustment |
| Credit Memo | CreditMemo |
| Credit Memo Application | CreditMemoApplication |
| Credit Memo Application Item | CreditMemoApplicationItem |
| Credit Memo Item | CreditMemoItem |
| Credit Memo Part | CreditMemoPart |
| Credit Memo Part Item | CreditMemoPartItem |
| Credit Taxation Item | CreditTaxationItem |
| Custom Exchange Rate | FXCustomRate |
| Debit Memo | DebitMemo |
| Debit Memo Item | DebitMemoItem |
| Debit Taxation Item | DebitTaxationItem |
| Discount Applied Metrics | DiscountAppliedMetrics |
| Entity | Tenant |
| Feature | Feature |
| Gateway Reconciliation Event | PaymentGatewayReconciliationEventLog |
| Gateway Reconciliation Job | PaymentReconciliationJob |
| Gateway Reconciliation Log | PaymentReconciliationLog |
| Invoice | Invoice |
| Invoice Adjustment | InvoiceAdjustment |
| Invoice Item | InvoiceItem |
| Invoice Item Adjustment | InvoiceItemAdjustment |
| Invoice Payment | InvoicePayment |
| Journal Entry | JournalEntry |
| Journal Entry Item | JournalEntryItem |
| Journal Run | JournalRun |
| Order | Order |
| Order Action | OrderAction |
| Order ELP | OrderElp |
| Order Line Items | OrderLineItems |
| Order Item | OrderItem |
| Order MRR | OrderMrr |
| Order Quantity | OrderQuantity |
| Order TCB | OrderTcb |
| Order TCV | OrderTcv |
| Payment | Payment |
| Payment Application | PaymentApplication |
| Payment Application Item | PaymentApplicationItem |
| Payment Method | PaymentMethod |
| Payment Method Snapshot | PaymentMethodSnapshot |
| Payment Method Transaction Log | PaymentMethodTransactionLog |
| Payment Method Update | UpdaterDetail |
| Payment Part | PaymentPart |
| Payment Part Item | PaymentPartItem |
| Payment Run | PaymentRun |
| Payment Transaction Log | PaymentTransactionLog |
| Processed Usage | ProcessedUsage |
| Product | Product |
| Product Feature | ProductFeature |
| Product Rate Plan | ProductRatePlan |
| Product Rate Plan Charge | ProductRatePlanCharge |
| Product Rate Plan Charge Tier | ProductRatePlanChargeTier |
| Rate Plan | RatePlan |
| Rate Plan Charge | RatePlanCharge |
| Rate Plan Charge Tier | RatePlanChargeTier |
| Refund | Refund |
| Refund Application | RefundApplication |
| Refund Application Item | RefundApplicationItem |
| Refund Invoice Payment | RefundInvoicePayment |
| Refund Part | RefundPart |
| Refund Part Item | RefundPartItem |
| Refund Transaction Log | RefundTransactionLog |
| Revenue Charge Summary | RevenueChargeSummary |
| Revenue Charge Summary Item | RevenueChargeSummaryItem |
| Revenue Event | RevenueEvent |
| Revenue Event Credit Memo Item | RevenueEventCreditMemoItem |
| Revenue Event Debit Memo Item | RevenueEventDebitMemoItem |
| Revenue Event Invoice Item | RevenueEventInvoiceItem |
| Revenue Event Invoice Item Adjustment | RevenueEventInvoiceItemAdjustment |
| Revenue Event Item | RevenueEventItem |
| Revenue Event Item Credit Memo Item | RevenueEventItemCreditMemoItem |
| Revenue Event Item Debit Memo Item | RevenueEventItemDebitMemoItem |
| Revenue Event Item Invoice Item | RevenueEventItemInvoiceItem |
| Revenue Event Item Invoice Item Adjustment | RevenueEventItemInvoiceItemAdjustment |
| Revenue Event Type | RevenueEventType |
| Revenue Schedule | RevenueSchedule |
| Revenue Schedule Credit Memo Item | RevenueScheduleCreditMemoItem |
| Revenue Schedule Debit Memo Item | RevenueScheduleDebitMemoItem |
| Revenue Schedule Invoice Item | RevenueScheduleInvoiceItem |
| Revenue Schedule Invoice Item Adjustment | RevenueScheduleInvoiceItemAdjustment |
| Revenue Schedule Item | RevenueScheduleItem |
| Revenue Schedule Item Credit Memo Item | RevenueScheduleItemCreditMemoItem |
| Revenue Schedule Item Debit Memo Item | RevenueScheduleItemDebitMemoItem |
| Revenue Schedule Item Invoice Item | RevenueScheduleItemInvoiceItem |
| Revenue Schedule Item Invoice Item Adjustment | RevenueScheduleItemInvoiceItemAdjustment |
| Subscription | Subscription |
| Subscription Product Feature | SubscriptionProductFeature |
| Taxable Item Snapshot | TaxableItemSnapshot |
| Taxation Item | TaxationItem |
| Updater Batch | UpdaterBatch |
| Usage | Usage |

These endpoints are related to managing authentication tokens and identity for Xero API

Functionality at a glance
The NBG "UK OPB - Account and Transaction v3.1.5" API follows the [UK Open Banking Specification
v3.1.5](https://openbankinguk.github.io/read-write-api-site3/v3.1.5/profiles/account-and-transaction-api-profile.html)
This Account and Transaction API Specification describes the flows and payloads for retrieving a list of accounts and their transactions.
The API endpoints described here allow a AISP to:
Create the Consent with the appropriate permissions in order to be able to access the API Endpoints
Retrieve the list of accounts
Retrieve an account's details
Retrieve an account's balances
Retrieve an account's transactions
Retrieve an account's beneficiaries
Retrieve an account's standing orders
Retrieve an account's party
Retrieve an account's scheduled payments
Retrieve an account's statements
Quick Getting Started
Login/Register to the NBG Technology HUB
Go to "APPS"
Select your Organization and go to step 4. If you want to create a new Organization click \"CREATE AN ORGANIZATION\" and follow the steps below:
Enter the title of your Organization
Enter a short description of your Organization (optional)
Click "SUBMIT"
Select the Organization of choice and click "ADD AN APPLICATION"
Fill in the forms (title and short description)
Check \"Authorization Code\" and \"Client Credentials\"
Enter the OAuth Redirect and Post Logout URIs (these are the URIs that we will redirect the user upon logging in and logging out respectively)
You can use the following redirect URL to easily test the API through the portal: https://developer.nbg.gr/oauth2/redoc-callback
Click "SUBMIT"
Store the APPs "Client ID" and "Client Secret"
Go to "API PRODUCTS" and select the ACCOUNT INFORMATION - UK OPEN BANKING API
Click \"START USING THIS API\", choose your app and click
"SUBSCRIBE"
Get an Access Token using the Access Token Flow and the API scopes provided in the Authentication and Authorization (OAuth2) section below
Create a Sandbox
Play with the API
Sandbox Flow
The Sandbox Flow matches the Production Flow. The difference lies into the Data used. Instead of live
data, the Sandbox flow uses mocked data.
Production Flow
The Production Flow is described in the [UK Open Banking v3.1.5
Specification](https://openbankinguk.github.io/read-write-api-site3/v3.1.5/profiles/account-and-transaction-api-profile.html)
More details about the implementation specifics followed, please visit section **UK OPB Implementation
Specifics**
Authentication and Authorization (OAuth2)
This API version uses the OAuth2 protocol for authentication and authorization, which means that a
Bearer (access token) should be acquired. An access token can be retrieved using the client_id and
client_secret of the APP that you created and subscribed in this API, and your own credentials
(username, password) that you use to sign in the NBG Technology HUB. The scopes are defined below:
Authorization Endpoint:
https://my.nbg.gr/identity/connect/authorize
Token Endpoint:
https://my.nbg.gr/identity/connect/token
Authorization Code
Sandbox Scopes:
sandbox-uk-account-info-api-v1 offline_access
Production Scopes:
accounts offline_access
Client Credentials
Sandbox Scopes:
sandbox-uk-account-info-api-v1
Production Scopes:
accounts
See more here
QWAC Certificates
TPPs are required to present a QWAC certificate during API consumption. The API checks that this certificate has been provided and is valid. In sandbox mode the certificate validations are optional. To validate your certificate in sandbox implementation, please send us your QWAC certificate at [email protected] and set the HTTP Header \"x-sandbox-qwac-certificate-check\" with the value \"true\" in your requests.
SMS Challenge (One Time Password)
In order to successfully authorize an Accounts Access you will need to provide the SMS OTP (One Time Password) in the corresponding Accounts Consent UI Screen.
By default the SMS OTP will be sent to the mobile number declared upon singing up in the NBG Technology HUB.
Create your Sandbox
Create a new Sandbox application by invoking the POST /sandbox. This call will generate a new Sandbox
with a unique sandbox-id.
Important! Before proceeding save the sandbox id you just created.
When you create a sandbox, users and sandbox specific data are generated as sample data.
Start Testing
Once you have your sandbox-id, you can start invoking the rest of the operations by providing the
mandatory http header sandbox-id and the http headers described below.
Important notes
Request headers
The following HTTP header parameters are required for every call:
Authorization. The Auth2 Token
sandbox-id. Your Sandbox ID
Consent
In order to be able to effectively start using the Endpoints the appropriate Consent needs to be
created and set to the 'Authorised' status.
In order to create the Consent you need to at least set the required permissions and the Risk
sections.
Optionally you may set the
ExpirationDateTime. When the Consent expires
TransactionFromDateTime. Start Date to retrieve the transactions
TransactionToDateTime. End Date to retrieve the transactions
Not Implemented Endpoints
The following endpoints are not implemented in the API
GET /balances
GET /transactions
GET /beneficiaries
GET /accounts/\{AccountId\}/direct-debits
GET /direct-debits
GET /standing-orders
GET /accounts/\{AccountId\}/product
GET /products
GET /accounts/\{AccountId\}/offers
GET /offers
GET /scheduled-payments
GET /statements
Error Codes
The error codes and their description can be found
here
UK OPB Implementation Specifics
Below you may find more specific information & limitations regarding the implementation followed in the Production API.
Token Endpoint Client Authentication
At this point the supported Client Authentication method is "Client Secret Basic" - usage of "Client ID" & "Client Secret".
Consent Authorization
For a PSU to Authorize a Consent, they need to be redirected to the appropriate Consent UI.
For this redirection to take place the TPP needs to follow the Authorization Endpoint by amending the generated "Consent ID", like this: https://my.nbg.gr/identity/connect/authorize?consentid={{consentid}}&clientid={{clientid}}&scope={{scope}}&redirecturi={{redirecturi}}&response_type=code
Once the PSU is redirected to the Consent Authorization Screen, they need to enter their IBank (Production) or Developer Portal (Sandbox) Credentials and either Authorize or Reject the Consent.
At this point the Consent is binded with the PSU.
Debtor Account
Currently, only the "UK.OBIE.IBAN" scheme is supported.
Feedback and Questions
We would love to hear your feedback and answer your questions. Send us at
[email protected]
Check out our [Sandbox Postman
Collection](https://github.com/NBG-Developer-Portal/Account-Information-UK-Open-Banking)!
Created by NBG.
Entities
Below, the main entities are documented.
OBExternalPermissions1Code
Attributes
| Type| Description| Example| Values|
| -----| -----| -----| -----|
| enum| Specifies the Open Banking account access data types. This is a list of the data clusters being consented by the PSU, and requested for authorisation with the ASPSP.| ReadAccountsBasic ReadAccountsDetail ReadBalances ReadBeneficiariesBasic ReadBeneficiariesDetail ReadDirectDebits ReadOffers ReadPAN ReadParty ReadPartyPSU ReadProducts ReadScheduledPaymentsBasic ReadScheduledPaymentsDetail ReadStandingOrdersBasic ReadStandingOrdersDetail ReadStatementsBasic ReadStatementsDetail ReadTransactionsBasic ReadTransactionsCredits ReadTransactionsDebits ReadTransactionsDetail |
OBReadData1
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Permissions| Specifies the Open Banking account access data types. This is a list of the data clusters being consented by the PSU, and requested for authorisation with the ASPSP.| array[OBExternalPermissions1Code]|
| ExpirationDateTime| Specified date and time the permissions will expire. If this is not populated, the permissions will be open ended. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00| string|
| TransactionFromDateTime| Specified start date and time for the transaction query period. If this is not populated, the start date will be open ended, and data will be returned from the earliest available transaction. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00| string|
| TransactionToDateTime| Specified end date and time for the transaction query period. If this is not populated, the end date will be open ended, and data will be returned to the latest available transaction. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00| string|
OBRisk2
The Risk section is sent by the initiating party to the ASPSP. It is used to specify additional details for risk scoring for Account Info.
Attributes
| Name| Description| Values|
| -----| -----| -----|
OBReadConsent1
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Data | Entity | OBReadData1 Permissions array[[OBExternalPermissions1Code]] ExpirationDateTime [string] TransactionFromDateTime [string] TransactionToDateTime [string] |
| Risk | Entity | OBRisk2 |
ErrorCode
Attributes
| Type| Description| Example| Values|
| -----| -----| -----| -----|
| enum| This is Data Type gives a low level textual error code to help categorise an error response. The applicable HTTP response code is also given.| UK.OBIE.Field.Expected UK.OBIE.Field.Invalid UK.OBIE.Field.InvalidDate UK.OBIE.Field.Missing UK.OBIE.Field.Unexpected UK.OBIE.Header.Invalid UK.OBIE.Header.Missing UK.OBIE.Resource.ConsentMismatch UK.OBIE.Resource.InvalidConsentStatus UK.OBIE.Resource.InvalidFormat UK.OBIE.Resource.NotFound UK.OBIE.Rules.AfterCutOffDateTime UK.OBIE.Rules.DuplicateReference UK.OBIE.Signature.Invalid UK.OBIE.Signature.InvalidClaim UK.OBIE.Signature.MissingClaim UK.OBIE.Signature.Malformed UK.OBIE.Signature.Missing UK.OBIE.Signature.Unexpected UK.OBIE.Unsupported.AccountIdentifier UK.OBIE.Unsupported.AccountSecondaryIdentifier UK.OBIE.Unsupported.Currency UK.OBIE.Unsupported.EventType UK.OBIE.Unsupported.Frequency UK.OBIE.Unsupported.LocalInstrument UK.OBIE.Unsupported.Scheme UK.OBIE.Reauthenticate UK.OBIE.Rules.ResourceAlreadyExists UK.OBIE.UnexpectedError |
OBError1
Attributes
| Name| Description| Values|
| -----| -----| -----|
| ErrorCode | Entity | ErrorCode |
| Message| A description of the error that occurred. e.g., 'A mandatory field isn't supplied' or 'RequestedExecutionDateTime must be in future'OBIE doesn't standardise this field| string|
| Path| Recommended but optional reference to the JSON Path of the field with error, e.g., Data.Initiation.InstructedAmount.Currency| string|
OBErrorResponse1
An array of detail error codes, and messages, and URLs to documentation to help remediation.
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Code| High level textual error code, to help categorize the errors.| string|
| Id| A unique reference for the error instance, for audit purposes, in case of unknown/unclassified errors.| string|
| Message| Brief Error message, e.g., 'There is something wrong with the request parameters provided'| string|
| Errors| Gets or Sets Errors| array[OBError1]|
OBExternalRequestStatus1Code
Attributes
| Type| Description| Example| Values|
| -----| -----| -----| -----|
| enum| Specifies the status of consent resource in code form.| Authorised AwaitingAuthorisation Rejected Revoked |
OBReadDataConsentResponse1
Attributes
| Name| Description| Values|
| -----| -----| -----|
| ConsentId| Unique identification as assigned to identify the account access consent resource.| string|
| CreationDateTime| Date and time at which the resource was created. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00| string|
| Status | Entity | OBExternalRequestStatus1Code |
| StatusUpdateDateTime| Date and time at which the resource status was updated. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00| string|
| Permissions| Specifies the Open Banking account access data types. This is a list of the data clusters being consented by the PSU, and requested for authorisation with the ASPSP.| array[OBExternalPermissions1Code]|
| ExpirationDateTime| Specified date and time the permissions will expire. If this is not populated, the permissions will be open ended. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00| string|
| TransactionFromDateTime| Specified start date and time for the transaction query period. If this is not populated, the start date will be open ended, and data will be returned from the earliest available transaction. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00| string|
| TransactionToDateTime| Specified end date and time for the transaction query period. If this is not populated, the end date will be open ended, and data will be returned to the latest available transaction. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00| string|
Links
Links relevant to the payload
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Self| -| string|
| First| -| string|
| Prev| -| string|
| Next| -| string|
| Last| -| string|
Meta
Meta Data relevant to the payload
Attributes
| Name| Description| Values|
| -----| -----| -----|
| TotalPages| -| integer|
| FirstAvailableDateTime| All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone.An example is below: 2017-04-05T10:43:07+00:00| string|
| LastAvailableDateTime| All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone.An example is below: 2017-04-05T10:43:07+00:00| string|
OBReadConsentResponse1
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Data | Entity | OBReadDataConsentResponse1 ConsentId string] CreationDateTime [string] Status [[OBExternalRequestStatus1Code] StatusUpdateDateTime string] Permissions [array[[OBExternalPermissions1Code]] ExpirationDateTime [string] TransactionFromDateTime [string] TransactionToDateTime [string] |
| Risk | Entity | OBRisk2 |
| Links | Entity | Links Self [string] First [string] Prev [string] Next [string] Last [string] |
| Meta | Entity | Meta TotalPages [integer] FirstAvailableDateTime [string] LastAvailableDateTime [string] |
OBExternalAccountType1Code
Attributes
| Type| Description| Example| Values|
| -----| -----| -----| -----|
| enum| -| Business Personal |
OBExternalAccountSubType1Code
Attributes
| Type| Description| Example| Values|
| -----| -----| -----| -----|
| enum| -| ChargeCard CreditCard CurrentAccount EMoney Loan Mortgage PrePaidCard Savings |
OBCashAccount5
Attributes
| Name| Description| Values|
| -----| -----| -----|
| SchemeName| Name of the identification scheme, in a coded form as published in an external list.| string|
| Identification| Identification assigned by an institution to identify an account. This identification is known by the account owner.| string|
| Name| The account name is the name or names of the account owner(s) represented at an account level, as displayed by the ASPSP's online channels. Note, the account name is not the product name or the nickname of the account.| string|
| SecondaryIdentification| This is secondary identification of the account, as assigned by the account servicing institution. This can be used by building societies to additionally identify accounts with a roll number(in addition to a sort code and account number combination).| string|
OBBranchAndFinancialInstitutionIdentification5
Attributes
| Name| Description| Values|
| -----| -----| -----|
| SchemeName| Name of the identification scheme, in a coded form as published in an external list.| string|
| Identification| Unique and unambiguous identification of the servicing institution.| string|
OBAccount6
Unambiguous identification of the account to which credit and debit entries are made.
Attributes
| Name| Description| Values|
| -----| -----| -----|
| AccountId| A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.| string|
| Currency| Identification of the currency in which the account is held. Usage: Currency should only be used in case one and the same account number covers several currencies and the initiating party needs to identify which currency needs to be used for settlement on the account.| string|
| AccountType | Entity | OBExternalAccountType1Code |
| AccountSubType | Entity | OBExternalAccountSubType1Code |
| Description| Specifies the description of the account type.| string|
| Nickname| The nickname of the account, assigned by the account owner in order to provide an additional means of identification of the account.| string|
| OpeningDate| Date on which the account and related basic services are effectively operational for the account owner.All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00| string|
| Account| Provides the details to identify an account.| array[OBCashAccount5]|
| Servicer | Entity | OBBranchAndFinancialInstitutionIdentification5 SchemeName [string] Identification [string] |
OBReadDataAccount5
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Account| Unambiguous identification of the account to which credit and debit entries are made.| array[OBAccount6]|
OBReadAccount5
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Data | Entity | OBReadDataAccount5 Account array[[OBAccount6]] |
| Links | Entity | Links Self [string] First [string] Prev [string] Next [string] Last [string] |
| Meta | Entity | Meta TotalPages [integer] FirstAvailableDateTime [string] LastAvailableDateTime [string] |
OBCreditDebitCode
Attributes
| Type| Description| Example| Values|
| -----| -----| -----| -----|
| enum| -| Credit Debit |
OBBalanceType1Code
Attributes
| Type| Description| Example| Values|
| -----| -----| -----| -----|
| enum| -| ClosingAvailable ClosingBooked ClosingCleared Expected ForwardAvailable Information InterimAvailable InterimBooked InterimCleared OpeningAvailable OpeningBooked OpeningCleared PreviouslyClosedBooked |
OBActiveOrHistoricCurrencyAndAmount
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Amount| A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.| string|
| Currency| A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".| string|
OBExternalLimitType1Code
Attributes
| Type| Description| Example| Values|
| -----| -----| -----| -----|
| enum| -| Available Credit Emergency Pre-Agreed Temporary |
OBCreditLine1
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Included| Indicates whether or not the credit line is included in the balance of the account. Usage: If not present, credit line is not included in the balance amount of the account.| boolean|
| Type | Entity | OBExternalLimitType1Code |
| Amount | Entity | OBActiveOrHistoricCurrencyAndAmount Amount [string] Currency [string] |
OBCashBalance1
Set of elements used to define the balance details.
Attributes
| Name| Description| Values|
| -----| -----| -----|
| AccountId| A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.| string|
| CreditDebitIndicator | Entity | OBCreditDebitCode |
| Type | Entity | OBBalanceType1Code |
| DateTime| Indicates the date (and time) of the balance.All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00| string|
| Amount | Entity | OBActiveOrHistoricCurrencyAndAmount Amount [string] Currency [string] |
| CreditLine| Set of elements used to provide details on the credit line.| array[OBCreditLine1]|
OBReadDataBalance1
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Balance| Set of elements used to define the balance details.| array[OBCashBalance1]|
OBReadBalance1
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Data | Entity | OBReadDataBalance1 Balance array[[OBCashBalance1]] |
| Links | Entity | Links Self [string] First [string] Prev [string] Next [string] Last [string] |
| Meta | Entity | Meta TotalPages [integer] FirstAvailableDateTime [string] LastAvailableDateTime [string] |
OBBeneficiaryType1Code
Attributes
| Type| Description| Example| Values|
| -----| -----| -----| -----|
| enum| Specifies the Beneficiary Type.| Trusted Ordinary |
OBBeneficiary5
Attributes
| Name| Description| Values|
| -----| -----| -----|
| AccountId| A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.| string|
| BeneficiaryType | Entity | OBBeneficiaryType1Code |
| CreditorAccount | Entity | OBCashAccount5 SchemeName [string] Identification [string] Name [string] SecondaryIdentification [string] |
OBReadDataBeneficiary5
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Beneficiary| -| array[OBBeneficiary5]|
OBReadBeneficiary5
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Data | Entity | OBReadDataBeneficiary5 Beneficiary array[[OBBeneficiary5]] |
| Links | Entity | Links Self [string] First [string] Prev [string] Next [string] Last [string] |
| Meta | Entity | Meta TotalPages [integer] FirstAvailableDateTime [string] LastAvailableDateTime [string] |
OBParty2
Attributes
| Name| Description| Values|
| -----| -----| -----|
| PartyId| A unique and immutable identifier used to identify the customer resource. This identifier has no meaning to the account owner.| string|
| Name| Name by which a party is known and which is usually used to identify that party.| string|
OBReadDataParty2
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Party | Entity | OBParty2 PartyId [string] Name [string] |
OBReadParty2
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Data | Entity | OBReadDataParty2 Party [OBParty2] PartyId [string] Name [string] |
| Links | Entity | Links Self [string] First [string] Prev [string] Next [string] Last [string] |
| Meta | Entity | Meta TotalPages [integer] FirstAvailableDateTime [string] LastAvailableDateTime [string] |
OBReadDataParty3
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Party| -| array[OBParty2]|
OBReadParty3
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Data | Entity | OBReadDataParty3 Party array[[OBParty2]] |
| Links | Entity | Links Self [string] First [string] Prev [string] Next [string] Last [string] |
| Meta | Entity | Meta TotalPages [integer] FirstAvailableDateTime [string] LastAvailableDateTime [string] |
SandboxRequest
Request to create a new sandbox
Attributes
| Name| Description| Values|
| -----| -----| -----|
| sandboxId| Sandbox Id| string|
ErrorResponse
Attributes
| Name| Description| Values|
| -----| -----| -----|
| errorMessage| -| string|
SandboxRetryCacheEntry
Keeps the number of calls without x-fapi-customer-ip-address header present
Attributes
| Name| Description| Values|
| -----| -----| -----|
| cacheKey| Cache key| string|
| count| Number of retries ( up to 4 )| integer|
| expirationTimestamp| Expiration timestamp of the entry| string|
SandboxBankAccountInfo
General account information
Attributes
| Name| Description| Values|
| -----| -----| -----|
| currency| Currency (EUR, USD ...)| string|
| iban| Account's IBAN| string|
| accountType| Account's type (Business, Personal)| string|
| accountSubType| Account's sub-type (ChargeCard, CreditCard, CurrentAccount ...)| string|
| description| Account's description| string|
| alias| Account's alias| string|
| openingDate| Account's opening date| string|
| availableBalance| Account's available balance| number|
| ledgerBalance| Account's ledger balance| number|
| overdraftLimit| Account's overdraft limit| number|
SandboxParty
Connected party information
Attributes
| Name| Description| Values|
| -----| -----| -----|
| id| Party id| string|
| name| Name| string|
SandboxBeneficiary
Beneficiary information
Attributes
| Name| Description| Values|
| -----| -----| -----|
| name| Beneficiary name| string|
SandboxStandingOrder
Standing order information
Attributes
| Name| Description| Values|
| -----| -----| -----|
| description| Standing order short description| string|
| frequency| Standing order frequency| string|
| firstPaymentDate| Standing order first collection date| string|
| nextPaymentDate| Standing order next collection date| string|
| finalPaymentDate| Standing order final collection date| string|
| lastPaymentDate| Standing order last executed payment date| string|
| status| Standing order status (Active, Inactive)| string|
| amount| Standing order amount| number|
SandboxScheduledPayment
Scheduled payment information
Attributes
| Name| Description| Values|
| -----| -----| -----|
| description| Scheduled payment's short description| string|
| executionDate| Scheduled payment's execution date| string|
| amount| Amount| number|
| senderReference| Debtor / Sender reference| string|
SandboxStatement
Statement information
Attributes
| Name| Description| Values|
| -----| -----| -----|
| number| Statement number| string|
| year| Statement year| integer|
| month| Statement month| integer|
SandboxTransaction
Transaction information
Attributes
| Name| Description| Values|
| -----| -----| -----|
| reference| Transaction reference| string|
| amount| Amount| number|
| currency| Currency (EUR, USD ...)| string|
| creditDebit| Credit / Debit indicator| string|
| valueDateTime| Valeur| string|
| bookingDateTime| Booking date time| string|
| description| Description| string|
| accountingBalance| Balance| number|
| relatedAccount| Related account| string|
| relatedName| Related account| string|
| transactionCode| Transaction code| string|
SandboxBankAccount
Sandbox bank account
Attributes
| Name| Description| Values|
| -----| -----| -----|
| info | Entity | SandboxBankAccountInfo currency [string] iban [string] accountType [string] accountSubType [string] description [string] alias [string] openingDate [string] availableBalance [number] ledgerBalance [number] overdraftLimit [number] |
| party | Entity | SandboxParty id [string] name [string] |
| beneficiaries| List of account's beneficiaries| array[SandboxBeneficiary]|
| standingOrders| List of account's standing orders| array[SandboxStandingOrder]|
| scheduledPayments| List of account's scheduled payments| array[SandboxScheduledPayment]|
| statements| List of account's statements| array[SandboxStatement]|
| transactions| List of account's transactions| array[SandboxTransaction]|
SandboxCardInfo
Sandbox card information
Attributes
| Name| Description| Values|
| -----| -----| -----|
| number| Card number| string|
| description| Description| string|
| holderName| Holder name| string|
| expiration| Expiration date (05/2022)| string|
| type| Type| string|
| subType| Sub type| string|
| availableBalance| Available balance| number|
| ledgerBalance| Ledger balance| number|
| creditLimit| Credit limit ( applicable to credit cards )| number|
SandboxCard
Sandbox card
Attributes
| Name| Description| Values|
| -----| -----| -----|
| info | Entity | SandboxCardInfo number [string] description [string] holderName [string] expiration [string] type [string] subType [string] availableBalance [number] ledgerBalance [number] creditLimit [number] |
| party | Entity | SandboxParty id [string] name [string] |
| statements| Card statements| array[SandboxStatement]|
| transactions| Card transactions| array[SandboxTransaction]|
SandboxUser
User data
Attributes
| Name| Description| Values|
| -----| -----| -----|
| userId| Connected user id| string|
| retryCacheEntries| Retry cache entries| array[SandboxRetryCacheEntry]|
| accounts| List of accounts| array[SandboxBankAccount]|
| cards| List of cards| array[SandboxCard]|
Sandbox
Sandbox model
Attributes
| Name| Description| Values|
| -----| -----| -----|
| sandboxId| Sandbox id| string|
| users| List of users| array[SandboxUser]|
OBExternalScheduleType1Code
Attributes
| Type| Description| Example| Values|
| -----| -----| -----| -----|
| enum| -| Arrival Execution |
OBScheduledPayment3
Attributes
| Name| Description| Values|
| -----| -----| -----|
| AccountId| A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.| string|
| ScheduledPaymentId| A unique and immutable identifier used to identify the scheduled payment resource. This identifier has no meaning to the account owner.| string|
| ScheduledPaymentDateTime| The date on which the scheduled payment will be made.All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone.An example is below: 2017-04-05T10:43:07+00:00| string|
| ScheduledType | Entity | OBExternalScheduleType1Code |
| Reference| Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction. Usage: If available, the initiating party should provide this reference in the structured remittance information, to enable reconciliation by the creditor upon receipt of the amount of money. If the business context requires the use of a creditor reference or a payment remit identification, and only one identifier can be passed through the end-to-end chain, the creditor's reference or payment remittance identification should be quoted in the end-to-end transaction identification.| string|
| DebtorReference| A reference value provided by the PSU to the PISP while setting up the scheduled payment.| string|
| InstructedAmount | Entity | OBActiveOrHistoricCurrencyAndAmount Amount [string] Currency [string] |
| CreditorAccount | Entity | OBCashAccount5 SchemeName [string] Identification [string] Name [string] SecondaryIdentification [string] |
OBReadDataScheduledPayment3
Attributes
| Name| Description| Values|
| -----| -----| -----|
| ScheduledPayment| -| array[OBScheduledPayment3]|
OBReadScheduledPayment3
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Data | Entity | OBReadDataScheduledPayment3 ScheduledPayment array[[OBScheduledPayment3]] |
| Links | Entity | Links Self [string] First [string] Prev [string] Next [string] Last [string] |
| Meta | Entity | Meta TotalPages [integer] FirstAvailableDateTime [string] LastAvailableDateTime [string] |
OBExternalStandingOrderStatus1Code
Attributes
| Type| Description| Example| Values|
| -----| -----| -----| -----|
| enum| -| Active Inactive |
OBStandingOrder5
Attributes
| Name| Description| Values|
| -----| -----| -----|
| AccountId| A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.| string|
| StandingOrderId| A unique and immutable identifier used to identify the standing order resource. This identifier has no meaning to the account owner.| string|
| Frequency| Individual Definitions: IntrvlMnthDay - An interval specified in months(between 01, 02, 03, 04, 06, 12, 24), specifying the day within the month(01 to 31) Full Regular Expression: ^(IntrvlMnthDay:(0[1,2,3,4,6]|12|24):(0[1-9]|[12] [0-9]|3[01]))$| string|
| Reference| Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction. Usage: If available, the initiating party should provide this reference in the structured remittance information, to enable reconciliation by the creditor upon receipt of the amount of money. If the business context requires the use of a creditor reference or a payment remit identification, and only one identifier can be passed through the end-to-end chain, the creditor's reference or payment remittance identification should be quoted in the end-to-end transaction identification.| string|
| FirstPaymentDateTime| The date on which the first payment for a Standing Order schedule will be made.All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone.An example is below: 2017-04-05T10:43:07+00:00| string|
| NextPaymentDateTime| The date on which the next payment for a Standing Order schedule will be made.All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone.An example is below: 2017-04-05T10:43:07+00:00| string|
| LastPaymentDateTime| The date on which the last (most recent) payment for a Standing Order schedule was made.All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone.An example is below: 2017-04-05T10:43:07+00:00| string|
| FinalPaymentDateTime| The date on which the final payment for a Standing Order schedule will be made.All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone.An example is below: 2017-04-05T10:43:07+00:00| string|
| StandingOrderStatusCode | Entity | OBExternalStandingOrderStatus1Code |
| FirstPaymentAmount | Entity | OBActiveOrHistoricCurrencyAndAmount Amount [string] Currency [string] |
| NextPaymentAmount | Entity | OBActiveOrHistoricCurrencyAndAmount Amount [string] Currency [string] |
| LastPaymentAmount | Entity | OBActiveOrHistoricCurrencyAndAmount Amount [string] Currency [string] |
| FinalPaymentAmount | Entity | OBActiveOrHistoricCurrencyAndAmount Amount [string] Currency [string] |
| CreditorAccount | Entity | OBCashAccount5 SchemeName [string] Identification [string] Name [string] SecondaryIdentification [string] |
OBReadDataStandingOrder5
Attributes
| Name| Description| Values|
| -----| -----| -----|
| StandingOrder| -| array[OBStandingOrder5]|
OBReadStandingOrder6
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Data | Entity | OBReadDataStandingOrder5 StandingOrder array[[OBStandingOrder5]] |
| Links | Entity | Links Self [string] First [string] Prev [string] Next [string] Last [string] |
| Meta | Entity | Meta TotalPages [integer] FirstAvailableDateTime [string] LastAvailableDateTime [string] |
OBExternalStatementType1Code
Attributes
| Type| Description| Example| Values|
| -----| -----| -----| -----|
| enum| -| AccountClosure AccountOpening Annual Interim RegularPeriodic |
OBStatement2
Provides further details on a statement resource.
Attributes
| Name| Description| Values|
| -----| -----| -----|
| AccountId| A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.| string|
| StatementId| Unique identifier for the statement resource within an servicing institution. This identifier is both unique and immutable.| string|
| StatementReference| Unique reference for the statement. This reference may be optionally populated if available.| string|
| Type | Entity | OBExternalStatementType1Code |
| StartDateTime| Date and time at which the statement period starts.All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone.An example is below: 2017-04-05T10:43:07+00:00| string|
| EndDateTime| Date and time at which the statement period starts.All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone.An example is below: 2017-04-05T10:43:07+00:00| string|
| CreationDateTime| Date and time at which the statement period starts.All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone.An example is below: 2017-04-05T10:43:07+00:00| string|
OBReadDataStatement2
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Statement| Provides further details on a statement resource.| array[OBStatement2]|
OBReadStatement2
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Data | Entity | OBReadDataStatement2 Statement array[[OBStatement2]] |
| Links | Entity | Links Self [string] First [string] Prev [string] Next [string] Last [string] |
| Meta | Entity | Meta TotalPages [integer] FirstAvailableDateTime [string] LastAvailableDateTime [string] |
OBEntryStatus1Code
Attributes
| Type| Description| Example| Values|
| -----| -----| -----| -----|
| enum| -| Booked Pending |
ProprietaryBankTransactionCodeStructure1
Set of elements to fully identify a proprietary bank transaction code.
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Code| Proprietary bank transaction code to identify the underlying transaction.| string|
| Issuer| Identification of the issuer of the proprietary bank transaction code.| string|
OBTransactionCashBalance
Set of elements used to define the balance as a numerical representation of the net increases and decreases in an account after a transaction entry is applied to the account.
Attributes
| Name| Description| Values|
| -----| -----| -----|
| CreditDebitIndicator | Entity | OBCreditDebitCode |
| Type | Entity | OBBalanceType1Code |
| Amount | Entity | OBActiveOrHistoricCurrencyAndAmount Amount [string] Currency [string] |
OBCashAccount6
Unambiguous identification of the account of the creditor, in the case of a debit transaction.
Attributes
| Name| Description| Values|
| -----| -----| -----|
| SchemeName| Name of the identification scheme, in a coded form as published in an external list.| string|
| Identification| Identification assigned by an institution to identify an account. This identification is known by the account owner.| string|
| Name| The account name is the name or names of the account owner(s) represented at an account level, as displayed by the ASPSP's online channels. Note, the account name is not the product name or the nickname of the account.| string|
OBTransaction6
Provides further details on an entry in the report.
Attributes
| Name| Description| Values|
| -----| -----| -----|
| AccountId| A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.| string|
| TransactionReference| Unique reference for the transaction. This reference is optionally populated, and may as an example be the FPID in the Faster Payments context.| string|
| CreditDebitIndicator | Entity | OBCreditDebitCode |
| Status | Entity | OBEntryStatus1Code |
| BookingDateTime| Date and time when a transaction entry is posted to an account on the account servicer's books. Usage: Booking date is the expected booking date, unless the status is booked, in which case it is the actual booking date.All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone.An example is below: 2017-04-05T10:43:07+00:00| string|
| ValueDateTime| Date and time at which assets become available to the account owner in case of a credit entry, or cease to be available to the account owner in case of a debit transaction entry. Usage: If transaction entry status is pending and value date is present, then the value date refers to an expected/requested value date. For transaction entries subject to availability/float and for which availability information is provided, the value date must not be used.In this case the availability component identifies the number of availability days.All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone.An example is below: 2017-04-05T10:43:07+00:00| string|
| TransactionInformation| Further details of the transaction. This is the transaction narrative, which is unstructured text.| string|
| Amount | Entity | OBActiveOrHistoricCurrencyAndAmount Amount [string] Currency [string] |
| ProprietaryBankTransactionCode | Entity | ProprietaryBankTransactionCodeStructure1 Code [string] Issuer [string] |
| Balance | Entity | OBTransactionCashBalance CreditDebitIndicator [OBCreditDebitCode] Type [OBBalanceType1Code] Amount [OBActiveOrHistoricCurrencyAndAmount] Amount [string] Currency [string] |
| CreditorAccount | Entity | OBCashAccount6 SchemeName [string] Identification [string] Name [string] |
| DebtorAccount | Entity | OBCashAccount6 SchemeName [string] Identification [string] Name [string] |
OBReadDataTransaction6
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Transaction| Provides further details on an entry in the report.| array[OBTransaction6]|
OBReadTransaction6
Attributes
| Name| Description| Values|
| -----| -----| -----|
| Data | Entity | OBReadDataTransaction6 Transaction array[[OBTransaction6]] |
| Links | Entity | Links Self [string] First [string] Prev [string] Next [string] Last [string] |
| Meta | Entity | Meta TotalPages [integer] FirstAvailableDateTime [string] LastAvailableDateTime [string] |
Authentication

Summary
The Swiss NextGen API is based on the NextGenPSD2 Framework Version 1.3.4 of the Berlin Group which offers a modern, open, harmonised and interoperable set of
Application Programming Interfaces (APIs) as the safest and most efficient way to provide data securely.
The NextGen Framework reduces XS2A complexity and costs, addresses the problem of multiple competing standards
in Europe and, aligned with the goals of the Euro Retail Payments Board,
enables European banking customers to benefit from innovative products and services ('Banking as a Service')
by granting TPPs safe and secure (authenticated and authorised) access to their bank accounts and financial data.
The Swiss edtion refines the message formats specific to Switzerland and defines some matching examples.
The possible Approaches are:
Redirect SCA Approach
(Not recommended by obp.ch community) OAuth SCA Approach
(Not recommended by obp.ch community) Decoupled SCA Approach
(Not recommended by obp.ch community) Embedded SCA Approach without SCA method
(Not recommended by obp.ch community) Embedded SCA Approach with only one SCA method available
(Not recommended by obp.ch community) Embedded SCA Approach with Selection of a SCA method
Not every message defined in this API definition is necessary for all approaches.
Furthermore this API definition does not differ between methods which are mandatory, conditional, or optional
Therefore for a particular implementation of a compliant API it is only necessary to support
a certain subset of the methods defined in this API definition.
**Please have a look at the implementation guidelines if you are not sure
which message has to be used for the approach you are going to use.**
Some General Remarks Related to this version of the OpenAPI Specification:
This API definition is based on the Implementation Guidelines of the Berlin Group API.
It is not a replacement in any sense.
The main specification is (at the moment) always the Implementation Guidelines of the Berlin Group API.
This API definition contains the REST-API for requests from the PISP to the ASPSP.
This API definition contains the messages for all different approaches defined in the Implementation Guidelines.
According to the OpenAPI-Specification [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md]
"If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored."
The element "Accept" will not be defined in this file at any place.
The elements "Content-Type" and "Authorization" are implicitly defined by the OpenApi tags "content" and "security".
There are several predefined types which might occur in payment initiation messages,
but are not used in the standard JSON messages in the Implementation Guidelines.
Therefore they are not used in the corresponding messages in this file either.
We added them for the convenience of the user.
If there is a payment product, which needs these fields, one can easily use the predefined types.
But the ASPSP need not to accept them in general.
**We omit the definition of all standard HTTP header elements (mandatory/optional/conditional)
except they are mentioned in the Implementation Guidelines.**
Therefore the implementer might add these in his own realisation of a comlient API in addition to the elements defined in this file.
General Remarks on Data Types
The Berlin Group definition of UTF-8 strings in context of the API have to support at least the following characters
a b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 4 5 6 7 8 9
/ - ? : ( ) . , ' +
Space

UPDATE: We have released a beta version of the new bunq API documentation.
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 that connects to the bunq Sandbox environment. To create accounts for the Sandbox app, please follow the steps in the 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:
Create an API key. You can do it either in our developer portal or in the bunq app (Profile → Security & Settings → Developers → API keys). If you want to test our sandbox first, our bunq Developer is the best place to start.
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.
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.
Make your first call!
bunqAPIcontext
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 to make sure you don't miss any important updates.
OAuth
What is OAuth?
OAuth 2.0 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.
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:
Register an OAuth Client by creating an app in bunq Developer.
Add one or more Redirect URLs.
Get your client_id and secret from your app information tab in bunq Developer.
Redirect your users to the OAuth authorization request URL.
If the user accepts the authorization request, they will be redirected to the previously specified redirect_uri with an authorization code parameter.
Use the token endpoint to exchange the authorization code for an access_token.
Use the access_token as a normal API Key. Open a session or use our SDKs 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.
bunqOAuthcredentials
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:
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 that's optimised for emulating;
Android Studio.
Starting the Android Virtual Device (AVD) Manager
Open Android Studio.
From the top menu, select “Tools” > "Android" > "AVD Manager".
Setting up a new virtual device
Start the wizard by clicking on "+ Create Virtual Device".
Select a device (recommendation: "Pixel 5.0" or "Nexus 6") and press "Next".
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.
In the bottom left corner, select "Show Advanced Settings".
Scroll to "Memory and Storage".
Change "Internal Storage" to "2048 MB".
Change "SD card" to "200 MB".
Press "Finish".
Starting the virtual device
On the right side under "Actions", select the green "Play" button.
Wait for the device to boot, this may take a few minutes.
Installing the bunq Sandbox App APK
Open the command line.
Navigate to your Android SDK platform tools directory (e.g. cd ~/Library/Android/sdk/platform-tools on macOS).
Make sure that the virtual device is started and has fully booted.
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
Create a sandbox account in the developer portal.
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:
Install Tinker.
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.
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:
create an app in the developer portal, or
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;
generate an API key in the sandbox app (Profile → Security & Settings → Developers → API keys);
get an API key from 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: nlNL" --header "X-Bunq-Region: nlNL" --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 counterpartyalias. Make sure you set the correct type for the alias, depending on what you pass. When providing an IBAN, a name of the counterpartyalias 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 totalamount of the tab when you change its status to WAITINGFOR_PAYMENT.
7. PUT tab-usage-single
Update the status of the tab to WAITINGFORPAYMENT 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 cashregisterqr_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 tabqrcode 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:
Check the list of supported currencies via GET /user/{userID}/transferwise-currency. Copy the needed currency code.
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.
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
Create a quote via POST /user/{userID}/transferwise-quote and save its ID.
ℹ️ Use amounttarget to indicate the sum the recipient must get. Amountsource, 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.
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:
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
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. 🎉
Check if there are any additional transfer requirements via POST /user/{userID}/transferwise-quote/{transferwise-quoteID}/transferwise-transfer-requirement.
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
The bunq user has accepted the authorization request and your application can read the bunq user’s account information.
Your application imports all the transactions and attachments.
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
List the payments of the user via GET /user/{userID}/monetary-account/{monetary-accountID}/payment.
Check if the payments have attachments via GET /user/{userID}/monetary-account/{monetary-accountID}/payment/{paymentID}/note-attachment. Save the attachment IDs.
Export the raw content of the attachments via GET /user/{userID}/attachment/{attachmentID}/content.
HINT: You can use callbacks to make sure you don’t miss anything happening on the bunq account.

Processe arquivos de retorno CNAB