The Payment Scheduler API allows you to easily set up and manage recurring billing payments. Once the customer and card details are saved in Card Storage you can set up a new schedule using just the returned token references. As per the schedule specified, Global Payments will obtain the cardholder details from our secure vault and create the authorization request. Whenever scheduled payments are executed, a full report of the day's transactions with each outcome will be emailed to an administrator on your account.
Create
Once you have a card saved in Card Storage you can set-up scheduled payments against it. In the request, you supply the references of the Payer and Payment Method to be charged and the specific schedule pattern to follow, for example weekly, monthly, on the last day of each month. You can specify the number of times for the scheduled payment to run, or alternatively, use an end date. You can also set the date for the schedule to begin or the date after which it should start. Otherwise the current date is used. The maximum frequency for schedules to run is daily.
We provide a series of short-hand macros to easily set up a schedule such as daily, monthly, and bimonthly. You can also use cron expressions for more specific and advanced functionality. For more information please see the Macros & Cron Expressions section below. Once executed, the response will include the Schedule Text element, this is a plain English text of the schedule created. You should ensure that it conforms to your intended payment schedule.
Sample Request
<?xml version="1.0" encoding="UTF-8"?>
<request type="schedule-new" timestamp="20170331140251">
<merchantid>MerchantID</merchantid>
<account>internet</account>
<channel>ECOM</channel>
<scheduleref>58de618b3279c</scheduleref>
<alias>Gym Membership</alias>
<orderidstub>gym</orderidstub>
<transtype>auth</transtype>
<schedule>monthly</schedule>
<startdate>20170402</startdate>
<numtimes>12</numtimes>
<!-- if using end date
<numtimes>-1</numtimes>
<enddate>20180131</enddate> -->
<payerref>03e28f0e-4cf0-492e-80bd-20ec318e9334</payerref>
<paymentmethod>3c4af936-3732-483e-a393-f558bec2fb2a</paymentmethod>
<amount currency="EUR">1001</amount>
<prodid>Fitness First</prodid>
<varref>My Legal Entity</varref>
<custno>987654123</custno>
<comment>Social Sign-Up</comment>
<sha1hash>6616a0949b15de433f25cfc4cc5ec5f6f9518e69</sha1hash>
</request>Search
This request allows you to retrieve the list of scheduled payments associated with a particular Payer and Payment Method. The response will contain the details of each one under the Schedules element.
Sample Request
<?xml version="1.0" encoding="UTF-8"?>
<request type="schedule-search" timestamp="20180802120019">
<merchantid>MerchantID</merchantid>
<payerref>03e28f0f-4cf0-492e-80bd-20ec318e9334</payerref>
<paymentmethod>406aec24-b56f-4ee7-9729-05c098afdb07</paymentmethod>
<sha1hash>83e0cb3aeffa80d53ffbd72ab83015f8f79ad4a0</sha1hash>
</request>Delete
If you wish to cancel a scheduled payment you can send a delete request. This action cannot be undone so please exercise caution when using this request type.
Sample Request
<?xml version="1.0" encoding="UTF-8"?>
<request type="schedule-delete" timestamp="20180802120019">
<merchantid>MerchantID</merchantid>
<scheduleref>58de618b3279d</scheduleref>
<sha1hash>718ef2612bd985b6a01398888849f8d23b3a49de</sha1hash>
</request>Get
Using just the Schedule Reference, this request retrieves the details (for example, number of times run) of a specific schedule. The response will include the additional data that can be supplied when setting up the schedule, including customer number, product ID, variable reference and comments, in addition to the Payer and Payment Method references the schedule is configured to charge.
Sample Request
<?xml version="1.0" encoding="UTF-8"?>
<request type="schedule-get" timestamp="20180802120019">
<merchantid>MerchantID</merchantid>
<scheduleref>58e2313ae72bf</scheduleref>
<sha1hash>a3e961f1b111ceb52a55ee673ec781e1967dc3a3</sha1hash>
</request>Macros
When creating a recurring or subscription payment, the <schedule> element is used to specify how often and when to charge the relevant Payer and Payment Method. You can submit this schedule as a Cron expression, we also have some simple macros you can use. The macros will set up a schedule based on the current date. For example, sending the value as monthly will set up a monthly recurring scheduled transaction each month on today's date. This does not include the actual day the schedule is created.
| Macro | Description |
|---|---|
|
weekly |
Set up a payment weekly on today's day. For example if the schedule is set up on a Tuesday, it will be charged every Tuesday. |
| monthly | Set up a payment monthly on today's date. If the date is 29th, 30th or 31st then the last day of the month will be used automatically. |
| bimonthly | Set up a payment every January, March, May, July, September and November on today's date. If the date is 29th, 30th or 31st then the last day of the month will be used automatically. |
| quarterly | Set up a payment every January, April, July and October on today's date. If the date is 29th, 30th or 31st then the last day of the month will be used automatically. |
| halfyearly | Set up a payment every January and July on today's date. If the date is 29th, 30th or 31st then the last day of the month will be used automatically. |
| yearly | Set up a payment yearly on today's date. |
Cron Expressions
Alternatively, you can use the cron expression format. It is comprised of 3 required fields separated by white space: "day-of-month␣month␣day-of-week".
Specifying both a day-of-week and a day-of-month value is currently not supported. You'll need to use the '?' character in one of these fields.
| Field Name | Allowed Values | Value Translation | Allowed Special Characters |
|---|---|---|---|
| day-of-month | 1-31 | The specific date in the month to execute | , - * ? / L W |
| month | 1-12 | The specific month to execute (Jan - Dec) | , - * / |
| day-of-week | 1-7 | The specific day of the week to execute (Sun - Sat) | , - * ? / L # |
You can use the numerical allowed values to declare specific dates, months and days of the week for the payment to be executed. The special characters allow for more advanced functionality. In the table below we've outlined their general function and what their value means in each field.
| Value | Description | day-of-month | month | day-of-week |
|---|---|---|---|---|
| , | Specify additional values. For example 1,2 * ? means run on the 1st and 2nd of every month. | N/A | N/A | N/A |
| - | Specify a range of values. For example 1-5 * ? means run on each day from the 1st to the 5th of the month, every month. | N/A | N/A | N/A |
| * | Specify all values | every day of the month | every month | N/A |
| ? | Used to declare no specific value. Can only be used in the day-of-month and day-of-week fields. Used when you wish to specify a particular in one of those fields, but not the other. | any day of the month | N/A | any day of the week |
| / | Can be used to specify increments in months. For example */4 means every 4 months. In addition to increments, can also be used to specify exactly what months in the year it will occur. Based on the increment set, the year will be divided into segments of that increment. For example, if we set the increment to 4, the year is then divided into three segments of 4: Jan - April, May - Aug, Sept - Dec. If we want our schedule to start in March and run in July and November (and repeat the exact same the next year) we would set a value of 3/4(or the third month in our segments of 4). |
N/A | every nth month | N/A |
| L | Short-hand for last. If used in the day-of-month field it can be used in conjunction with an offset. For example, L-3 would mean the third-to-last day of a calendar month. In the day-of-week field, it can be used to specify "the last Sun-Sat of the month". For example, 6L would mean "last Friday of the month". |
last day of the month | N/A | last day of the week |
| W | This character is used to specify the weekday (Monday-Friday) nearest the given day. For example, if you were to specify 15W as the value for the day-of-month field, the meaning would be: "the nearest weekday to the 15th of the month". So 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. The L and W characters can also be combined for the day-of-month expression to yield LW, which translates to "last weekday of the month". |
nearest weekday to | N/A | N/A |
| # | Used to specify "the nth Sun-Sat day of the month". For example, the value of 6#3 means "the third Friday of the month" (day 6 = Friday and "#3" = the 3rd one in the month). Some other examples include:
|
N/A | N/A | the nth Sun-Sat of the month |
Some Cron Examples
|
Cron expression
|
Value meaning
|
|---|---|
| * * ? | Daily |
| ? * 3 | Weekly on Tuesday |
| 4 * ? | Monthly on the 4th |
| L * ? | Monthly on the last day of the month |
| 24 */3 ? | Every quarter of the year (January, April, July and October) regardless of when the schedule is created. |
| ? * 6#3 | Monthly on the 3rd Friday |
| ? * 4L | Monthly on the last Wednesday |
| ? */2 1#2 | Every 2 months on the 2nd Sunday |
| ? */4 2L | Every 4 months on the last Monday |
| 28 6/6 ? | On the 28th every 6 months starting in June |
| 24 1 ? | Yearly on the 24th of January |
| LW * ? | Monthly on the last weekday of the month |
| 7W */2 ? | Every 2 months on the nearest weekday to the 7th |
| 15W * ? | Monthly on the nearest weekday to the 15th |
| L 2 ? | Yearly on the last day of February |
| 7W 11 ? | Yearly on the nearest weekday to the 7th of November |
| LW 8 ? | Yearly on the last weekday of August |
Generate Hash
Follow the steps in this section to build the request security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.
In addition to SHA-1, you can also generate your hash using SHA-256. The resulting hash should be placed in the <sha256hash> tag instead of the <sha1hash> tag. For more information, contact our support team at ecomsupport@globalpay.com.
Build the Request Hash
Use the dropdown below to select a request type: Create, Search, Delete or Get. After making a selection, the steps on how to build the request hash for that type are provided.
Check Hash
Follow the steps in this section to build the response security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.
Check the Response Hash
Use the dropdown below to select a request type: Create, Search, Delete or Get. After making a selection, the steps on how to check the response hash for that type are provided.