List programmes

List all available programmes. Use a programme’s ProgrammeId when creating a payment request that uses Payee Choice.

Endpoints

EnvironmentMethod and URL
StagingGET https://api.staging.vitesse.io/v1/payment-initiation/programmes
Production – UK HubGET https://api.vitesse.io/v1/payment-initiation/programmes
Production – US HubGET https://api.us.vitesse.io/v1/payment-initiation/programmes

For help choosing an environment, see Environment.

Access requirements

Configure at least one of the following access combinations:

OAuth scopeIdentity client role
programmesprogrammes.viewer
programmesprogrammes.manager

For more information about scopes, see Authentication. For information about the access granted by specific roles, see Identity client roles.

Query parameters

Use these parameters to filter programmes and page through the results.

ParameterWhen to use it
ContinuationTokenRetrieve the next page. Use the token returned in the previous response.
NameFilter programmes by name.
PageSizeSet the maximum number of programmes per page. The default is 10; the accepted range is 1 to 100.
StatusFilter by programme status: Draft, Active, Inactive or Deleted.

Send the request

This example uses the Staging environment:

curl --request GET \
  --url 'https://api.staging.vitesse.io/v1/payment-initiation/programmes' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Accept: application/json'

Replace <access-token> with an access token that contains the required scope.

Example response

A successful request returns 200 OK and a Data array containing programme details. This example returns two Active programmes:

{
  "Data": [
    {
      "ProgrammeId": "42ea67d3-30d9-4143-848a-15cd59878ccd",
      "Status": "Active",
      "Name": "UK Claims",
      "Description": "UK claims payment programme",
      "EligiblePaymentMethods": [
        "BankAccount"
      ],
      "EligibleAccountIds": [
        3761,
        6341,
        6562
      ]
    },
    {
      "ProgrammeId": "e15ac418-dba0-4993-814b-5dba24ff77ad",
      "Status": "Active",
      "Name": "US Claims",
      "Description": "US claims payment programme",
      "EligiblePaymentMethods": [
        "BankAccount",
        "Echeck"
      ],
      "EligibleAccountIds": [
        4827,
        4828
      ]
    }
  ]
}

Use the returned ProgrammeId when retrieving or updating a programme, or when creating a Payee Choice payment request.

Troubleshoot requests

If the request fails, use the returned HTTP status code to identify the likely cause and corrective action.

If the response contains an empty Data array, check that the identity client can access programmes and has the correct role.

For error response formats, additional HTTP status codes and error-handling guidance, see Error responses.

Next steps

Use a programme ID from the results to view its configuration with Retrieve a programme.