Skip to content

Subscription System integration (SSI)

Target Audience: Users, Developers, Stakeholders

Introduction

Info

Please note: This is the preferred way of integrating External Subscription Systems with Payway. Subscription System integrations performed pre 2018-01-01 may differ in implementation details. If you are unsure how your integration works please contact Adeprimo.

Integrating an External Subscription System (ESS) to Payway (PW) is done using three different concepts: Events, Callbacks, and Interfaces.

PW publishes events whenever something of importance takes place in the system, such as an order being placed, a subscription being renewed or someone canceling their subscription. By reacting to these events the ESS can synchronize its state to match the state in PW.

When reacting to these events the ESS might create data that needs to be reported back to PW, such as a new subscription number being set on a specific subscription. To accommodate this PW exposes a callback API that the ESS can use to propagate these events back to PW.

For some of the functionality to work as expected the ESS must expose some of its data, such as Customer data and Subscription data, to PW. The data being exposed should match the Interfaces provided to simplify integration.

Abbreviations

Abbreviation Full name Description
ESS External Subscription System The system being integrated e.g. Kayak, CProfit, Infosoft
PW Payway
PAP Payway Administration Portal The administration portal. Found on https://your_organisation_id.admin.worldoftulo.com
PCP Payway Customer Portal The pages in Payway that the customer can access, including "My account" and the purchase pages

Events

PW publishes events whenever something of importance takes place in the system, such as an order being placed, a subscription being renewed or someone canceling their subscription. By reacting to these events the ESS can synchronize its state to match the state in PW.

Events are being published through HTTP POST-requests in json-format. The integration must supply HTTP-endpoints that PW can post to that can process the events being published.

Protocol

The events are automatically re-sent in case the receiving end-point answers with anything other than a 200 OK. This creates a requirement on the consumer to only respond with something other than 200 OK when the event can safely be re-sent from PW.

Re-sending events occur once every hour. After 10 retries an e-mail notification will be sent to the maintainer of the endpoint. After 50 retries on one event, the end-point will be marked as not usable and all events going out to that specific endpoint will be queued until the endpoint is manually marked as usable again.

Event objects

Order

{
    "id": "<order id>",
    "order_reference": "ORGANISATION-123",
    "created": "2014-05-05T22:49:22+00:00",
    "amount": "100.00", #The amount of the order
    "payment_method": "creditcard",
    "specific_payment_method_name": "Card", #Only available when payment_method is adyen, see tables below
    "specific_payment_method_type": "scheme", #Only available when payment_method is adyen, see tables below
    "traffic_source": "youtube",
    "delivery_address": {
        "first_name": "Test",
        "last_name": "Tester",
        "street": "Testvägen",
        "street_number": 23,
        "staircase": "",
        "floor": "3",
        "apartment": "AS", #Can be used for the shorthand for apartment. For example AS.
        "apartment_number": "",
        "zip_code": "",
        "city": "",
        "care_of": "", #Can be used for the C/O part if applicable
        "citizenship_country_code": "SV",
        "company_crn": null,
        "company_department": null,
        "company_name": null,
        "company_reference": null,
        "company_vat_number": null,
        "contact_email": "user@email.com",
        "drop_box": null,
        "country_code": "",
        "mobile_number": "0501231234"
    }
}
Payment methods
Name Description
creditcard Payment with creditcard via VismaPay
invoice Invoicing via ESS
directdebit Payment with online bank via VismaPay
adyen Payment via Adyen, specific method described below
Adyen specific payment methods
Name Type
Card (Credit card, language depending on your settings in Adyen) scheme
Finnish E-Banking ebanking_FI
MobilePay mobilepay

Payment

{
    "id": "<payment_id>",
    "created": "2014-05-05T22:49:22+00:00",
    "amount": "100.00",
    "method": "creditcard",
    "specific_payment_method_name": "Card", #Only available when method is adyen, see tables above
    "specific_payment_method_type": "scheme", #Only available when method is adyen, see tables above
    "transaction_reference": "123456"
    }

Specific Events

Partial objects are described here.

new_subscription

