About API
API
We aim to provide experiences that exceed expectations. We have built our open API around the Representational State Transfer Service architecture (REST), a standard HTTP and easy-to-read and write JavaScript Object Notation (JSON). We follow the Berlin Group API specifications and the Implementation guide and also extended the associated documentation to meet the regulatory requirements.
API HTTP Methods
- All services are accessed through APIs using REST based HTTPS methods:
- GET: Reads a resource and returns it;
- POST: Creates a new resource;
- PUT: Requests that the entity provided is stored in the URI provided;
- DELETE: Deletes the resource identified by URI.
API availability status
The API availability status is used to inform TPP developers regarding API
(feature) lifecycle. The availability status is defined for API operations, parameters, models, and properties
| Status | This status is used for the API (feature) that is implemented but is still subject to change. This API can be used by developers in Sandbox and Production, but Bank`s is not obliged to guarantee that significant changes to this API will not be introduced in future. The features the API in Beta status might also be completely removed in future releases. The Beta API’s changes first appear in the Sandbox environment and later in the Production environment. This way TPP developers will have time to adapt to the upcoming changes in the Production API. |
|---|---|
| Beta | The draft status is used for APIs which are still in design phase. |
| Draft | The APIs in Production status are in use in Production environment and should be used in Production applications. No significant changes will be made to the stable APIs (features). |
| Production | The APIs in Production status are in use in Production environment and should be used in Production applications. No significant changes will be made to the stable APIs (features). |
| Sandbox Only | The APIs with Sandbox only status are only available in the Sandbox environment and will not be available in the Production environment. |
| Deprecated | The APIs with Deprecated status will be removed in the future. Deprecated APIs will continue to be supported by the Papaya’s developer’s portal for six months. |
API in Swagger format
The Bank API specification is available in the swagger format. More information about it can be found here. The swagger files for this API can be downloaded from these links:
Live Papaya XS2A API specification v1.0 – login
SandBox Papaya XS2A API specification v1.0 – login
API lifecycle
- The API version number is always included in the API call:
- https://tpp-sandbox.papaya.eu/banklink/v1/{service} (sandbox)
- https://tpp.papaya.eu/banklink/v1/{service} (live)
The API version number in the URL indicates the major version of the API.
There can be minor updates to the APIs which do not change the major version number. The major version number only changes when the big number changes which might significantly impact API backwards compatibility is implemented. The new major versions of specification will depend on Berlin Group specification releases and NCA mandates, such changes will be published 3 months prior to the release date. The older versions of APIs will be deprecated but remain available for up to six months after release implementation, and removed after this period. API major version number will be incremented with every new major API release, e.g. next API version will typically have URL in following format:
- https://tpp-sandbox.papaya.eu/banklink/v2/{service} (sandbox)
- https://tpp.papaya.eu/banklink/v2/{service} (live)
HTTP Response Codes
The HTTP response code is communicating the success or failure of a TPP request message. The 4XX HTTP response codes only be given if the current
request cannot be fulfilled, in example if a payment initiation cannot be posted, or account transactions cannot be retrieved. A request to get the status of an existing payment or a consent returns HTTP response code 200 since the actual request to retrieve the status succeeded, regardless if that payment or consent state is set to failure or not.
| Code | Description |
|---|---|
| 200 OK | This return code is permitted if a request was repeated due to a time-out. The response in that might be either a 200 or 201 code. The POST for a Funds request will also return 200 since it does not create a new resource. DELETE Response Code where a payment resource has been cancelled successfully and no further cancellation authorisation is required. |
| 201 Created | POST response code where Payment Initiation or Consent Request was correctly performed. |
| 202 Accepted | DELETE response code, where a payment resource can be cancelled in general, but a cancellation authorisation is needed in addition. |
| 204 No Content | DELETE response code where a consent resource was successfully deleted. The code indicates that the request was performed, but no content was returned. |
| 400 Bad Request | Validation error occurred. This code will cover malformed syntax in request or incorrect data in payload. |
| 401 Unauthorized | The TPP or the PSU is not correctly authorized to perform the request. Retry the request with correct authentication information. |
| 403 Forbidden | Returned if the resource that was referenced in the path exists but cannot be accessed by the TPP or the PSU. |
| 404 Not found | Returned if the resource or endpoint that was referenced in the path does not exist or cannot be referenced by the TPP or the PSU. |
| 405 Method Not Allowed | This code is only sent when the HTTP method (PUT,POST, DELETE, GET etc.) is not supported on a specific endpoint. It has nothing to do with the consent,payment or account information data model. |
| 406 Not Acceptable | The ASPSP cannot generate the content that the TPP specified in the Accept header. |
| 408 Request Timeout | The server is still working correctly, but an individual request has timed out. |
| 415 Unsupported Media Type | The TPP has supplied a media type which the ASPSP does not support. |
| 429 Too Many Requests | The TPP has exceeded the number of requests allowed by the consent or by the RTS. |
| 500 Internal Server Error | Internal server error occurred. |
| 503 Service Unavailable | The ASPSP server is currently unavailable. Generally, this is a temporary state. |