Integration Journey

The Subscription Module allows SmartPay integrators to create and manage complex subscriptions, plans, monitor charges and automated payments.

Authentication

info

Subscription supports strong API authentication.

In order to authenticate within the SmartPay APIs, you will need to provide the standard "Authorization" header in every request. SmartPay supports the Basic authentication scheme in accordance with RFC standard.

The value to be passed in the header is base64-encoded credentials containing your merchantKey as username and authenticationKey as password. MerchantKey and authentication key will be provided by your dedicated Product Solution Specialist.

Header:

Authorization: Basic <base64(merchantKey:authenticationKey)>

Additionally, the merchantKey must be provided in the HEADER of the request in the property X-API-KEY. Your merchantKey should be previously provided by your dedicated Product Solution Specialist, please see Sandbox vs. Production.

Header:

x-api-key: {merchantKey}

important

This must be done for every request to the Subscription APIs. If not provided, the API will return HTTP 403 - Forbidden.

tip

We recommend setting a minimum timeout of 90 seconds, even though API requests are expected to return a response much faster.
Having a 90 second timeout interval allows handling of delays dependent on different queries and responses from external systems and payment providers.

Subscription Process Flow

1. Subscription Plans are created by calling the Subscription Module API Create Subscription Plan. The plan ID returned in the response could be then used for creating underlying subscription(s).
2. Your server creates a new subscription by calling the API method Create Subscription. Alongside your secret Merchant Key which authenticates your request, you should provide also the Customer Account ID for an existing or a new customer. You would receive a response including the The Subscription ID, which is a unique identifier of the subscription.
3. Your server forwards the Subscription ID to your client for the initialization of the Subscription Widget.
4. The customer securely submits their payment information via the initialized Subscription Widget. It directly communicates to the acquirer for the authentication of the payment instrument. Once finished, it provides the storing of the payment option status via a JavaScript callback.
5. The stored payment option would then be used by our system to trigger MIT payments as per the Subscription details (amount, recurrence, ect). Depending on the details of the created subscription, our backend would create a billing cycle for each due charge. Each billing cycle would be linked to at least one transaction.

Payment Series Process Flow

1. A Payment Series is created by calling the Subscription Module API Create Payment Series. You would receive a response including the The Payment Series ID, which is a unique identifier of the payment serie.
2. Your server forwards the Payment Series ID to your client for the initialization of the Subscription Widget.
3. The customer securely submits their payment information via the initialized Subscription Widget. It directly communicates to the acquirer for the authentication of the payment instrument. Once finished, it provides the storing of the payment option status via a JavaScript callback.
4. At this point, whenever you want to trigger an MIT transaction under the created Payment Series, you can call the Create PS Transaction API.

For the full details of the available features and APIs please refer to this section.

tip

For a complete list of endpoint specifications and data schemas, please refer to the Subscription API-Reference.