This event is emitted whenever an order has been processed and completed successfully in PW. It describes what, when and how a customer has purchased a new subscription.

{
    "event_name": "new_subscription",
    "timestamp": "2014-05-05T22:48:22+00:00",
    "account_id": "<payway account id>",
    "email": "<payway account email>",
    "customer_number": "<customer number>",
    "birth_date":  "<birth date>",
    "company_registration_number": "<company registration number>", #empty string if not set,
    "company_name": "<company name>",
    "order": {
        "id": "<order id>",
        "order_reference": "ORGANISATION-123",
        "created": "2014-05-05T22:49:22+00:00",
        "amount": "100.00", #The amount of the order
        "payment_method": "creditcard",
        "specific_payment_method_name": "Card", #Only available when payment_method is adyen
        "specific_payment_method_type": "scheme", #Only available when payment_method is adyen
        "traffic_source": "youtube",
        "delivery_address": {
          "first_name": "Test",
          "last_name": "Tester",
          "street": "Testvägen",
          "street_number": 23,
          "staircase": "",
          "floor": "3",
          "apartment": "AS", #Can be used for the shorthand for apartment. For example AS.
          "apartment_number": "",
          "zip_code": "",
          "city": "",
          "care_of": "", #Can be used for the C/O part if applicable
          "citizenship_country_code": "SV",
          "company_crn": null,
          "company_department": null,
          "company_name": null,
          "company_reference": null,
          "company_vat_number": null,
          "contact_email": "user@email.com",
          "drop_box": null,
          "country_code": "",
          "mobile_number": "0501231234"
        }
    },
    # The payment object will be null when the payment method for the order is invoice.
    "payment": {
        "id": "<payment_id>",
        "created": "2014-05-05T22:49:22+00:00",
        "amount": "100.00",
        "method": "creditcard",
        "specific_payment_method_name": "Card", #Only available when method is adyen
        "specific_payment_method_type": "scheme", #Only available when method is adyen
        "transaction_reference": "123456"
    },
    "subscription": {
        "id": "<user_product_id>",
        "subscription_number": "<empty string>", #Subscription number is assigned later by the ESS
        "created": "2014-05-05T22:49:22+00:00",
        "start_date": "2014-05-05T22:49:22+00:00",
        "period_end": "2014-06-05T22:49:22+00:00",
        "payway_product_code": "<payway_product_code>",
        "title_code": "<title_code>",
        "external_package_id": "<payway_package_integration_code>", #The unique identifier of the package for the subscription for the package in the ESS
        "external_campaign_id": "<payway_campaign_integration_code>",#The unique identifier of the campaign for the subscription for the package in the ESS
        "period": "month",
        "period_length": 1,
        "campaign": <true|false>,
        "transition_to_package": <true|false>, #signals if the campaign will continue to normal package. Only valid if campaign=true
        "type": "<recurring|limited>" # only if package, if campaign = ""
    }
}

new_gift_subscription

This event is emitted whenever an order on a gift has been processed and completed successfully in PW. It describes what, when and how a customer has purchased a new subscription for another person.

