Subscriptions

Preparing your account

Before you can create subscriptions, make sure you've checked everything on the merchant account setup checklist:

• ✓  Active Assets are configured.
• ✓  Gas Wallet contains native tokens.
• ✓  API Key created.
• ✓  After testing, to use the MainNet: KYB procedure is finished.

Overview

Subscriptions enable merchants to generate reliable recurring revenue. Merchants can easily create subscription plans and automatically charge customers on a periodic basis. When working with subscriptions, there are a few building blocks to consider:

1. Subscription Plan.
2. Subscription.
3. Subscription Charges.

Plan

The subscription plan defines the core attributes of future subscriptions. It could be used as a source for the list of subscription plans for customers to select from.

To create a new subscription plan, navigate to the relevant dashboard section and click on the "Create plan" button.

Create plan button

When creating a plan, please specify the following attributes:

• Asset: The specific token that will be debited from the customer.

• Period: The frequency of debits in days (selectable from 1 to 365).
  For monthly debits, please specify 31 days.

• Grace period: The grace period defines the amount of time allowed after a subscription expires before the subscription cancellation. Setting a grace period helps in managing temporary issues such as payment delays or technical problems, ensuring continuous service and providing a better customer experience. Consider factors like billing periods, typical payment processing times, and your flexibility in handling late payments when setting this period.

• Name and description: Information about the plan that will be displayed to the user.

• Tags: An optional field for a list of text tags, which can be useful for searching for the plan in the future. The main purpose of tags is to group and categorize plans. You an assign arbitrary tags to plans and use them in UI to filter or group plans according to your logic.

New subscription plan form

Plan statuses have the following mechanics:

• Once created, a plan has a Draft status. The plan can be updated in this status only.
• In order to create a subscription based on a plan, that plan should be switched to Active.
• When a plan is no longer needed, it should be moved to a Acrhive status. Subscriptions cannot be created in this status anymore, but you can always move them back to active status if needed.

Plan activation

After you activate a plan, you can start adding subscriptions for your customers.

Active plan status

Subscription

A subscription is an entity that is linked to a subscription plan and contains charging rules. Charging rules are immutable and implemented as a smart contract on a blockchain network. Once deployed, this smart contract controls the number of tokens being transferred from the payer to the merchant.

Subscription creation must be performed exclusively on the merchant's backend system. This is because we require the secret part of the API key for request authentication.

Creation via API

To create a subscription via API, the following steps are required:

• planId: Select the ID of the active plan for which the subscription will be created.
• customerId: Specify the customer ID within the merchant's system.
• payer: Indicate the customer's blockchain address from which debits will be made.

More API details at the route description.

# This code must be on your backend side
# Do not send your Secret into Client Browser!
curl --request POST \
  --url https://api.smartypay.io/integration/subscriptions \
  --user API_KEY:SECRET \
  --header 'content-type: application/json' \
  --data '{
    "planId": "CjGSkDdmSNCslurvtgu2Vw",
    "customerId": "some-customer-001",
    "payer": "0x14186c8215985f33845722730c6382443bf9ec65",
    "startFrom": "2024-07-29T13:51:34.755Z"
}'

We'll get a summary of the new subscription, which will be marked as a "Draft":

{
  "status": "Draft",
  "contractAddress": "0xd90537f50e6273f904ac5d2cadc68b5dc679e36e",
  "planId": "CjGSkDdmSNCslurvtgu2Vw",
  "payer": "0x14186c8215985f33845722730c6382443bf9ec65",
  "asset": "bUSDT",
  "blockchain": "BinanceTestNet",
  "customerId": "some-customer-001",
  "nextChargeAt": "2024-07-29T13:51:34.755Z",
  "createdAt": "2024-07-29T13:51:34.755Z",
  "startFrom": "2024-07-29T13:51:34.755Z"
}

Please pay attention to the contractAddress field in the created subscription. This is the address of the blockchain contract responsible for withdrawing funds from the customer's blockchain address.
The customer will need to grant explicit permission for this contract to withdraw funds from their address. This is necessary for the contract to be able to collect the required subscription fee at the specified time.

To summarize:

1. We create a subscription associated with a specific customer's cryptocurrency wallet address.
2. The generated subscription itself has its unique blockchain address.
3. The customer must authorize the withdrawal of tokens to this address.

