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

EnvironmentMethod and URL
StagingPOST https://api.staging.vitesse.io/v1/payment-initiation/paymentSchedulers
Production – UK HubPOST https://api.vitesse.io/v1/payment-initiation/paymentSchedulers
Production – US HubPOST https://api.us.vitesse.io/v1/payment-initiation/paymentSchedulers

For help choosing an environment, see Environment.

Access requirements

Configure the following access:

OAuth scopeIdentity client role
payment-requestspayment-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 0 to 59.
  • Hour – which hour, using 24-hour time from 0 to 23.
  • Date – which day of the month, from 1 to 31.
  • Month – which month, from 1 (January) to 12 (December)
  • Weekday – which day of the week, from 1 (Monday) to 7 (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 zero
  • 9 – 09:00 am
  • * – any date
  • * – any month
  • 1 – Monday

Examples:

  • 0 9 * * * – every day at 09:00 UTC
  • 0 17 * * 5 – every Friday at 17:00 UTC
  • 0 0 15 * * – the fifteenth of each month at 00:00 UTC
  • 0 */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.