{
    "event_name": "new_gift_subscription",
    "timestamp": "2014-05-05T22:48:22+00:00",
    "giver": {
        "account_id": "<payway account id>",
        "email": "<payway account email>",
        "customer_number": "<customer_number>"
    },
    "receiver": {
        "email" : "<email address of the receiver>", #Not mandatory, can be empty  
        "delivery_address": {
          "first_name": "Test",
          "last_name": "Tester",
          "street": "Testvägen",
          "street_number": 23,
          "staircase": "",
          "floor": "3",
          "apartment": "AS", #Can be used for the shorthand for apartment. For example AS.
          "apartment_number": "",
          "zip_code": "",
          "city": "",
          "care_of": "", #Can be used for the C/O part if applicable
          "citizenship_country_code": "SV",
          "company_crn": null,
          "company_department": null,
          "company_name": null,
          "company_reference": null,
          "company_vat_number": null,
          "contact_email": "user@email.com",
          "drop_box": null,
          "country_code": "",
          "mobile_number": "0501231234"
        }
    },
    "order": {
        "id": "<order id>",
        "order_reference": "ORGANISATION-123",
        "created": "2014-05-05T22:49:22+00:00",
        "amount": "100.00", #The amount of the order
        "payment_method": "invoice", #Valid payment methods are <invoice, free>
        "traffic_source": "youtube",
        "delivery_address": {
          "first_name": "Test",
          "last_name": "Tester",
          "street": "Testvägen",
          "street_number": 23,
          "staircase": "",
          "floor": "3",
          "apartment": "AS", #Can be used for the shorthand for apartment. For example AS.
          "apartment_number": "",
          "zip_code": "",
          "city": "",
          "care_of": "", #Can be used for the C/O part if applicable
          "citizenship_country_code": "SV",
          "company_crn": null,
          "company_department": null,
          "company_name": null,
          "company_reference": null,
          "company_vat_number": null,
          "contact_email": "user@email.com",
          "drop_box": null,
          "country_code": "",
          "mobile_number": "0501231234"
        }
    },
    # The payment object will be null when the payment method for the order is invoice. Currently gift campaigns can only be sold with payment methods invoice and free.
    "payment": {
            "id": "<payment_id>",
            "created": "2014-05-05T22:49:22+00:00",
            "amount": "0.00",
            "method": "free",
            "transaction_reference": null
    },
    "gift_subscription": {
        "created": "2014-05-05T22:49:22+00:00",
        "start_date": "2014-05-05T22:49:22+00:00",
        "payway_product_code": "<payway_product_code>",
        "title_code": "<title_code>",
        "external_package_id": "<payway_package_integration_code>", #The unique identifier of the package for the subscription for the package in the ESS
        "external_campaign_id": "<payway_campaign_integration_code>",#The unique identifier of the campaign for the subscription for the package in the ESS
        "period": "month",
        "period_length": 1,
        "campaign": <true|false>,
        "transition_to_package": <true|false>, #signals if the campaign will continue to normal package. Only valid if campaign=true
        "type": "<recurring|limited>" # only if package, if campaign = ""
    }
}

new_subscription_period

This event is emitted whenever a new subscription has been paid for in PW. The ESS must then update their subscription data with the new information regarding the new period and payment data.

{
    "event_name": "new_subscription_period",
    "timestamp": "2014-05-05T22:48:22+00:00",
    "account_id": "<payway account id>",
    "email": "<payway account email>",
    "customer_number": "<customer_number>",
    "birth_date":  "<birth date>",
    "company_registration_number": "<company registration number>", #empty string if not set,
    "company_name": "<company name>",
    "order": {
        "id": "<order id>",
        "order_reference": "ORGANISATION-123",
        "created": "2014-05-05T22:49:22+00:00",
        "amount": "100.00", #The amount of the order
        "payment_method": "creditcard",
        "specific_payment_method_name": "Card", #Only available when payment_method is adyen
        "specific_payment_method_type": "scheme", #Only available when payment_method is adyen
        "traffic_source": "youtube",
        "delivery_address": {
          "first_name": "Test",
          "last_name": "Tester",
          "street": "Testvägen",
          "street_number": 23,
          "staircase": "",
          "floor": "3",
          "apartment": "AS", #Can be used for the shorthand for apartment. For example AS.
          "apartment_number": "",
          "zip_code": "",
          "city": "",
          "care_of": "", #Can be used for the C/O part if applicable
          "citizenship_country_code": "SV",
          "company_crn": null,
          "company_department": null,
          "company_name": null,
          "company_reference": null,
          "company_vat_number": null,
          "contact_email": "user@email.com",
          "drop_box": null,
          "country_code": "",
          "mobile_number": "0501231234"
        }
    },
    "payment": {
        "id": "<payment_id>",
        "created": "2014-05-05T22:49:22+00:00",
        "amount": "100.00",
        "method": "creditcard",
        "specific_payment_method_name": "Card", #Only available when payment_method is adyen
        "specific_payment_method_type": "scheme", #Only available when payment_method is adyen
        "transaction_reference": "123456"
    },
    "subscription": {
        "id": "<subscription_id>",
        "subscription_number": "<subscription number>", #Subscription number identifying the subscription in the ESS
        "created": "2014-05-05T22:49:22+00:00",
        "start_date": "2014-05-05T22:49:22+00:00",
        "period_end": "2014-06-05T22:49:22+00:00",
        "payway_product_code": "<payway_product_code>",
        "title_code": "<title_code>",
        "external_package_id": "<payway_package_integration_code>", #The unique identifier of the package for the subscription for the package in the ESS
        "external_campaign_id": "<payway_campaign_integration_code>",#The unique identifier of the campaign for the subscription for the package in the ESS
        "period": "month",
        "period_length": 1,
        "campaign": <true|false>,
        "transition_to_package": <true|false>, #signals if the campaign will continue to normal package. Only valid if campaign=true
        "type": "<recurring|limited>" # only if package, if campaign = ""
    }
}

