Last update 5/09/2018

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 Ingenico ePayments 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 Ingenico ePayments, 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.

    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, Ingenico ePayments 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

    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. Via e-Commerce and DirectLink

    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.

    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 Description Format
    SUBSCRIPTION_ID Unique identifier of the subscription. The subscription ID must be assigned dynamically. AN, 50
    SUB_AMOUNT







    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. N
    SUB_COM Order Description AN, 100
    SUB_ORDERID OrderID for subscription payments AN, 40
    SUB_PERIOD_UNIT "d" = daily







    "ww" = weekly







    "m" = monthly
    AN, 2
    SUB_PERIOD_NUMBER Interval between each occurrence of the subscription payments. N
    SUB_PERIOD_MOMENT







    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)
    N
    SUB_STARTDATE Subscription start date Date
    SUB_ENDDATE Subscription end date Date
    SUB_STATUS 0 = inactive







    1 = active
    AN, 1
    SUB_COMMENT Comment for merchant AN, 200
    CN

    Cardholder name

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

    AN, 35









    • 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) Description Format
    1 OPERATION* ADDSUBS (Add Subscription)
    DELSUBS (Delete Subscription)
    AN, 8
    2 CN* Cardholder name AN, 35
    3 ACC_CARDNO* Card or Bank account number AN, 23
    4 EXPDATE* Expiry date (if applicable) AN, 4
    5 BRAND* Brand of the payment method AN, 25
    6 PSPID* Merchant identifier in our system AN, 30
    7 SUBSCRIPTION_ID* Unique identifier of the subscription AN, 50
    8 AMOUNT* Amount of the subscription, multiplied by 100 (as the format of the amount can't contain any decimals or other separators). N
    9 CURRENCY* Currency (3-digit ISO format) AN, 3
    10 PERIODICITY_UNIT* ‘d’ = daily
    ‘ww’ = weekly
    ‘m’ = monthly
    AN, 2
    11 PERIODICITY_NUMBER* Interval between each occurrence of the subscription payments. N
    12 PERIODICITY_MOMENT* Depending on field 10
    Daily (d): interval in days
    Weekly (ww): 1=Sunday, … 7=Saturday
    Monthly (m): day of the month
    N
    13 SUBSCRIPTION_STATUS* 0 – Inactive
    1 – Active
    N
    14 START_DATE* Start and end dates. Note that the date format should be yyyy-MM-dd

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

    Date
    15 END_DATE Date
    16 EXTERNALREF_PATTERN

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

    Ex: subscription 123 [MM-YYYY]

    AN, 40
    17 COMDESC_PATTERN

    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]

    AN, 100
    18 (empty)
    19 BUYER_EMAIL Email address AN, 50
    20 BUYER_TELNO Telephone number AN, 50
    21 COMMENT Free text comment AN, 200

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

    This website uses cookies to be able to give you the best user experience. If you don't want to accept these cookies, we allow you to change the cookie settings. Click 'Accept' to allow all cookies from this website.

    Cookie settings

    Introduction

    Functional

    Functional cookies are required for the website to operate correctly. These cookies cannot be disabled.

    Optimized

    Optimization cookies allow us to analyze site usage so we can measure and improve our website.
    This is the default level.

    Personalized

    Personalization cookies are used for social media and advanced personalization. They allow us to show you information related to your company.


    Example functionality allowed

    • Store country preference
    • Store language preference

    Example functionality not allowed

    • Saving personal data
    • Anonymous tracking via Google Analytics
    • Tracking for remarketing purposes

    Example functionality allowed

    • Store country preference
    • Store language preference
    • Anonymous tracking via Google Analytics

    Example functionality not allowed

    • Saving personal data
    • Tracking for remarketing purposes

    Example functionality allowed

    • Store country preference
    • Store language preference
    • Anonymous tracking via Google Analytics
    • Serve content relevant to your interests
    • Serve ads relevant to your interests
    • Tracking for remarketing purposes

    Example functionality not allowed

    • Saving personal data