List payment methods permitted for a programme

List payment methods permitted for a programme, country, currency and field scope. Vitesse filters the programme’s eligible payment methods against those supported for the requested combination.

Endpoints

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

For help choosing an environment, see Environment.

Access requirements

Configure at least one of the following access combinations:

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.

Query parameters

Provide all four parameters with each request.

ParameterDescription
ProgrammeIdThe ID of the programme whose permitted payment methods you want to retrieve.
CountryThe recipient’s country in ISO 3166-1 alpha-2 format, such as GB.
CurrencyThe payment currency in ISO 4217 format, such as GBP.
ScopesOne or more field scopes used to filter methods: Payment for payment fields, Bank for bank fields, Beneficiary for recipient fields, or All for all three. To pass multiple scopes, repeat the Scopes parameter.
Scopes is a query parameter for filtering payment methods. It is separate from the OAuth scope used for access.

Send the request

This example uses the Staging environment and requests permitted methods for a programme in the UK, using GBP and all field scopes:

curl --get \
  --url 'https://api.staging.vitesse.io/v1/payment-initiation/paymentMethods/listPermitted' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Accept: application/json' \
  --data-urlencode 'ProgrammeId=b5f4e4b7-437b-46ee-9b3d-6281a9f54ce1' \
  --data-urlencode 'Country=GB' \
  --data-urlencode 'Currency=GBP' \
  --data-urlencode 'Scopes=All'

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 permitted payment methods. The returned methods depend on the programme and the country, currency and scopes in the request.

{
  "Data": [
    "BankAccount"
  ]
}

Troubleshoot the request

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

Check that all four query parameters are present, the ProgrammeId is correct, and Country and Currency use valid ISO codes. Use at least one valid value for Scopes.

If Data is empty, check the programme's eligible payment methods and whether they are supported for the requested country, currency and field scopes.

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

Next steps

Use a returned payment method when making a payment. For Payee Choice, see Make a payment using Payee Choice.