subscription_stopped

This event is emitted whenever a subscription, that PW controls, is deactivated. Note: This means that this event is emitted at the time of the deactivation of the subscription, and not at the time of the cancellation of the subscription. Further information regarding cancellation reasons.

{
    "event_name": "subscription_stopped",
    "timestamp": "2018-03-12T10:42:16+00:00",
    "account_id": "5aa659887f74882b15000001",
    "email": "user@email.com",
    "customer_number": "123456",
    "subscription": {
            "id": "<subscription_id>",
            "subscription_number": "<subscription number>", #Subscription number identifying the subscription in the ESS
            "created": "2018-03-12T10:42:16+00:00",
            "start_date": "2018-03-11T10:42:16+00:00",
            "period_end": "2018-03-13T10:42:16+00:00",
            "payway_product_code": "package_code",
            "period": "month",
            "period_length": 1,
            "external_package_id": "package_integration_code",
            "external_campaign_id": null,
            "campaign": false,
            "type": "recurring",
            "title_code": "TITLE_CODE"
    },
    "deactivation": {
            "reason": "expiration_passed", # The PW internal code for the reason of deactivation. Configured in PAP.
            "code": "01" # The integration_code, as a way to map this reason from PW to ESS. Configured in PAP.
    }
}

changed_subscription_renewal_date

This event is emitted when the renewal date of a PW-controlled subscription is changed. Read more here.

{
    "event_name": "changed_subscription_renewal_date",
    "timestamp": "2018-07-11T09:00:37+00:00",
    "account_id": "5b45c72909c04c219d000001",
    "email": "user@email.com",
    "customer_number": "123456",
    "subscription": {
        "id": "5b45c72909c04c219d000003",
        "subscription_number": "",
        "created": "2018-07-11T09:00:25+00:00",
        "start_date": "2018-07-10T09:00:25+00:00",
        "period_end": "2018-07-12T09:00:25+00:00",
        "payway_product_code": "package_code",
        "period": "month",
        "period_length": 1,
        "external_package_id": "package_integration_code",
        "external_campaign_id": null,
        "campaign": false,
        "type": "recurring",
        "title_code": "TITLE_CODE"
    },
    "renewal_date": "2018-07-12T12:00:25+03:00"
}

account_marketing_permission_changed

Release version: 3.7.8
This event is emitted when an account's marketing permissions are changed. This can occur when an account is created or when the user updates marketing permission settings from My account.
Read more on marketing permissions here.
{
  "event_name": "account_marketing_permission_changed",
  "timestamp": "2018-10-10T09:15:29+00:00",
  "account_id": "5bbdc33109c04ce0a7000001",
  "email": "user@email.com",
  "customer_number": "123456",
  "accepted_marketing_permissions": [
    {
      "id": "5bbdc33109c04ce0a7000003",
      "name": "Email permission",
      "type": "email",
      "description": null
    },
    {
      "id": "5bbdc33109c04ce0a7000004",
      "name": "Phone call permission",
      "type": "phone_call",
      "description": null
    }
  ]
}

account_changed

This event is emitted when a account is changed via the "My account" page in PCP, by an administrator using the PAP or via the Payway APIs.

