1. Home
  2. Integration Solutions
  3. Recurring Payments
  4. Subscription Manager

Subscription Manager

1. Introduction

The Subscription Manager allows you to create and store recurring payments in advance, based on a date interval and a recurrence rate.

A typical application would be a magazine subscription, for which the customer has to pay the same amount every month until he cancels it.

The subscription payment can be created in several ways:

  • Manually in your Viveum account
  • Via transaction creation in eCommerce, DirectLink or Batch

2. In the back office

Clicking the “Subscription” item via "Advanced" in your account menu will take you to the "Subscription management" dashboard, which is divided into the following parts:

  • "Subscription status" (default page) shows an overview of your current subscriptions. Clicking on the number of subscriptions corresponding to a given status will display the list of subscriptions.
  • "Global parameters" allows you to configure your subscription manager options.
  • "Edit/View subscriptions" allows you to search for, view and edit any subscription you may have stored in your account. It is also possible, instead of viewing via the browser, to download a list of subscriptions in a text file.
  • "Create subscription" allows you to create new subscriptions manually.

2.1 Configuration

In the “Global Parameters” tab, you can define the following settings:

  • "Number of retries when a payment fails". It is possible that one of the payments has an error. Our system will retry for as many times as is configured here (max. 5). The interval between each retry is one day.
  • "What to do when the maximum number of retries has been reached".
    • If you choose to deactivate a subscription, no further payments will be made for it.
    • If you choose to proceed with the next occurrence as defined in the subscription, the next payment will be made at the next occurrence.
    • In both cases, the failed payment will remain unsettled after the maximum number of retries has been reached. In the event that a payment failed after the maximum number of retries has been reached, a notification will be sent to the email address configured in the “Transaction emails” tab on the “Technical information" page of your account.
  • "Disclaimer" (e-Commerce only) defines whether or not to display a message requesting the buyer’s consent to the storage of his payment data and the future subscription payments. If you do not wish to use the default disclaimer provided by Viveum, we strongly recommend you to request the buyer’s consent to the storage of his payment data and the future subscription payments on your side.

2.2 Create a subscription

In order to create a subscription, you must provide the following information:

Field Description
Subscription ID A unique identifier for the subscription. This is not an OrderID, as each occurrence of the subscription will be a separate payment.
Name/email/phone Card/account holder’s information

Credit Card

Direct Debits

The payment method, and subsequent account or card information.

Note: Direct Debits DE subscriptions can not be created with IBAN account information; Konto/BLZ must be used instead. Direct Debits NL is not supported.

Recurrence

You can choose between daily, weekly or monthly. For each choice, you can fine-tune the recurrence (for weekly, you can choose the day of the week, for monthly, you can choose the day of the month.)

If you wish to have a recurrence every few days, you must choose “Daily” and then set the required number of days.
The same rule is valid for weeks and months, e.g. if the recurrence should be the fifth of every two months, you put Recurrence on "Monthly", and Payment occurs on the "5" of every "2" month(s).

Note:
- When the day of the month for the subscription is greater than the available number of days in the current month (e.g. there is no February 30th), the subscription will use the last available day of the month instead.
- If you create a subscription with a Start date in the past, we will change the Start date to a future date, based on any of the values you entered with Recurrence (see above).
Start date / End date

Date range of the subscription.

If the date of the last payment of the subscription is on the exact date of the end date, the payment will be processed.

To ensure an optimum processing of all subsequent payments, we recommend you not to modify the Start date after at least one payment has been processed.
OrderID Order identifier that will be included in each payment of the subscription. Clicking the “add dd/MM/yyyy” button will include the date in the OrderID, so as to easily differentiate each subscription payment.
COM Order description included in each subscription payment. Clicking the “add dd/MM/yyyy” button will include the date in the COM-field, in order to easily differentiate each subscription payment.
Comment Free text to store a comment for the merchant
Status Setting the subscription to “active” will trigger payments as configured.

When creating a subscription, no verification of the credit card takes place. The validity of the card will be verified with the first subscription payment.

