The Repeat Billing system gives merchants who use the Hosted Payment Pages the ability to setup and manage automatic recurring payments, such as those used in a subscription service. The ability to directly debit a card for each payment depends upon your acquiring bank allowing ‘Continuous Authority’ transactions for your merchant account.
Payment Agreements
The Repeat Billing System allows you to create and manage what are termed Payment Agreements. These Payment Agreements specify the value and frequency of the payments to be made. Payment Agreements can be for a fixed term, or for an unlimited term.
Their elements that form a Payment Agreement are as follows:
- Initial payment amount
- Payment period (Monthly or Weekly)
- Payment interval (Interval between payment periods, e.g. every 2 weeks)
- Regular payment amount
- Start date (when to start the regular payments)
- Term (how many payments to take)
- Final payment amount (Any additional final payment to take after the last regular payment)
With these elements, it is possible to create Payment Agreements that suit most subscription requirements or other regular payment requirements.
Sending the payment agreement details
The details are sent as part of the transaction request using the following fields:
| Field | Description | Notes |
|---|---|---|
| amount | Regular payment amount | The amount to be taken at each payment interval. |
| period | Agreement billing period | This can be set to either ‘M’ (Months) or ‘W’ (Weeks) |
| interval | Number of Weeks/Months between each payment | Set to 1 to bill every month/week (as per billing period). |
| start | Agreement start date | Formatted as DDMMYYYY. The start date cannot be the same date that the agreement is made on, and cannot be a date that has already past. |
| term | Agreement term | Indicates the number of regular payments to take. Set this to zero to indicate an unlimited term. |
| final | Final payment amount | 0 if there is no final payment amount. Final payment can only be set if there is a fixed term to the agreement. |
| auto | Auto Repeat : Indicates whether the subsequent transaction is initiated by merchant or auto charged by system. | Value: “true” denotes that Telr system will charge the customer automatically in the given interval. Value: “false” denotes that merchant will initiate the subsequent transaction. * Default value is true if auto is not passed in repeat object. |
| type | Repeat Type : Indicate the type of subsequent authorization. | Values: “unscheduled” or “recurring” (This field is required to indicate that this transaction may be used for subsequent authorization) If auto is passed as “false” then “type” must be passed. If auto is passed as "true" then type is not required. |
All payment amounts are taken in the same currency as used for the main transaction request (as sent in the field). The amounts must be sent in major units (for example, 9 dollars 50 cents must be sent as 9.50 not 950).
Example
{
"method": "create",
"store": 15996,
"authkey": "mykey1234",
"order": {
"cartid": "1234",
"test": "1",
"amount": "10.50",
"currency": "AED",
"description": "My purchase"
},
"return": {
"authorised": "https://www.mysite.com/authorised",
"declined": "https://www.mysite.com/declined",
"cancelled": "https://www.mysite.com/cancelled"
},
"repeat": {
"auto": true,
"amount": "100.00",
"interval": 1,
"period": "M",
"term": 12,
"final": "0",
"start": "10082023"
}
}
Immediate Payment Amount
This specifies an amount to be taken at the same time that the agreement is setup. The immediate payment amount is sent as the amount field in the main transaction request.
Regular Payment Amount
This is the amount that will be taken from the card holder for each payment
Agreement period and interval
The period must be set to either ‘M’ or ’W’, which relates to Months or Weeks. The interval must be an integer value between 1 and 12.
Examples
| Examples | Notes |
|---|---|
| period=M interval=1 | Payment taken every month |
| period=W interval=3 | Payment taken every three weeks. |
Agreement term
This is a number indicating how many regular payments are to be taken. Set this to zero to indicate an agreement that does not have a fixed term.
| Examples | Notes |
|---|---|
| period=M interval=1 term=12 | 12 payments taken one month apart – agreement duration is 1 year. |
| period=M interval=3 term=0 | Payments taken every quarter, no fixed term. Payments will continue until such time as the agreement is cancelled. |
Start date
This indicates when the first regular payment should be taken. It is an 8 digit value, formatted as DDMMYYYY where DD = 2 digit day, MM = 2 digit month and YYYY = 4 digit year.
This date cannot be in the past, and cannot be the same date as the date the agreement is being made on (i.e. it cannot be today)
When the payment interval is specified in weeks, it will be taken on the same day of the week as the day that this date represents. For example, as the 1st of May 2011 (01052011) is a Sunday, every payment would be taken on a Sunday.
When the payment interval is specified in months, it will be taken of the same day of the month as the day given here. In the event that this is scheduled for a day that not all months have, then the payment will be taken on the last day of the month instead. For example, a payment scheduled for the 30th of each month would be taken on the 28th (or 29th) of February, and on the 30th for all other months.
The start date value can be supplied as the word ‘next’ in which case the first regular payment will be scheduled for one payment period on from today.
| Examples | Notes |
|---|---|
| period=M interval=1 start=10082015 | First payment to be taken on the 10th of August 2015. Subsequent payments will be taken on the 10th of each month. |
| period=W interval=2 start=13062015 | First payment will be taken on the 13th of June 2015. As that is a Saturday, subsequent payments will be taken every two weeks on a Saturday. |
| period=M interval=1 start=next | First payment will be taken 1 month from today. Subsequent payments will be taken on the same day of each month. |
Final payment amount
This specifies an amount to be taken at the end of the agreement. This is only applicable for fixed term agreements (where repeat_term is non-zero). This final amount is in addition to any amount that would be taken as part of the regular payment processing. It will be taken at one payment interval following the last regular payment.
The total amount the customer will pay is as follows For fixed term payments:
- Initial payment amount (amount)
- repeat_term * repeat_amount
- repeat_final
For unlimited term payments:
- Initial payment amount (amount)
- Continual payments of repeat_amount until the agreement is canceled.