Subscriptions/Recurring | Qliro devportal

For developers

By Qliro

Select search filters:

Subscriptions/Recurring

Enable recurring orders by allowing you to create orders without Customer on site

Overview

The initial purchase is created when the customer completes the purchase in the checkout as usual. Subsequent purchases are done without customer participation and are initiated using our Admin API.

Supported payment methods

Qliro Invoice
Credit card

Invoices can be set to be sent via email or by mail if letter invoice is selected. Subscription by cards is made possible by using a unique token that is created with the first purchase. For card subscriptions, masked card details can be displayed and managed from the subscription pages on your site. Additional cards may also be added by using the new card registration form, which is a card form rendered in a Qliro-managed iframe.

Note: This feature requires you as a merchant to manage the subscription logic meanwhile this feature enables you to initiate a payment regularly without the customer needing to be present.

How-to

In the ‘Create Order’ call for the initial purchase, the subscription item(s) should be tagged by adding metadata tags under each item. The order creation is handled in the same way for a recurring order as for a non-recurring order. Qliro will for credit card orders register a token.

For cards, a merchantSavedCreditCardPushURL should be provided in the Create order call as a URL to receive credit card token and card details

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
{
  "MerchantReference": "MerchantUniqueReference",
  "MerchantApiKey": "MERCHANTKEY",
  "Currency": "SEK",
  "Country": "SE",
  "Language": "sv-se",
  "MerchantConfirmationUrl": "http://Merchant.com/confirmation/",
  "MerchantTermsUrl": "http://Merchant.com/terms/",
  "PrimaryColor": "#00FF00",
  "CallToActionColor": "#0000FF",
  "OrderItems": [
    {
      "MerchantReference": "XXX",
      "Description": "ZZZ",
      "Quantity": "4",
      "PricePerItemIncVat": "450",
      "PricePerItemExVat": "450",
      "Metadata": {
        "Subscription": {
          "Enabled": true
        }
      }
    }
  ]
}

Retreiving order information

After the customer completes the purchase you will receive a status notification on merchantOrderManagmentUrl and if the card was used by the customer, card information notification will be sent to merchantSavedCreditCardPushURL. The notifications will come asynchronously and will be connected to the same orderId. For more information please go to Notifications.

The card details can be used to:

Display which cards are linked to the subscription as well as the expiry date of cards on a subscription management page.
Track the expiry date of the card to send a reminder to register a new card as expiration approaches.

Masked card data is also provided in the GetOrder response if the order was placed with CreditCard as the payment method. Card transaction processing and token registration are two separate operations. Since MerchantSavedCreditCard may not be available directly after payment completion, Qliro’s recommendation is for merchants to provide a MerchantSavedCreditCardPushUrl which can be used to register credit card token on the merchant side as soon as they become available.

Card details in GetOrder Response

1
2
3
4
5
6
7
8
9
10
11
{
  "MerchantSavedCreditCard": {
    "Id": "3d2092a6-7baf-49e3-bd34-d0d0d85744b5",
    "BrandName": "VISA",
    "ExpiryYear": 24,
    "ExpiryMonth": 12,
    "Bin": 346596,
    "Last4Digits": 1234,
    "MaskedNumber": "346596XXXXXX1234"
  }
}

Initiate recurring order

When the next order on the same subscription should be shipped MerchantPayment is to be used to initiate a new payment on behalf of the customer. This order can thereafter be processed the same way as other orders, MarkItemsAsShipped, ReturnWithItems etc.

For details on the request/response parameters as well as error codes, please continue to the API reference.

Managing Subscriptions – Adding a new card

In order to be able to add cards to an existing subscription, Qliro checkout provides an endpoint on the Merchant API that provides the possibility to return an HTML snippet on your site that renders a card form enabling the capture of card details while following PCI-DSS. This request will work similar to CreateOrder HTML snippet population.

For details on the request/response parameters as well as error codes, please continue to the API reference.

When the HTML snippet from the CreateMerchantSavedCreditCard response is deployed, a frontend communication endpoint will be defined through the variable qccf in the global scope of the browser window.

To make sure the API is loaded before registering listeners, define a function qccfReady in the global scope and add all listeners inside of its body. The function will be invoked when the Qliro Credit Card Form front end API has been setup.

If the MerchantConfirmationUrl is not specified when creating the order, then there will be no redirection after the new creditcard has been added. In this case, the ‘Credit Card Created’ listener can be used to understand if the customer tried to add a creditcard.

Implementation Example

1
2
3
window.qccfReady = function(q1) {
qccf.onCreditCardCreated(creditCardCreatedListener);
}

When customer will complete new credit card registration and payment become successful redirections will be performed to merchant specified MerchantConfirmationUrl. Note new credit card token registration can take time depends of credit card provider. Merchant will be notified about new merchant credit card details by push notification to MerchantSavedCreditCardPushUrl.

Next up is B2B