2.3 Edit a subscription

The screen for editing a subscription proposes the same features as for creation.

All fields are subject to change, except for the Subscription ID. If the customer’s card expires, it can be updated or changed and the subscription does not need to be recreated.

Please note, if you edit the payment dates relating to a Subscription, Viveum may process a "catch up" payment to cover any transactions that may have otherwise been missed as a consequence of the change.

For example:

  • Week 1 – Subscription created to be processed every Wednesday. First transaction is processed on that Wednesday
  • Week 2 – Subscription edited on Tuesday to change the day of processing to Monday
  • Week 3 – Subscription processed on Monday

IMPORTANT! Avoid daylight saving discrepancy between users and PSPID

  • When editing subscriptions, please make sure to adapt your user’s daylight saving settings to the setting of the PSPID
  • Otherwise, due payments might not be triggered for modified subscriptions on this PSPID
  • To change the setting of your user, go to Configuration > Users > EDIT on your user > (De-)flag “Automatically adjust to daylight settings”
  • To change the setting of the PSPID, go to Configuration > Account > Your administrative details > (De-)flag “Automatically adjust to daylight settings"

2.4 Delete a subscription

In order to delete a subscription, you need to look it up via the “Edit/View subscriptions” link, and click on the “delete” button next to the corresponding subscription.

Deleting a subscription only deletes the scheduling, and does not refund or cancel any ongoing payments.

2.5 View transactions

Each subscription transaction is a separate payment, with its own PAYID and status. You can look them up via the “View transactions” link in the back office.

If you wish to view all subscription transactions, it is easier to look them up via the subscription manager, by supplying the subscription ID (only the last 12 transactions will be visible).

3.1 Input

In order to create a subscription via e-Commerce or DirectLink, an initial transaction must be performed. In case of e-Commerce, if the initial transaction is not successful the subscription will not be created. Please note that subscription creation via DirectLink requires processing the initial transaction without 3D Secure.

Tip: If you do not wish to perform an actual transaction at the time of the subscription creation, you may submit an amount of €0, which will then only validate the card; the transaction will not be submitted to the acquirer.

The following data must be sent along with the transaction in order to create a subscription:

Field / Format Description

SUBSCRIPTION_ID

AN, 50

 Unique identifier of the subscription. The subscription ID must be assigned dynamically.
SUB_AMOUNT
N






 Amount of the subscription (can be different from the amount of the original transaction) multiplied by 100, as the format of the amount must not contain any decimals or other separators.

SUB_COM

AN, 100

 Order Description

SUB_ORDERID

AN, 40

 OrderID for subscription payments

SUB_PERIOD_UNIT

AN, 2

 "d" = daily

"ww" = weekly

"m" = monthly

SUB_PERIOD_NUMBER

N

 Interval between each occurrence of the subscription payments.

SUB_PERIOD_MOMENT
N

 Depending on SUB_PERIOD_UNIT (not applicable for "daily" (d) as here the moment is equal to the unit)

  • Weekly (ww): 1=Sunday, … 7=Saturday
  • Monthly (m): day of the month (1-31)

SUB_STARTDATE

Date

 Subscription start date

Format: yyyy-mm-dd or dd/mm/yyyy

SUB_ENDDATE

Date

 Subscription end date

SUB_STATUS

AN, 1

 0 = inactive

1 = active

SUB_COMMENT

AN, 200

 Comment for merchant

CN

AN, 35

Cardholder name

Must be sent in DirectLink request / default field on e-Commerce payment page.



  • Remember to include these fields in your SHA calculation. For more info on SHA, go to e-commerce or DirectLink documentation.
  • The subscription payments will only be executed once the subscription status is “active”. The subscription status does not change automatically to active at the start date defined in the subscription.

If the EMAIL and OWNERTELNO fields are completed with the order, they will also be added to the subscription.

Note: Subscription payments will always be processed as direct sales. However, when using e-Commerce, the first transaction will be processed as configured in the Technical information page of your account.

3.2 Feedback

