Skip to content

Subscription System integration

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

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.

Specific Events

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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
{
    "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>",
    "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",
        "traffic_source": "youtube",
        "delivery_address": {
            "first_name": "Test",
            "last_name": "Tester",
            "street": "Testvägen",
            "street_number": 23,
            "staircase": "",
            "apartment_number": "",
            "zip_code": "",
            "city": "",
            "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",
        "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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
{
    "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": "",
            "apartment_number": "",
            "zip_code": "",
            "city": "",
            "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": "",
            "apartment_number": "",
            "zip_code": "",
            "city": "",
            "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": nil
    },
    "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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
{
    "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>",
    "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",
        "traffic_source": "youtube",
        "delivery_address": {
            "first_name": "Test",
            "last_name": "Tester",
            "street": "Testvägen",
            "street_number": 23,
            "staircase": "",
            "apartment_number": "",
            "zip_code": "",
            "city": "",
            "country_code": "",
            "mobile_number": "0501231234"
        }
    },
    "payment": {
        "id": "<payment_id>",
        "created": "2014-05-05T22:49:22+00:00",
        "amount": "100.00",
        "method": "creditcard",
        "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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "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

1
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.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "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
    }
  ]
}

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 TBA set this field if you want to pre populate the address on the PW account. Must adhere to PW address validation rules. Link to address validation rules to be inserted later

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 nil. 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

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.

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.

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 mostdfdd 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

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.

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