Getting a customer's blockchain wallet address can be tricky. Customers usually use special apps called crypto wallets. While these apps can provide the address, setting them up can take a long time.
That's why we've made things easier with our SDK. We've done all the hard work of connecting with the customer's wallet, so you don't have to.

Creation via SDK

As with creating a subscription directly via REST API, we need to obtain the following data from the client:

• The client's blockchain address from which all future subscription charges will originate
• The client's authorization to debit funds from this address

Smarty Pay can handle these tasks through its ready-made subscription creation widget:
new-subscription.smartypay.io.

Initially, we connect the user's crypto wallet and display information about the future subscription.

Connected client crypto wallet

Then, we ask them to give us permission to take the necessary funds for the subscription.

Request allowance for a necessary funds

Session Token Creation

To use our subscription widget, you'll need to create a special session token. This ensures that the merchant has directly established the link to their customerId. By using this session token, you can make sure that the customer information you see in the widget is correct and hasn't been changed.

Example of session token creation by API call:

# This code must be on your backend side
# Do not send your Secret into Client Browser!
curl --request POST \
  --url https://api.smartypay.io/integration/subscriptions/create-customer-token \
  --user API_KEY:SECRET \
  --header 'content-type: application/json' \
  --data '{
    "customerId": "your_customer_id"
}'

Also, don't forget to obtain the identifier of the active plan for which a new subscription will be created:

# This code must be on your backend side
# Do not send your Secret into Client Browser!
curl 'https://api.smartypay.io/integration/subscription-plans' \
  --user API_KEY:SECRET

More info about these routes you can find here.

Or you can get same data by using our Node.js SDK:

import { SmartyPayAPI } from 'smartypay-node-sdk';

// This code must be on your backend side
// Do not send your Secret into Client Browser!
const api = new SmartyPayAPI({
  publicKey: 'API_KEY',
  secretKey: 'API_SECRET'
});

// Make a new session token for the widget in frontend
const sessionToken = await api.subscriptions.createCustomerToken({
  customerId: 'your_customer_id'
});

// Get the target plan id
const activePlans = await api.getActivePlans();
const targetPlanId = activePlans[0].id

More info about SDK you can find here.

Open Subscription Widget

We now have everything we need:

• A session token to open the Smarty Pay widget.
• The identifier of the desired subscription plan.

This is sufficient to open the subscription widget directly using the following URL:
https://new-subscription.smartypay.io/?plan={PLAN_ID}&session={SESSION_TOKEN}

Alternatively, you can embed the widget opening on the merchant's site as a popup window using our client-side SDK:

import {SmartyPaySubscriptions} from 'smartypay-client-sdk';

const frontApi = new SmartyPaySubscriptions();

frontApi.newSubscriptionWidget({
    sessionId: sessionToken,  // sessionToken from backend
    planId: targetPlanId,     // targetPlanId from backend
    target: 'target-html-id'  // id for parent element in html page
})

As a result, the Smarty Pay widget will open for creating a new subscription. This widget will handle all interactions with the customer's crypto wallet, including requesting permission to debit payment for the subscription:

New subscription widget

Charges

A subscription charge represents a single token transfer from the payer to the merchant.

A merchant can view the complete subscription charge history in the "Subscriptions" section of the dashboard:

Subscription charges history

The following statuses could be assigned to a subscription charge:

Managing Active Subscriptions

Once a customer's initial payment has been successfully processed, their subscription becomes active. However, there may be instances where either the customer or the merchant wishes to modify an active subscription, such as by pausing or canceling it.

Merchants can access these features within the subscriptions section of their dashboard:

Subscription flow edit by merchant

Smarty Pay has a special page where the client can manage their subscription themselves:
subscriptions.smartypay.io

Subscription flow edit by client

To access this screen, a merchant must generate a session token for the customer, similar to the process for creating a subscription widget. For detailed instructions on token generation, please open this section.

Replace the placeholder in the subscription edit page URL with the correct session token:
https://subscriptions.smartypay.io/?session={SESSION_TOKEN}

On this screen, the customer can:

• View the current subscription details.
• Modify the authorized limit for future charges.
• Pause the subscription.
• Cancel the subscription.
• Create a new subscription on a different plan.
• View the charge history.

Subscription Flow

The following status transitions are possible for a subscription.

Subscriptions flow