# Overview

Enabling recurring payments can give you the edge over your competition. Subscriptions and one-click payments provide you with an easy-to-use system to charge your customers regularly.

Some of the benefits recurring transactions bring to merchants:

  • predictable revenue streams
  • greater availability of expensive products to the general public
  • increased convenience and loyalty of customers

No matter what area you operate in, Straal will help you boost your revenue by smart and automated charging of cards and bank accounts.

In this section you'll learn about:

  • setting up one-click payments
  • managing plans and subscriptions
  • Straal Retry Logic

# One-click payments

One-click payments enable your customers to easily pay for products or services. Once they store their card credentials during the first payment, they don't need to re-enter them later. This is both more secure and convenient.

To get an idea of how one-click transactions are performed with Straal, see the scenario below.

Use case – a one-click transaction

This scenario fits a returning customer of an online retailer or a mobile app store. Such customers often perform irregular transactions of varying amounts. A one-click payment is generally a convenience in such cases.

When attempting the first payment, the customer is required to provide their card's security details. Once a card object has been created, it can later be referred to with its ID, without the need to provide the card's CVV and expiration date each time.

If you haven't yet, you need to create a customer first (see APIref: Create a customer). You'll need to specify the customer's email and (optionally) their unique reference.

During the first transaction, a new customer needs to specify their card details, that is, the card number, CVV, expiry date and the cardholder's name.

To learn more about the first transaction, see: Payment methods – cards or APIref: Creating a transaction with a card.

If a customer attempts another transaction, they don't need to provide their card's security details. When a card object is created during the first transaction, the card's information is tokenized, so it can be substituted with its ID afterwards. You can see an example in: APIref: Creating a transaction.

You can read more about tokenization in Transactions.

# Subscriptions

From global SaaS companies (such as VoD services, music platforms) to more traditional subscription services (such as gym memberships or subscription of periodicals), subscriptions provide a stable and reliable source of income.

Subscription-based models help businesses build customer loyalty easily and grow their client bases, because it's so easy for a customer to make simple recurring payments without the need to refill their details every time.

# Plans

Before you start a subscription, you need to create a plan. It determines how the client will be charged. Easily set up the parameters defining your payment schedule and method with the Straal API. Try out a variety of options and choose the best one, because the number of plans you create is unlimited. Encourage new customers to buy your product or service with free-of-charge trial periods.

Use case – create a plan

Consider a VoD business charging a monthly fee of $9.99 to its clients. As it is just starting its operations, it introduces a 30-day trial period to encourage clients to use its service.

To create a plan, you will need to specify the following:

  • your plan's name
  • the amount to be charged, for example 999 for $9.99
  • the currency
  • the trial length in days (here: 30)
  • the frequency of card charges (here: once every month)

So, a request body could look like this:

  "name": "Regular monthly $9.99",
  "amount": 999,
  "currency": "usd",
  "trial_days": 30,
  "step_type": "month",
  "step_value": 1

In the response there will be a newly generated plan_id that you can use to refer to this plan. For details, see APIref: Create a plan. Or read more about plans in APIref: Plans.

# Trials

Trials are useful when you want to give your customers some time to try your product before you start charging them. Be it 7 or 30 days, or 6 months, you decide how and when to charge them.

The duration of a trial is defined in the API request in the trial_days key. For example, a request to create a subscription with a 30-day trial would contain the following in the request body:

  "trial_days": 30

Read more about declaring trial periods in a sample scenario of creating a subscription with a trial or in APIref: Plans.

# Managing subscriptions

The Straal API allows creating, modifying or cancelling a subscription. To better understand how to manage a subscription, see two sample scenarios below. For technical details, such as what to include in the API request, see APIref: Subscriptions.

Use case – create a subscription with a trial

To better understand how to manage a subscription, consider the following example. This scenario fits an online service provider, such as music or video streaming sites. A new customer decides to subscribe to your service for a monthly fee of $9.99. As a newcomer, they get a free 30-day trial.

To add a new subscription, there needs to be a plan created beforehand. Plan defines how often and for what amount will you charge the customer. To learn how to create a plan, see "Plans" above.

