How to create subscriptions with the Matic Rest API

In Matic, a recurring payment is one that is executed more than once (prior authorization from the payer), according to an established frequency and that can be stopped automatically or manually. Matic allows these types of payments with a feature called Subscription.

Subscriptions in Matic Rest API can be created in several ways:

Using the Create subscription endpoint: This endpoint allows you to configure a subscription with certain parameters that are used during the transactions execution.
Using some of the available endpoints to create a transactions: Create transaction and Create transaction with payment method, these endpoints allow a transaction execution and optionally you can indicate that such transaction include subscription as well as provide the required recurrence parameters.

To create a subscription in any of the cases the following fields must be taken into account:

Field	Description
day_frecuency	How often, in days, to charge the customer. Incompatible with month_frequency and day_of_month_frecuency.
day_of_month_frecuency	The day of the month on which the customer will be charged when a monthly frequency is used, is incompatible with day_frequency.
month_frecuency	The frequency in months with which the customer should be charged, must be set next to day_of_month_frecuency. It is incompatible with day_frequency.
next_payment_date (Optional)	The date for the next payment to be executed. The frecuency parameters are used to automatically calculate this if omitted and get the closest date that applies. This field allows you to set date further away if you needed.
stop_date (Optional)	The farthest date when the recurring payment is allown to be active. If the next payment date calculated that day or before results in a date after the indicated then the subscription is automatically paused. When is omitted then you will need to manual stop the subscription.

📘
Remember that
When you configure a subscription with the parameter month_frecuency then you must include the field day_of_month_frecuency and exclude the field day_frecuency.

Examples of monthly subscription creation

The monthly frequency parameters allow you to set in how many months the transactions should be made, so if you want to execute transactions with common frequencies such as monthly or quarterly, they can be configured quickly.

Using the Create subscription endpoint:

For this example we intend to create a subscription that will be charged on the 5th of each month for a period of 3 months, this is achieved by configuring the field day_month_frequency with the value 5 and month_frequency with the value 1, the next_payment_date field with the value "2024-07-05" and the stop_date field with the value "2024-09-05", this will cause the first charge to be made on July 05, 2024, then on august 05, 2024 it will charge again and the last charge will correspond with the stop_date set for September 05, 2024.

curl --request POST \
     --url https://api.matic.io/subscriptions \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "merchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
     "payment": {
          "apply_cfee": true,
          "cfee_included": true,
          "merchant_gateway_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "sec_code": "PPD",
          "total": 500
     },
     "payment_method_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
         "subscription_settings": {
          "day_of_month_frecuency": 5,
          "month_frecuency": 1,
          "next_payment_date": "2024-07-05",
          "stop_date": "2024-09-05"
     }
}
'

Using the Create transaction endpoint:

A subscription can be created from a transaction by setting the is_subscription field to true and specifying the subscription settings that will be applied to future payments.

This example uses the same configuration as the previous example for a monthly subscription that will be charged on the 5th day for 3 months.

curl --request POST \
     --url https://api.matic.io/transactions \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "billing_address": {
          "address1": "string",
          "address2": "string",
          "city": "string",
          "country": "USA",
          "state": "string",
          "zip_code": "string"
     },
     "create_third_party_token": true,
     "customer_email": "[email protected]",
     "is_subscription": true,
     "merchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
     "payment": {
          "apply_cfee": true,
          "cfee_included": true,
          "merchant_gateway_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "sec_code": "PPD",
          "total": 500
     },
     "payment_method_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
     "subscription_settings": {
          "day_of_month_frecuency": 5,
          "month_frecuency": 1,
          "next_payment_date": "2024-07-05",
          "stop_date": "2024-09-05"
     },
     "trans_metadata": "string"
}
'

Examples of creation of a subscription with daily frequency

The daily frequency parameter allows you to set the number of days from the date indicated in next_payment_date to a stop condition given by the stop_date field. This frequency is quite useful if you want to make payments with less common frequencies such as every 2 days, every 13 days, among others.

In this example, the customer will be charged 500$ every 13 days from 2024-07-05 through 2024-12-05.

Using the Create subscription endpoint:

curl --request POST \
     --url https://api.matic.io/subscriptions \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "merchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
     "payment": {
          "apply_cfee": true,
          "cfee_included": true,
          "merchant_gateway_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "sec_code": "PPD",
          "total": 500
     },
     "payment_method_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
     "subscription_settings": {
          "day_frecuency": 13,
          "next_payment_date": "2024-07-05",
          "stop_date": "2024-12-05"
     }
}
'

Using the Create transaction endpoint:

curl --request POST \
     --url https://api.matic.io/transactions \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "billing_address": {
          "address1": "string",
          "address2": "string",
          "city": "string",
          "country": "USA",
          "state": "string",
          "zip_code": "string"
     },
     "create_third_party_token": true,
     "customer_email": "[email protected]",
     "is_subscription": true,
     "merchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
     "payment": {
          "apply_cfee": true,
          "cfee_included": true,
          "merchant_gateway_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "sec_code": "PPD",
          "total": 500
     },
     "payment_method_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
     "subscription_settings": {
          "day_frecuency": 13,
          "next_payment_date":"2024-07-05"
          "stop_date": "2024-12-05"
     },
     "trans_metadata": "string"
}
'

📘Remember that

Examples of monthly subscription creation

Examples of creation of a subscription with daily frequency

📘
Remember that