Search programme accounts
Search for accounts associated with an active programme. Filter the results by account properties to find an eligible account for a payment request.
Endpoints
| Environment | Method and URL |
|---|---|
| Staging | GET https://api.staging.vitesse.io/v1/payment-initiation/programmes/{id}/accounts/search |
| Production – UK Hub | GET https://api.vitesse.io/v1/payment-initiation/programmes/{id}/accounts/search |
| Production – US Hub | GET https://api.us.vitesse.io/v1/payment-initiation/programmes/{id}/accounts/search |
Replace {id} with the programme’s ProgrammeId.
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 |
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.
Search parameters
Use these parameters to page through accounts associated with a programme and optionally filter or sort them.
| Parameter | Type | Description |
|---|---|---|
id | String | The programme’s ProgrammeId. |
limit | Integer | Maximum number of accounts to return. Defaults to 10; must be between 1 and 100. |
offset | Integer | Number of matching accounts to skip. Defaults to 0; must be 0 or greater. |
query | String | Filter accounts using AccountId, MerchantCode, Name, Code, Alias, Currency, UpperPaymentLimit, SubAccountType, UpdatedAt or AccountBalance. For example, (Currency: "GBP") finds GBP accounts. Combine conditions to narrow results. For example Currency: "GBP" AND AccountBalance > 500 returns GBP accounts with a balance above 500. URL-encode the expression when sending the request. |
sortQuery | String | Sort results by a supported account field, such as Name asc. |
For example, use (Currency: "GBP") to find GBP accounts and Name desc to sort the results by name in descending order.
Before you begin
Get the programme’s ProgrammeId using Search programmes or List programmes. You can only search for accounts that are associated with an active programme.
Send the request
This example uses the Staging environment. It searches the specified programme’s eligible accounts for GBP accounts and sorts them by name:
curl --get \
--url 'https://api.staging.vitesse.io/v1/payment-initiation/programmes/4f8a2c31-6d7e-4b90-a123-9c5d7e8f2a61/accounts/search' \
--header 'Authorization: Bearer <access-token>' \
--header 'Accept: application/json' \
--data-urlencode 'query=(Currency: "GBP")' \
--data-urlencode 'sortQuery=Name asc' \
--data-urlencode 'limit=10' \
--data-urlencode 'offset=0'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 200 OK with a Data array of matching accounts and pagination details.
{
"Data": [
{
"AccountId": 3761,
"MerchantCode": "northstar",
"Name": "UK Motor Claims",
"Code": "UK-MOTOR-GBP",
"Alias": "UK motor",
"Currency": "GBP",
"AccountBalance": 125000.00,
"UpperPaymentLimit": 50000.00,
"UpperPaymentLimitCurrency": "GBP",
"SubAccountType": "Standard",
"FcpEnabled": false
}
],
"TotalCount": 1,
"Limit": 10,
"Offset": 0
}Troubleshoot requests
If the request fails, use the returned HTTP status code to identify the likely cause and corrective action.
Check that {id} is a valid ProgrammeId, that the programme is active, and that it has eligible accounts. Check that limit is between 1 and 100, offset is not negative, and the query and sortQuery use supported account fields. An empty Data array can mean the programme is inactive, has no eligible accounts, or none match the filters.
For error response formats, additional HTTP status codes and error-handling guidance, see Error responses.
Next steps
Use an AccountId from the results as the SendAccountId when creating a payment request that uses the programme. For instructions on how to create the payment request, see Make a payment using Payee Choice.
Updated 17 days ago