Once there is a plan created, you can create a subscription. A subscription needs to be connected to customer and card objects, which you need to create beforehand. See APIref: Create a customer and APIref: Create a card using CryptKey).

To do so, you will need:

  • your plan's ID generated at its creation (plan_id)
  • credit or debit card details
  • the customer's email address
  • (optionally) your unique reference for this customer

After you create a customer and link him to a card you can create the subscription. A request body for creating a subscription (endpoint: https://api.straal.com/v1/cards/:card_id/subscriptions) could look like this:

  "plan_id": "mcn15j2hwhq4f",

The response will contain information about newly created subscription. For details, see APIref: Create a subscription.

If you wish to check the details of your new subscription later, you can do so using its ID (see: APIref: Get a subscription).

Use case – cancel a subscription

You own a chain of gyms and fitness clubs. One of your customers, Ms. Cortes is relocating to another country and, sadly, has to cancel her membership. You can cancel her monthly subscription using the Straal API.


  • If the customer changes her mind later, you can't restore a cancelled subscription. You'll have to create a new one instead.
  • When a subscription is cancelled, it ends after the current billing period is over.

To cancel a subscription, you'll need the following:

  • your API Key with the permission v1.subscriptions.cancel
  • subscription ID

To cancel a subscription, you send a POST request to https://api.straal.com/v1/subscriptions/:id/cancel where :id is the ID of the subscription you wish cancel. In the body of the request, you send an empty JSON: {}, optionally containing extra-data:.

You can see a sample response in APIref: Cancel a subscription.

# Subscription lifecycle

Subscription lifecycle is a sequence of operations that you can perform on a subscription in Straal.

Diagram showing what can happen to a subscription during it lifecycle. It's described below.

  1. A subscription is created.
  2. If a subscription is linked to a plan with a trial period, a Verification Authorization is carried out, and the trial starts.
  3. If there is no (more) trial, the connected card is authorized and charged.
  4. If the charge is successful, the next one happens after the subscription period comes to an end. The next charge begins the next subscription period. If a charge fails, a transaction retry is possible, according to your setup (see: Smart Retry Logic).
  5. At any point, a subscription can be cancelled. To functionally renew a subscription, a new one has to be created.

# Smart Retry Logic

It can sometimes happen that a subscription charge fails either for technical reasons or due to insufficient funds on the payer account. You can instruct Straal to automatically retry failed subscription transactions. It will happen automatically, and can be fine-tuned to your business model.

Note: if your shop uses a retry logic, it should be explained in your Terms and Conditions that a recurring payment will be performed with the help of an auto-retry system.

If you are an enterprise client, you can also ask us to switch on our Smart Charge Logic, that was designed to bring the best results as far as the effectiveness of charging is concerned. It was optimised using machine learning algorithms and the vast amounts of data that we have gathered over the years.

If you let us know your preference, we will customise the retry logic for you. The default behaviour of the system is not to attempt an operation again after it was rejected.

Here is an example logical chain you could set up:

An example chain for the retry logic. It's described below.

  1. An attempted operation is rejected.
  2. Straal sends you a notification (see Notifications) and schedules a retry in 3 days.
  3. You should send an email to your customer, saying something like: "We were unable to charge your card and we will try again in 3 days. Make sure there are sufficient funds in your account, or click to use another card."
  4. If the retry fails 3 days later, then Straal notifies you and schedules one more attempt in 2 days.
  5. If the operation fails again, Straal notifies you and doesn't try again.

# Create Subscription Request

Create Subscription Requests (CSRs) are objects in our system, created automatically for correctly formed POST requests to subscription endpoints. CSRs store data related to subscription creation: card or bank account, transactions, plan and, if the request succeeded, also subscription details.

Imagine that something goes wrong while creating a subscription. Many factors may cause an attempt to create a subscription to be rejected, such as basic validation, anti-fraud mechanisms, custom rules and so forth. You can use CSRs to analyse how the custom rules influence the percentage of accepted transactions.

For more instructions, see APIref: Get a CSR or APIref: Get the CSR list.

What you can do next:

Remember you can consult our comprehensive API Reference at any moment.

For help with payments vocabulary, head to our glossary.

You can reach us by e-mail. IT Support: [email protected], Support Team: [email protected].