# 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](https://www.berlin-group.org/nextgenpsd2-downloads).** 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
# Introduction
[OpenFinTech.io](https://openfintech.io) is an open database that comprises of standardized primary data for FinTech industry.
It contains such information as geolocation data (countries, cities, regions), organizations, currencies (national, digital, virtual, crypto), banks, digital exchangers, payment providers (PSP), payment methods, etc.
It is created for communication of cross-integrated micro-services on "one language". This is achieved through standardization of entity identifiers that are used to exchange information among different services.
### UML
UML Domain Model diagram you can find [here](https://api.openfintech.io/public_domain_model.png).
### Persistence
Entities are updated not more than 1 time per day.
### Terms and Conditions
This *OpenFinTech.io* is made available under the [Open Database License](http://opendatacommons.org/licenses/odbl/1.0/).
Any rights in individual contents of the database are licensed under the [Database Contents License](http://opendatacommons.org/licenses/dbcl/1.0/).
### Contacts
For any questions, please email - info@openfintech.io
Or you can contact us at Gitter
Powered by [Paymaxi](https://www.paymaxi.com)
# Get Started
If you use [POSTMAN](https://www.getpostman.com) or similar program which can operate with swagger`s files - just [download](https://docs.openfintech.io) our spec and [import it](https://www.getpostman.com/docs/importing_swagger). Also you can try live [API demo](https://api.openfintech.io).
## Overview
The OpenFinTech API is organized around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer). Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors.
API is based on [JSON API](http://jsonapi.org) standard. JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.
JSON API requires use of the JSON API media type (`application/vnd.api+json`) for exchanging data.
### Additional Request Headers
#### ACCEPT HEADER
Your requests should always include the header:
```curl
Accept: application/vnd.api+json
```
## Authentication
To use OpenFinTech API no needed authorization.
## Versioning
When we make changes to the API, we release new, dated versions. The current version is **2017-08-24**. Read our [API upgrades guide]() to see our API changelog and to learn more about backwards compatibility.
## Pagination
OpenFinTech APIs to retrieve lists of banks, currencies and other resources - paginated to **100** items by default. The pagination information will be included in the list API response under the node name `meta` - contains information about listed objects [`total` - contains information about total count of listed objects, `pages` - count of pages], `links` - contain links to navigate between pages [`first` - link to first page, `prev` - link to previous page, `next` - link to next page, `last` - link to last page].
By default first page will be listed. For navigating through pages, use the page parameter (e.g. `page[number]`, `page[size]`).
The `page[size]` parameter can be used to set the number of records that you want to receive in the response.
The `page[number]` parameter can be used to set needed page number.
Example of response:
```json
{
"meta": {
"total": 419,
"pages": 42
},
"links": {
"first": "/v1/{path}?page[number]=1&page[size]=10",
"prev": "/v1/{path}?page[number]=39&page[size]=10",
"next": "/v1/{path}?page[number]=41&page[size]=10",
"last": "/v1/{path}?page[number]=42&page[size]=10"
}
```
### Sorting
OpenFinTech\`s API supported query parameter to sort result collection [e.g. `?sort=code`]. Information about available parameters may be found in the endpoint description. Positive parameter [e.g. `?sort=code`] points to ascending sorting, negative [e.g. `?sort=-code`] - to descending sorting. Also, supported multiple sorting parameters [e.g. `?sort=code, -name, id`, etc.]
```curl
https://api.openfintech.io/v1/countries?sort=name,-area
```
### Filtering
Filtering provided by unique query key `filter[*filtering_condition*]`. Information about available parameters may be found in the endpoint description.
```curl
https://api.openfintech.io/v1/countries?filter[region]=europe
```
## Images
OpenFinTech provides two types of images: icons and logos. To get one of those types you should to use next url pattern:
``` curl
https://api.openfintech.io/v1/{path}/{id}/{icon/logo}
```
Also, images can be resized by adding next parameters: `h={height}&w={width}`. For example, you want to get organization icon with width equals to 20 pixels:
``` curl
https://api.openfintech.io/v1/organizations/{id}/icon?w=20&h=20
```
If argument height or width is missing API returns original image with real sizes.
## Errors
API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.), and codes in the `5xx` range indicate an error with OpenFinTech's servers (these are rare).
| Code | Description |
|------|-------------|
| 200 - OK | Everything worked as expected. |
| 400 - Bad Request | The request was unacceptable, often due to missing a required parameter. |
| 401 - Unauthorized | No valid API key provided. |
| 402 - Request Failed | The parameters were valid but the request failed. |
| 404 - Not Found | The requested resource doesn't exist. |
| 409 - Conflict | The request conflicts with another request (perhaps due to using the same idempotent key). |
| 429 - Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |
| 500, 502, 503, 504 - Server Errors | Something went wrong on OpenFinTech's end. (These are rare.) |
For general questions and support of the API, contact: webservices@paylocity.com # Overview Paylocity Web Services API is an externally facing RESTful Internet protocol. The Paylocity API uses HTTP verbs and a RESTful endpoint structure. OAuth 2.0 is used as the API Authorization framework. Request and response payloads are formatted as JSON. Paylocity supports v1 and v2 versions of its API endpoints. v1, while supported, won't be enhanced with additional functionality. For direct link to v1 documentation, please click [here](https://docs.paylocity.com/weblink/guides/Paylocity_Web_Services_API/v1/Paylocity_Web_Services_API.htm). For additional resources regarding v1/v2 differences and conversion path, please contact webservices@paylocity.com. ##### Setup Paylocity will provide the secure client credentials and set up the scope (type of requests and allowed company numbers). You will receive the unique client id, secret, and Paylocity public key for the data encryption. The secret will expire in 365 days. * Paylocity will send you an e-mail 10 days prior to the expiration date for the current secret. If not renewed, the second e-mail notification will be sent 5 days prior to secret's expiration. Each email will contain the code necessary to renew the client secret. * You can obtain the new secret by calling API endpoint using your current not yet expired credentials and the code that was sent with the notification email. For details on API endpoint, please see Client Credentials section. * Both the current secret value and the new secret value will be recognized during the transition period. After the current secret expires, you must use the new secret. * If you were unable to renew the secret via API endpoint, you can still contact Service and they will email you new secret via secure email. When validating the request, Paylocity API will honor the defaults and required fields set up for the company default New Hire Template as defined in Web Pay. # Authorization Paylocity Web Services API uses OAuth2.0 Authentication with JSON Message Format. All requests of the Paylocity Web Services API require a bearer token which can be obtained by authenticating the client with the Paylocity Web Services API via OAuth 2.0. The client must request a bearer token from the authorization endpoint: auth-server for production: https://api.paylocity.com/IdentityServer/connect/token auth-server for testing: https://apisandbox.paylocity.com/IdentityServer/connect/token Paylocity reserves the right to impose rate limits on the number of calls made to our APIs. Changes to API features/functionality may be made at anytime with or without prior notice. ##### Authorization Header The request is expected to be in the form of a basic authentication request, with the "Authorization" header containing the client-id and client-secret. This means the standard base-64 encoded user:password, prefixed with "Basic" as the value for the Authorization header, where user is the client-id and password is the client-secret. ##### Content-Type Header The "Content-Type" header is required to be "application/x-www-form-urlencoded". ##### Additional Values The request must post the following form encoded values within the request body: grant_type = client_credentials scope = WebLinkAPI ##### Responses Success will return HTTP 200 OK with JSON content: { "access_token": "xxx", "expires_in": 3600, "token_type": "Bearer" } # Encryption Paylocity uses a combination of RSA and AES cryptography. As part of the setup, each client is issued a public RSA key. Paylocity recommends the encryption of the incoming requests as additional protection of the sensitive data. Clients can opt-out of the encryption during the initial setup process. Opt-out will allow Paylocity to process unencrypted requests. The Paylocity Public Key has the following properties: * 2048 bit key size * PKCS1 key format * PEM encoding ##### Properties * key (base 64 encoded): The AES symmetric key encrypted with the Paylocity Public Key. It is the key used to encrypt the content. Paylocity will decrypt the AES key using RSA decryption and use it to decrypt the content. * iv (base 64 encoded): The AES IV (Initialization Vector) used when encrypting the content. * content (base 64 encoded): The AES encrypted request. The key and iv provided in the secureContent request are used by Paylocity for decryption of the content. We suggest using the following for the AES: * CBC cipher mode * PKCS7 padding * 128 bit block size * 256 bit key size ##### Encryption Flow * Generate the unencrypted JSON payload to POST/PUT * Encrypt this JSON payload using your _own key and IV_ (NOT with the Paylocity public key) * RSA encrypt the _key_ you used in step 2 with the Paylocity Public Key, then, base64 encode the result * Base64 encode the IV used to encrypt the JSON payload in step 2 * Put together a "securecontent" JSON object: { 'secureContent' : { 'key' : -- RSA-encrypted & base64 encoded key from step 3, 'iv' : -- base64 encoded iv from step 4 'content' -- content encrypted with your own key from step 2, base64 encoded } } ##### Sample Example { "secureContent": { "key": "eS3aw6H/qzHMJ00gSi6gQ3xa08DPMazk8BFY96Pd99ODA==", "iv": "NLyXMGq9svw0XO5aI9BzWw==", "content": "gAEOiQltO1w+LzGUoIK8FiYbU42hug94EasSl7N+Q1w=" } } ##### Sample C# Code using Newtonsoft.Json; using System; using System.IO; using System.Security.Cryptography; using System.Text; public class SecuredContent { [JsonProperty("key")] public string Key { get; set; } [JsonProperty("iv")] public string Iv { get; set; } [JsonProperty("content")] public string Content { get; set; } } public class EndUserSecureRequestExample { public string CreateSecuredRequest(FileInfo paylocityPublicKey, string unsecuredJsonRequest) { string publicKeyXml = File.ReadAllText(paylocityPublicKey.FullName, Encoding.UTF8); SecuredContent secureContent = this.CreateSecuredContent(publicKeyXml, unsecuredJsonRequest); string secureRequest = JsonConvert.SerializeObject(new { secureContent }); return secureRequest; } private SecuredContent CreateSecuredContent(string publicKeyXml, string request) { using (AesCryptoServiceProvider aesCsp = new AesCryptoServiceProvider()) { aesCsp.Mode = CipherMode.CBC; aesCsp.Padding = PaddingMode.PKCS7; aesCsp.BlockSize = 128; aesCsp.KeySize = 256; using (ICryptoTransform crt = aesCsp.CreateEncryptor(aesCsp.Key, aesCsp.IV)) { using (MemoryStream outputStream = new MemoryStream()) { using (CryptoStream encryptStream = new CryptoStream(outputStream, crt, CryptoStreamMode.Write)) { byte[] encodedRequest = Encoding.UTF8.GetBytes(request); encryptStream.Write(encodedRequest, 0, encodedRequest.Length); encryptStream.FlushFinalBlock(); byte[] encryptedRequest = outputStream.ToArray(); using (RSACryptoServiceProvider crp = new RSACryptoServiceProvider()) { crp.FromXmlstring(publicKeyXml); byte[] encryptedKey = crp.Encrypt(aesCsp.Key, false); return new SecuredContent() { Key = Convert.ToBase64string(encryptedKey), Iv = Convert.ToBase64string(aesCsp.IV), Content = Convert.ToBase64string(encryptedRequest) }; } } } } } } } ## Support Questions about using the Paylocity API? Please contact webservices@paylocity.com. # Deductions (v1) Deductions API provides endpoints to retrieve, add, update and delete deductions for a company's employees. For schema details, click here. # OnBoarding (v1) Onboarding API sends employee data into Paylocity Onboarding to help ensure an easy and accurate hiring process for subsequent completion into Web Pay. For schema details, click here.
Portfolio Optimizer is a [Web API](https://en.wikipedia.org/wiki/Web_API) to analyze and optimize investment portfolios (collection of financial assets such as stocks, bonds, ETFs, crypto-currencies) using modern portfolio theory algorithms (mean-variance, VaR, etc.).
# API General Information
Portfolio Optimizer is based on [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) for easy integration, uses [JSON](https://en.wikipedia.org/wiki/JSON) for the exchange of data and uses a standard [HTTP verb](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) (`POST`) to represent the action(s).
Portfolio Optimizer is also as secured as a Web API could be:
* [256-bit HTTPS Encryption](https://en.wikipedia.org/wiki/HTTPS)
* 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:
* `Content-Encoding: gzip`
This header indicates that the data provided in input to the endpoint is compressed with gzip.
* `X-API-Key:
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 support@taxrates.io
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 support@taxrates.io
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: apiteam@taxrates.io