Skip to content

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.

API Endpoints

Endpoint Description System-to-System Documentation
Account API with operations related to an account. X Read More
Adyen API with operations related to the Payway - Adyen integration. X Read More
Campaign API for creating a campaign in Payway. Meant to be used to automatically create a campaign from an ESS. X Read More
Cancellation Reasons API with operations related to Cancellation Reasons. X Read More
Klarna payments API API with operations related to the Payway - Klarna payments integration. X Read More
Marketing Permissions API with operations related to Marketing Permissions. X Read More
Me API used with access-tokens tied to an account. To perform operations in the context of the end user. Read More
Order API with operations related to Orders. X Read More
Price API for changing price on package and campaign periods. X Read More
Product API for getting product information. X Read More
Subscription API with operations for subscriptions X Read More
Subscription System API dedicated for use with the new standard Subscription System integration. X Read More
User Agreement API API with operations related to user agreements. X Read More
User Product API for controlling subscriptions owned by external systems, such as App Store, Google play etc. X Read More
Voucher API for creating Vouchers. X Read More

Required Headers

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

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

Common Error Responses

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 message will contain these properties in every response. Some error responses will add additional data for troubleshooting. Third-party errors from other systems for example.

Standard error

Standard error containing code, field and message.

1
2
3
4
5
{
  "code": "error_code",
  "field": "field",
  "message": "error message"
}

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.

1
2
3
4
5
6
{
  "code": "error_code",
  "field": "field",
  "message": "error message",
  "correlation_id": "correlation_id only available for third party errors"
}

Additional error data

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

1
2
3
4
5
6
7
8
{
  "code": "already_set",
  "field": "national_identification_number",
  "message": "123321-1234 already set",
  "error_data": {
    "national_identification_number": "123321-1234"
  }
}

400 Bad request

json_parser_error

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

1
2
3
4
5
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

1
2
3
4
5
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

1
2
3
4
5
6
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.

1
2
3
4
5
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.

1
2
3
4
5
6
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.

1
2
3
4
5
HTTP 403 Forbidden
{
  "code": "forbidden",
  "message": "<descriptive error message>"
}

404 Not found

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

1
2
3
4
5
6
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.