This Subscription Integration guide describes how you can schedule subscription payments. Like recurring payments,
the money gets auto-debited from consumer's bank account to the merchant account in fixed time periods (e.g. weekly,
monthly, quarterly, yearly). Similarly, money can be auto-credited using payouts. Subscription businesses benefit from
the flexibility of creating different plans and pricing structures to meet market demands.
A subscription payment can be scheduled as a pre-authorization (PA), debit (DB) or credit (CD) transaction.
To collect card data, you must be PCI-DSS compliant. To minimize your compliance requirements, please use
Primeiro Pay Registration Tokens.
The merchant collects card data from the shopper and schedules a subscription payment. You can set the value
of the transaction, the schedule for when the charges should occur, and the number of times the payment transaction
should happen based on your subscription plan.
Collect the customer payment information via
Primeiro Pay or
Server-to-Server.
With any of the options, please consider having a card-on-file agreement with the shopper. It is best to tokenize
the card during the cardholder (CIT) initiated payment so that a merchant (MIT) agreement is in place for the
future subscription payments.
Sample request:
2. Schedule a payment
Perform a server-to-server POST request with the registration id, payment type and the job schedule parameters
which describes when and how often the transaction should be executed. For a complete reference of the scheduling job parameters,
please check API Reference.
You can use the numerical allowed values to declare specific dates, months and days of the week for the subscription payment
to be executed. The special characters allow for more advanced functionality. Please click the button below to see
the table where we've outlined their general function and what their value means in each field.
1,3,5 OR MON,WED,FRI in the job.dayOfWeek field means the days Monday, Wednesday and Friday
1,2,5 OR JAN,FEB,MAY in the job.month field means the months January, February and May
All fields
-
Range. Specify a range of values.
For example:
1-5 in the job.hour means the hours 1,2,3,4 and 5
2-4 or MON-WED in the job.dayOfWeek means the days Monday, Tuesday and Wednesday
All fields
*
Wildcard. Specify all valid values.
For example:
* in the job.minute means every minute
* in the job.hour means every hour
* in the job.month means every month
* in the job.dayOfWeek means every day of the week
All fields
?
Question mark. Specify no value.
Can only be used in the dayOfMonth and dayOfWeek fields. Used when you wish to specify a particular
value in one of those fields, but not the other.
For example:
15 in the job.dayOfMonth and ? in the job.dayOfWeek means the 15th day of the month, regardless of the day of the week
0/15 in the job.minute means the minutes 0, 15, 30 and 45
3/6 in the job.hour means every 6 hours beginning of the third hour
1/5 in the job.dayOfMonth means every 5 days beginning on the first day of the month
All fields
L
Last. Specify the last day of the month or week.
For example:
L in the job.dayOfMonth means the last day of the month, such as January 31 or February 28 (or 29 during a leap year)
6L or FRIL in the job.dayOfWeek means the last Friday of the month
job.dayOfMonth job.dayOfWeek
W
Nearest weekday. Specify the weekday (Monday-Friday) nearest the given day.
For example:
15W in the job.dayOfMonth means the nearest weekday to the 15th of the month. If the 15th is a Saturday,
the payment will execute on Friday the 14th. If the 15th is a Sunday, it will execute on Monday the 16th. If the 15th
is a Tuesday, then it will execute on that day.
1W in the job.dayOfMonth means the nearest weekday to the 1st of the month
LW in the job.dayOfMonth means the last weekday of the month
job.dayOfMonth
#
Weekday of the month. Specify "the nth Sun-Sat day of the month".
For example, the value of:
6#3 or FRI#3 in the job.dayOfWeek means the third Friday of the month
2#1 or MON#1 in the job.dayOfWeek means the first Monday of the month
4#5 or WED#5 in the job.dayOfWeek means the fifth Wednesday of the month.
If the month doesn't have the five Wednesdays, then no payment is executed.
job.dayOfWeek
Select trial period:
Select schedule:
Sample request:
3. We execute the transaction for you
An automated subscription payment is executed at the scheduled time using the stored payment information and the specified payment type.
4. Cancel the schedule
Send a de-scheduling request specifying the schedule id you want to cancel.
Sample request:
Add new subscription
The merchant collected card data from the shopper and already scheduled a subscription payment. You may now choose a different
pricing plan to allow subscribers enjoying the flexibility to shift to a lower or higher plan as per their preference. You can
set the value of the transaction, the schedule for when the charges should occur, and the number of times the payment transaction
should happen based on your new subscription plan.
Execute the new subscription payment at the scheduled time.
Transactions:
1. Schedule a new pricing plan
Perform a server-to-server POST request with the registration id, new amount value,
the payment type and the job schedule parameters which describes when and how often the transaction should be executed.
For a complete reference of the scheduling job parameters, please check API Reference.
To understand subscription upgrades and downgrades, imagine a fictional magazine company. It offers three subscription options:
Print edition, where the payer gets the physical copy of the magazine
Digital edition, where the payer accesses the magazine online
Both print and digital forms
Select plan:
Select schedule:
Sample request:
2. We execute the transaction for you
An automated subscription payment is executed at the scheduled time using the stored payment information and the specified payment type.
Cancel subscription
The merchant scheduled one or multiple subscription payments. You can cancel any of the subscriptions.