{
  "event_name": "account_changed",
  "timestamp": "2020-03-24T10:41:20+00:00",
  "account_id": "5e79e3d06e9552b5d58e4976",
  "email": "user@email.com",
  "customer_number": "123456",
  "customer":
    {
      "contact_email": "user@email.com",
      "customer_number": "123456",
      "first_name": "john",
      "last_name": "doe",
      "phone_number": "0701231234",
      "ssn": "12341234-0000",
      "crn": "321321-0000",
      "company_name": "acme",
      "birth_date": "2000-03-24",
      "address": {
          "first_name": "Test",
          "last_name": "Tester",
          "street": "Testvägen",
          "street_number": 23,
          "staircase": "",
          "floor": "3",
          "apartment": "AS", #Can be used for the shorthand for apartment. For example AS.
          "apartment_number": "",
          "zip_code": "",
          "city": "",
          "care_of": "", #Can be used for the C/O part if applicable
          "citizenship_country_code": "SV",
          "company_crn": null,
          "company_department": null,
          "company_name": null,
          "company_reference": null,
          "company_vat_number": null,
          "contact_email": "user@email.com",
          "drop_box": null,
          "country_code": "",
          "mobile_number": "0501231234"
      }
    }
}

account_activated

This event is emitted when a customer activates their account using the activation form in PCP or when a account activation is done using the Payway APIs.

{
  "event_name": "account_activated",
  "timestamp": "2020-03-24T10:41:20+00:00",
  "account_id": "5e79e3d06e9552b5d58e4976",
  "email": "user@email.com",
  "customer_number": "123456",
  "customer":
    {
      "contact_email": "user@email.com",
      "customer_number": "123456",
      "first_name": "john",
      "last_name": "doe",
      "phone_number": "0701231234",
      "ssn": "12341234-0000",
      "crn": "321321-0000",
      "company_name": "acme",
      "birth_date": "2000-03-24",
      "address": {
        "first_name": "Test",
        "last_name": "Tester",
        "street": "Testvägen",
        "street_number": 23,
        "staircase": "",
        "floor": "3",
        "apartment": "AS", #Can be used for the shorthand for apartment. For example AS.
        "apartment_number": "",
        "zip_code": "",
        "city": "",
        "care_of": "", #Can be used for the C/O part if applicable
        "citizenship_country_code": "SV",
        "company_crn": null,
        "company_department": null,
        "company_name": null,
        "company_reference": null,
        "company_vat_number": null,
        "contact_email": "user@email.com",
        "drop_box": null,
        "country_code": "",
        "mobile_number": "0501231234"
      }
    }
}

new_customer

This event is emitted when a new account is registered.

{
  "event_name":"new_customer",
  "timestamp":"2023-11-07T06:41:20+00:00",
  "account_id":"6549dc106e95526cbedbbc8e",
  "email":"user@email.com",
  "customer_number":"123456",
  "created_from_source":"CREATED_FROM_SOURCE",
  "customer":
    {
      "contact_email":"user@email.com",
      "customer_number":"123456",
      "first_name":"john",
      "last_name":"doe",
      "phone_number":"0701231234",
      "ssn":"12341234-0000",
      "crn":"321321-0000",
      "company_name":"acme",
      "birth_date":"2003-11-07",
      "address": {
        "first_name": "Test",
        "last_name": "Tester",
        "street": "Testvägen",
        "street_number": 23,
        "staircase": "",
        "floor": "3",
        "apartment": "AS", #Can be used for the shorthand for apartment. For example AS.
        "apartment_number": "",
        "zip_code": "",
        "city": "",
        "care_of": "", #Can be used for the C/O part if applicable
        "citizenship_country_code": "SV",
        "company_crn": null,
        "company_department": null,
        "company_name": null,
        "company_reference": null,
        "company_vat_number": null,
        "contact_email": "user@email.com",
        "drop_box": null,
        "country_code": "",
        "mobile_number": "0501231234"
      }
    }
}

Callbacks

PW provides a Subscription System API that can be used to perform specific tasks that are necessary when integrating an ESS.

