API Definition
This section outlines an overview of our API standards and practises, ensuring consistent interactions. Below you will find information on our versioning and change policy, supported http codes etc.
Versioning Policy
Our versioning is done via the URL, example: https://rest.pay.nl/v2/transactions. The version is updated as a whole instead of only updating a single namespace by one version.
Change policy
| Description | Request change | Response change |
|---|---|---|
| Adding new resources and/or methods to existing resources | Backwards compatible | Backwards Compatible |
| Adding / Removing / Modifying optional fields on an entity | Backwards compatible | Backwards compatible |
| Adding new required fields with a default value | Backwards compatible | Backwards compatible |
| Changing the order of fields | Backwards compatible | Backwards compatible |
| Changes to documentation without changing functionality | Backwards compatible | Backwards compatible |
| Change a required field to optional | Backwards Compatible | New Version |
| Change an optional field to required | New Version | Backwards Compatible |
| Changing the URL of a resource | New version | New version |
| Changing the type of a field (string to int for example) | New version | New version |
| Changing the name of a field and keeping the old field intact | Backwards compatible | Backwards compatible |
| Add required fields without a default value | New version | New version |
| Change validation rules on a field that’s more limited (length 128 to length 64) | New version | Backwards compatible |
| Change validation rules on a field that’s less limited (length 64 to length 128) | Backwards compatible | New version |
HTTP response codes
HTTP-code | Explanation | Body |
|---|---|---|
200 - Ok | The server has processed the request (GET) | Contains the Resources data that can be used in your application. You can check per API the response. |
201 - Created | The server has processed the request (POST) Resource has been created. | Resources is CREATED or UNSUSPENDED, Contains the Resources data that can be used to continue your application. |
204 - No content | The server has processed the request (DELETE) | No Body |
400 - Bad Request | Information was sent in that can not be processed. | Contains the posted Resources that generate errors. Including the error codes to resolve the issue. Check the error code for more information. |
401 - Unauthorized | Invalid credentials, please check if authentication-username and password contains valid token or account data. | No Body |
403 - Forbidden | No rights to perform this action. You can't request data that is not accessible via the credentials used. Unlike 401 Unauthorized, the client's identity is known to the server. | No Body |
404 - Not Found | The server can not find the requested resource. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist. Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an unauthorized client. This response code is probably the most well known due to its frequent occurrence on the web. | No Body |
405 - Method not allowed | The request method is known by the server but is not supported by the target resource. For example, an API may not allow calling DELETE to remove a resource. | Use GET/POST/UPDATE/DELETE. |
406 - Not acceptable | The Accept header format provided by the request is not supported. Check the supported Accept headers | No Body |
415 - Unsupported media Type | The Content Type header format provided by the request is not supported. Check the supported Content-Type Header | No Body |
422 - Unprocessable Entity | There is an administrative issue that prevent us from processing your request. | Contains information about the issue that should be resolved before you can proceed |
429 - Rate limit | You performed too many requests to the platform according to your licence. | Expect the limit and the releasetime? |
500 - Server error | The server could not process your request. A message is sent to PAY. monitoring team. | No Body |
Accept Headers
Defines how you want to receive the data from the API. If you give a different value as accept header you will get a HTTP 406 response code.
| Valid input | Description |
|---|---|
| Accept: / | You will receive the response in JSON format (default). |
| Accept: application/json | You want to receive the response in JSON format |
Content-Type Header
Defines how you send the data to the API. If you give different value as content-type header you will get a HTTP 415 response code.
| Valid input | Description |
|---|---|
| Content-type: application/json | You post the data in JSON format. |
Swagger files
| Name | URL |
|---|---|
| pay-card-payments.json | https://developer.pay.nl/openapi/pay-card-payments.json |
| pay-clearing-and-invoicing-apis.json | https://developer.pay.nl/openapi/pay-clearing-and-invoicing-apis.json |
| pay-gmsapi.json | https://developer.pay.nl/openapi/pay-gmsapi.json |
| pay-idefix-rest.json | https://developer.pay.nl/openapi/pay-idefix-rest.json |
| pay-idefix-trx.json | https://developer.pay.nl/openapi/pay-idefix-trx.json |
| pay-terminal-payments.json | https://developer.pay.nl/openapi/pay-terminal-payments.json |
| pay-tgu.json | https://developer.pay.nl/openapi/pay-tgu.json |
Updated about 1 month ago