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

ESS must supply an API endpoint that returns a Customer result based on customer number and zip code query
Synchronize Subscriptions must be supported.
ESS can supply an endpoint that can receive the event account_activated

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

ESS must supply an endpoint that can receive the new_subscription_period event.

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