Interfaces

These interfaces describe what kind of data each type of object that the ESS exposes must have. The closer to the interfaces the easier the PW-integration. Additionally, not all subscription systems can support all fields which can mean that not all functionality in PW can be supported.

Customer

Field Name Type(max length) Description
customer_number string(100) The unique identifier for this customer
first_name string(100)
last_name string(100)
contact_email string(100)
mobile_number string(100) in format 0404603839 or +358404603839
address Address object. Description of the address object below. Some fields in the address are marked as mandatory indicating that the must be supplied if a address object is supplied.

Address

Field Name Type (max length) Required Description
first_name String (100) Required First name
last_name String (100) Required Last name
street String (200) Required Street name
street_number String (10) Optional The street number, some subscription-systems only allow numerical values
zip_code String (6) Required The zipcode
floor String (10) Optional The floor
apartment_number String (5) Optional The apartment number
entrance String (6) Optional The entrance
city String (100) Required The city
dropbox String (5) Optional Dropbox
country_code String (2) Required Country code: SE, FI or AX

Subscription

Field Name Type(max length) Description
subscription_number string(100) The identifier for this subscription, unique for a given customer number. This is used to map a PW subscription to a external subscription
state active OR inactive The current state of the subscription
payment_method creditcard, invoice, directdebit, autogiro, sms, free If creditcard, directdebit, sms or free PW is the owner of the subscription and handles the payments
subscription_type limited or recurring recurring means subscription will be renewed, limited means it will only be active until the end date
start_date datetime The start date of the subscription in UTC
end_date datetime The end date of the subscription in UTC
external_package_id string(100) The unique identifier of the package for the subscription. This should match the integration code that has been set on the PW package
external_campaign_id string(100) The unique identifier of the campaign if subscription is for campaign, otherwise NULL. This should match the integration code on the PW campaign

Debt

Field Name Type(max length) Description
customer_number string(100) The unique identifier for this customer
has_debt string(true or false) Does this customer have outstanding payments that should hinder purchasing gifts

Possible subscription start dates

