List programmes
List all available programmes. Use a programme’s ProgrammeId when creating a payment request that uses Payee Choice.
Endpoints
| Environment | Method and URL |
|---|---|
| Staging | GET https://api.staging.vitesse.io/v1/payment-initiation/programmes |
| Production – UK Hub | GET https://api.vitesse.io/v1/payment-initiation/programmes |
| Production – US Hub | GET 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 scope | Identity client role |
|---|---|
programmes | programmes.viewer |
programmes | programmes.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.
| Parameter | When to use it |
|---|---|
ContinuationToken | Retrieve the next page. Use the token returned in the previous response. |
Name | Filter programmes by name. |
PageSize | Set the maximum number of programmes per page. The default is 10; the accepted range is 1 to 100. |
Status | Filter 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.
Updated 17 days ago