The following parameters will be returned in the post-sale feedback:

Field Description
subscription_id confirmation of the unique subscription identifier
creation_status Indicates whether the subscription was created successfully. Possible values: “OK” or “ERROR”.




Important

  • For the first transaction, the feedback is returned with the online post-sale server-to-server feedback. For every subsequent transaction, the feedback is returned with the offline post-sale feedback. For more info, go to Server-to-server feedback (post-payment).
  • Remember to include these fields in your SHA-OUT calculation. For more info on SHA, go to e-Commerce or DirectLink documentation.

4. Via Batch

The following fields should be submitted for batch subscription operations:

# / Field (*=Required) / Format Description

1 / OPERATION*

AN, 8

 ADDSUBS (Add Subscription)
DELSUBS (Delete Subscription)

2 / CN*

AN, 35

 Cardholder name

3 / ACC_CARDNO*

AN, 23

 Card or Bank account number

4 / EXPDATE*

AN, 4

 Expiry date (if applicable)

5 / BRAND*

AN, 25

 Brand of the payment method

6 / PSPID*

AN, 30

 Merchant identifier in our system

7 / SUBSCRIPTION_ID*

AN,50

 Unique identifier of the subscription

8 / AMOUNT*

N

 Amount of the subscription, multiplied by 100 (as the format of the amount can't contain any decimals or other separators).

9 / CURRENCY*

AN, 3

 Currency (3-digit ISO format)

10 / PERIODICITY_UNIT*

AN, 2

 ‘d’ = daily
‘ww’ = weekly
‘m’ = monthly

11 / PERIODICITY_NUMBER*

N

 Interval between each occurrence of the subscription payments.
12 / PERIODICITY_MOMENT* Depending on field 10
Daily (d): interval in days
Weekly (ww): 1=Sunday, … 7=Saturday
Monthly (m): day of the month

13 / SUBSCRIPTION_STATUS*

N

 0 – Inactive
1 – Active

14 / START_DATE*

Date

 Start and end dates. Note that the date format should be DD-MM-YYYY

All dates are converted with the user's time zone, e.g. if the START_DATE is 01/05/2020 and the user is set to GMT–1, the date/time will be converted to 01/05/2020 1:00:00 (CET).

15 / END_DATE

Date

16 / EXTERNALREF_PATTERN

AN, 40

Payment reference. You can include date patterns that will be replaced with the actual values on the payment date.

Ex: subscription 123 [MM-YYYY]

17 / COMDESC_PATTERN

AN, 100

Order description. Here you may also use date patterns, which will be replaced with their values at the time of each payment.

e.g. Your magazine [YYYYddd]
18 / (empty)

19 / BUYER_EMAIL

AN, 50

 Email address

20 / BUYER_TELNO

AN, 50

 Telephone number

21 / COMMENT

AN, 200

 Free text comment

  • The file should be an ASCII text file
  • The file should only contain one line per subscription. The lines are separated by the Carriage Return and Line Feed characters (ASCII :13 10 – HEX : 0xD 0xA)
  • The fields must be separated by a semicolon (“;”)
  • The fields themselves cannot contain any semicolons (“;”)

Example of a VISA Subscription:
ADDSUBS;John Doe;4111111111111111;1012;VISA;PSPID;ID001;100;EUR;d;1;1;1;2010-08-13;2011-08-13;Cotisation [MM-YYYY];Paiement n° [YYYYddd];;Bill.smith@yahooyahoo.com;0000000000;comment on this subs;

Example of a Direct Debit Subscription:
ADDSUBS;John Doe;XXXXXXXXXBLZXXXXXXXX;;DIRECT DEBITS DE;PSPID;ID002;100;EUR;d;1;1;1;2010-04-20;2010-05-15 00:00:00.000;Cotisation [MM-YYYY];Paiement n° [YYYYddd];;Bill.smith@yahooyahoo.com;0000000000;comment on this subs;

Note: if you copy/paste these example lines to conduct a test on your test account, please ensure you replace the PSPID and account numbers.

For more information, go to Batch.