Field Name Type Description
start_dates Array of dates The possible start dates for the package or campaign, dates must be in the format YYYY-MM-DD (ISO 8601). I.e. ['2021-12-01,...'2021-12-12']

Scenarios

These are the different scenarios that the ESS integration can deal with.

Activate account

This allows a customer that has a subscription in the ESS to activate (create) his digital account from the data supplied by the ESS. The customer does so by doing a lookup using his customer number and zip code.

If a customer is found using the customer number and zip code he will be presented with the customer data from the ESS where he can complete or change the customer data before creating a digital account. You may control which fields are shown and required using the activation field configuration.

When the digital account has been created, PW performs a Subscriptions synchronization to ensure that the customer has digital access to his subscriptions.

When a customer has activated their account the event account_activated is published. This information can be used to gather the customers that has gone through the activation procedure for further processing and for updating the customers personal information in the ESS.

Account Activation

Purchase by existing customer

This scenario allows a purchase made in PW to be exported to the Subscription System along with the information about what product has been purchased. This is applicable for when an account with a customer number makes a purchase.

When an order in PW has been closed and payment is processed the new_subscription event is published to interested parties. When this event has fired there will be an active subscription in PW. When the ESS has processed the new_subscription event it calls an API endpoint and sets the subscription number on the subscription in PW.

Purchase By Existing Customer

  • ESS must supply an endpoint that can receive the new_subscription event.
  • ESS must be able to assign a unique subscription number to the new subscription.
  • ESS must be able to call the subscription_number API endpoint to assign the subscription number to the new subscription owned by the PW Account.

Problem situations

ESS cannot assign a subscription number

If the ESS does not assign a subscription number for a subscription this will have the following implications:

  • Subscription paid by invoice: The subscription will remain active until the next sync of the account when the subscription will be deactivated. Note that a account without customer number cannot be synchronized and thus such an accounts will have a unpaid subscription remaining active in Payway.
  • Payments of subscription is handled by Payway: The subscription lifecycle is handled by Payway and will not be affected by the lack of a subscription number.

Purchase by new customer

This scenario allows a purchase made in PW to be exported to the ESS along with the information about what product has been purchased. This is applicable to when an account without a customer number (usually a newly registered account) makes a purchase.

When an order in PW has been closed and payment is processed the new_subscription event is published to interested parties. When this event has fired there will be an active subscription in PW. Significant to this event is that the customer_number field is blank. This means that there is no connection between the account in PW and a customer in ESS. When the ESS has processed the new_subscription event (and most likely created a new customer in the ESS, alternatively identified an existing customer to place the order for) it calls an API endpoint and sets the new customer number on the account in PW, secondly it calls an API endpoint to set the subscription number on the subscription in PW.

Purchase By New Customer

  • ESS must supply an endpoint that can receive the new_subscription event.
  • ESS must be able to assign a unique customer number to a customer in the ESS
  • ESS must be able to call the customer_number API endpoint to assign a customer number to an account in PW
  • ESS must be able to assign a unique subscription number to the new subscription.
  • ESS must be able to call the subscription_number API endpoint to assign the subscription number to the new subscription owned by the PW Account

Problem situations

ESS cannot assign customer number

Note

A customer with a subscription that is not managed by PW must be assigned a customer number

If ESS does not assign a customer number for a new customer then that customers subscriptions cannot be synchronized. This will in turn have implications for the ordered subscription, see ESS cannot assign a subscription number.

Situations like this can be handled by i.e. setting up the customer manually in the subscription system and adding the customer number to the account via PAP or have the customer number assigned via the API endpoint for assigning customer_number.

Purchase of gift campaign by existing customer

This scenario allows for a existing customer to buy a campaign as a gift for another person.

Purchase of gift

When a customer that is logged in visits the purchase page for gifts, it's validated that the customer have a customer number. An additional validation that the customer does not have debt can be done, however this is not mandatory and does not need to be implemented if not needed.

Validation of gift giver

When the customer has filled out the form, specifying the receivers name and address, validation is done on the receiver aswell. The receiver is located in the ESS by the email address supplied by the giver of the gift. If no match is made by email address, an attempt to locate the receiver will be made using firstname, lastname, street and zip-code. In the case that no customer matching these criteria is found, the receiver is valid to receive the gift. When a customer is found matching either of the above mentioned criteria, a check is made to determine if the receiver already have a active subscription on the title being given. A receiver with an active subscription on the same title as the gift is not valid to receive the gift.

Validation of gift receiver

  • ESS can supply an API endpoint that returns a Debt interface based on a customer number. This is not required for implementing purchases of gifts.
  • ESS must supply an API endpoint that returns a Customer result based on a email address or first name, last name, street and zip_code.
  • ESS must supply an endpoint that can receive the new_gift_subscription event.

New subscription period

This scenario allows for a new subscription period to be exported from PW to the ESS. When PW has processed the payment for a new subscription period the new_subscription_period event is published. When this event has fired the subscription is renewed for the next period and the ESS must update its' subcription and related payment data.

New Subscription Period

Subscription being deactivated

This scenario is what happens when a PW controlled subscription is stopped. Some examples on why this might happen:

  • Payment error, such as the credit card not covering the charges.
  • Subscription being cancelled by either the customer or customer service.
  • Subscription period is ended and its a limited subscription without automatic renewal.

When the subscription is deactivated PW will emit a subscription_stopped event that the ESS can react upon. Included in the event will be data about the deactivation neccessary to map the deactivation reason to deactivation reasons in the ESS.

Synchronize Subscriptions

This scenario allows the ESS to synchronize the customers PW account when there has been a change to the readers' subscription/s in the ESS. This applies to subscriptions owned/controlled by the ESS, not subscriptions that are owned/controlled by PW.

When a change has happened in the subscriptions for a given customer number you may call the sync_customer_subscriptions method in the API to trigger a sync.

Another way to trigger this synchronization is to add a customer number to an account using the Payway Administration Portal (PAP). A common way to synchronize a customers account is to remove their customer number in PAP and then add it again, using this as a way for a Customer Service Representative to force a synchronization of the subscriptions for a given customer.

When a synchronization happens PW will poll the ESS, asking for all subscriptions given the customer number used for the synchronization operation. Using the subscriptions supplied from the ESS PW will then first go through this process:

Sync Active/Stopped Subscriptions

After processing all the subscriptions that the ESS reports having, PW will process all active subscriptions in PW controlled by the ESS, and deactivate any subscription not having a corresponding subscription in the ESS. This is neccessary because some ESSs will not report anything about a stopped subscription. This will also make sure that there are no lingering subscriptions in PW, allowing customers access when they are no longer privileged.

If a subscription has been bought through PW recently (within 7 days), it might be the case that the subscription not yet has been established in the ESS, therefore PW will not deactive it. Consider this as a grace period to allow for the ESS to establish the subscription.

Sync Active/Stopped Subscriptions

Create Subscription

This operation will create a new subscription in PW. The new subscription will be a subscription on the Package/Campaign identified by mapping the external_package_id on the subscription to the integration_code on a Package/Campaign in PW. The subscription_number will be set on the subscription as an identifying key. The subscription will be activated and the Sync Attributes operation will run to synchronize the subscription data.

Sync Attributes

This operation will synchronize data on the PW subscription to match data from the subscription in the ESS.

data Description
subscription_type Optional. Will be used if the Subscription interface implements it.
valid_from Will update the valid_from date on the PW subscription to match the date from the ESS.
valid_to Will update the valid_to date on the PW subscription to match the date from the ESS.

Change Ownership

This operation changes the ownership from PW to the ESS. This is usually what happens if a PW controlled subscription, paid by credit card, is changed in the ESS to be paid by invoice.

This is usually only a valid scenario when a subscription has been frozen due to outstanding credit card payments and a customer service representative has changed the payment option in the ESS to invoice instead as a way to keep the subscription running.

This can only happen if the subscription in PW is deactivated.

The subscription in PW will have subscription_number removed and a new subscription will be created. The new subscription will be controlled by the ESS and have the subscription_number set.

Transition Subscription

This operation changes what Package/Campaign the subscription is associated with. The current PW subscription will be deactivated and its subscription_number removed. A new subscription matching the new Package/Campaign will be created.

Activate Subscription

This operation will activate a stopped subscription and then run the Sync Attributes operation to sync the subscription data.

Deactivate Subscription

This operation will stop a PW subscription aswell as setting the valid_to date to match the end date on the subscription in the ESS.

Marketing permissions changed for account

When an account is created from activation, registration or a purchase the event account_marketing_permission_changed is published.

Also when the user edits marketing permissions from "My account" the same account_marketing_permission_changed event is published.

An account is changed

When an account is changed from PCP,PAP or the Payway APIs the event account_changed is published. This information can be used to update personal information in the ESS.

Future start date

Payway offers the possibility for customers to make purchases with a future start date. With this customers can be allowed to purchase a follow up subscription before the current subscription has ended. Without this customers with a active subscription in Payway are not allowed to make purchases on the same package.

To support this feature ESS must provide an endpoint that

  • Accepts parameters external_package_id, external_campaign_id, from_date, to_date. Paramers are described in the table below.
  • Determines the possible start dates
  • Responds with the Possible subscription start dates

Parameters

Name Format Description
external_package_id string(100) The unique identifier of the package for the subscription. This should match the integration code that has been set on the PW package.
external_campaign_id string(100) The unique identifier of the campaign if subscription is for campaign, otherwise NULL. This should match the integration code on the PW campaign.
from_date string(ISO-8601 YYYY-MM-DD) Start of the date range requested, possible start dates prior to this date should not be returned.
to_date string(ISO-8601 YYYY-MM-DD) End of the date range requested, possible start dates after this date should not be returned.

Package mappings

The external_package_id in the the subscription interface determines the package of the customer's subscription in PW. The external_package_id must have been configured in PAP by setting the integration code on the package. If not set, the subscription will not be mapped to the account in PW. Your application can find out which packages and campaigns that are mapped.

package mapping