Payway API¶

Target audience: Developers, Stakeholders

Introduction¶

Payway provides a number of HTTP based API Endpoints for various operations.

In order to call the API Endpoints you need an API Client with the required scopes. A PAP user in the "superusers"-group can create and edit API Clients. The administration interface for this can be found in the Security-section of the PAP. Please read more about accessing the Payway API here.

Required Headers¶

When calling the HTTP-based APIs the following headers must be set:

Authorization: Bearer <insert_access_token_here>
Content-Type: application/json
Accept: application/json

API Versioning¶

A new API-endpoint version will be introduced when necessary to avoid introducing breaking changes.

Breaking changes include:

Change in field names
Change in resource paths
Removing fields
Change in value format
Change in HTTP verbs

None breaking changes, not resulting in new API-endpoint version, includes:

Additive changes, such as introducing new fields, endpoints or verbs

UNSET¶

The __UNSET__ pattern is used in Payway when you want to empty a value for an entity.

Example use case	Entity
Remove alias	Account

Example payload

{
  "account": {
    "alias": "__UNSET__",
    ...
    ..
  }  
}

__UNSET__ is used instead of null, "", or the default value for the type in question. This removes the need to pass in all information about an entity to perform an update on a single value.

All entity values do not support __UNSET__. When you try to unset a value that does not support it, it will result in an unset error.

Error handling¶

The API Endpoints have a collection of error conditions they might report but they all follow a common convention.

The error response is sent as application/JSON and will have an HTTP status code ranging between 400-500.

An error response will contain at at minimum the message property. Depending on the error more properties will be available. But in most cases you will receive a message and a code. Some error responses will add additional data for troubleshooting. Third-party errors from other systems for example.

Standard error¶

Standard error containing code, field, message and a pw_correlation_id.

code is used to identify the type of error. E.g. does_not_exist
field is the subject of the error. E.g. account
message is, well, the message.
pw_correlation_id is a used to identify the unique error occurence.

{
  "code": "error_code",
  "field": "field",
  "message": "error message",
  "pw_correlation_id": "pw-api-9dd0bf57-cf8a-4e1b-a3ed-dba991820d4f"
}

Third party error¶

Third party error containing all the values of a standard error, plus a correlation_id used to identify the error in the third party system.

{
  "code": "error_code",
  "field": "field",
  "message": "error message",
  "pw_correlation_id": "pw-api-9dd0bf57-cf8a-4e1b-a3ed-dba991820d4f",
  "correlation_id": "correlation_id only available for third party errors"
}

Third party error with correlation data¶

Third party error containing all the values of a standard error and a third party error.
If the third party supports correlation data it will be received in correlation_data.

{
  "code": "error_code",
  "field": "field",
  "message": "error message",
  "pw_correlation_id": "pw-api-9dd0bf57-cf8a-4e1b-a3ed-dba991820d4f",
  "correlation_id": "correlation_id only available for third party errors",
  "correlation_data": {
      "status": "403",
      "error_code": "901",
      "message": "Invalid Merchant Account",
      "error_type": "security",
      "psp_reference": "851563882585825A",
      "refusal_reason": "Expired Card",
      "result_code": "Refused",
      "refusal_reason_code": "2"
  }
}

Additional error data¶

A standard error with additional error_data to help in troubleshooting and automation.

{
  "code": "already_set",
  "field": "national_identification_number",
  "message": "123321-1234 already set",
  "pw_correlation_id": "pw-api-9dd0bf57-cf8a-4e1b-a3ed-dba991820d4f",
  "error_data": {
    "national_identification_number": "123321-1234"
  }
}

400 Bad request¶

unset error¶

Occurs when you try to unset a parameter that cannot be unset.

HTTP 400 Bad Request
{
  "code": "invalid_parameter",
  "field": "social_security_number",
  "message": "social_security_number cannot be __UNSET__"
}

json_parser_error¶

Occurs when the json payload in the request body can not be properly parsed.

HTTP 400 Bad Request
{
  "code": "json_parser_error",
  "message": "Invalid json in request body"
}

invalid_content_type_error¶

The requests Content-Type header is not set to application/json

HTTP 400 Bad Request
{
  "code": "invalid_content_type_error",
  "message": "<descriptive error message>"
}

invalid_parameter¶

Validation error on any of the fields in the requests json-payload

HTTP 400 Bad Request
{
  "code": "invalid_parameter",
  "field": "social_security_number",
  "message": "<descriptive error message>"
}

unknown_parameter¶

One or more of the fields in the requests json-payload was not recognized.

HTTP 400 Bad Request
{
  "code": "unknown_parameter",
  "message": "Unknown parameters: unknown_api_parameter_1,unknown_api_parameter_2"
}

configuration_error¶

One or more configuration errors occured. This will usually indicate that you have to contact Servicedesk to help resolve your problem.

HTTP 400 Bad Request
{
  "code": "configuration_error",
  "field": "<effected field if any>",
  "message": "<descriptive error message>"
}

403 Forbidden¶

This usually means that the operation tried to do something that is not allowed in the context of the operation.

HTTP 403 Forbidden
{
  "code": "forbidden",
  "message": "<descriptive error message>"
}

404 Not found¶

Indicates that one or more of the requested resources was not found.

HTTP 404 Not found
{
  "code": "not_found",
  "field": "<effected field if any>",
  "message": "<descriptive error message>"
}

409 Conflict¶

A 409 response usually means a specific domain error occured. These might depend on what operation is being performed. Important to study the error messages and codes when these happen. More information about specific 409 errors can be found in the documentation for specific endpoints.