Create a scheduler
Create a scheduler to set when Vendor Pay payment requests assigned to it become eligible for processing. Define the schedule with a cron expression in UTC. For details, see Scheduler timing below.
Endpoints
| Environment | Method and URL |
|---|---|
| Staging | POST https://api.staging.vitesse.io/v1/payment-initiation/paymentSchedulers |
| Production – UK Hub | POST https://api.vitesse.io/v1/payment-initiation/paymentSchedulers |
| Production – US Hub | POST https://api.us.vitesse.io/v1/payment-initiation/paymentSchedulers |
For help choosing an environment, see Environment.
Access requirements
Configure the following access:
| OAuth scope | Identity client role |
|---|---|
payment-requests | payment-requests.manager |
For more information about scopes, see Authentication. For information about the access granted by specific roles, see Identity client roles.
Scheduler timing
When a scheduler is assigned to a Vendor Pay payment request, its cron expression determines when the request becomes eligible for processing.
Vitesse checks for eligible requests every 20 minutes, or when the account is topped up, so processing may not begin at the exact scheduled minute.
Vendor Pay schedules use UTC. For example, 09:00 UTC is 09:00am in the UK during winter and 10:00am during British Summer Time. A fixed UTC expression therefore won’t stay at the same UK local time throughout the year.
Cron expression format
A cron expression has five values separated by spaces. Each value sets one part of the schedule:
- Minute – when in the hour, from
0to59. - Hour – which hour, using 24-hour time from
0to23. - Date – which day of the month, from
1to31. - Month – which month, from
1(January) to12(December) - Weekday – which day of the week, from
1(Monday) to7(Sunday).
Use * to allow any value in that field. Other fields can continue to restrict when the schedule runs. For example, you may use asterisks for Date and Month to allow all options, but limit the schedule to a specific Weekday.
Use */n to select an interval in that field. For example */15 in the minute position selects minutes 0, 15, 30 and 45 of each hour.
For example, 0 9 * * 1 means every Monday at 09:00 UTC. Read the values in order:
0– minute zero9– 09:00 am*– any date*– any month1– Monday
Examples:
0 9 * * *– every day at 09:00 UTC0 17 * * 5– every Friday at 17:00 UTC0 0 15 * *– the fifteenth of each month at 00:00 UTC0 */6 * * *– every 6 hours, at 00:00, 06:00, 12:00 and 18:00 UTC daily.
Send the request
This example uses the Staging environment:
curl --request POST \
--url 'https://api.staging.vitesse.io/v1/payment-initiation/paymentSchedulers' \
--header 'Authorization: Bearer <access-token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"Name": "Every six hours",
"CronExpression": "0 */6 * * *"
}'Replace <access-token> with a valid access token that contains the required scope, and any example values with your own details.
Example response
A successful request returns the new scheduler's PaymentSchedulerId:
{
"PaymentSchedulerId": "f42e2a27-7646-4ea8-bd32-eb5f6a7cca98"
}Use the returned PaymentSchedulerId when assigning this scheduler to a payment request.
Troubleshoot requests
If the request fails, use the returned HTTP status code to identify the likely cause and corrective action.
For error response formats, additional HTTP status codes and error-handling guidance, see Error responses.
Next steps
Use the PaymentSchedulerId when creating a scheduled payment request. For more information, see Make a payment using Vendor Pay.
Updated 15 days ago