List cancellation reasons

Retrieve the cancellation reason IDs and names available for payment requests. Use a returned ReasonId in a cancellation request.

Endpoints

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

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.

Send the request

This example uses the Staging environment:

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

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 and a Data array containing each available cancellation reason ID and name. The following abridged example shows three cancellation reasons:

{
  "Data": [
    {
      "ReasonId": "claim-status-change",
      "Name": "Change in claim status"
    },
    {
      "ReasonId": "client-request",
      "Name": "Client requested cancellation"
    },
    {
      "ReasonId": "duplicate",
      "Name": "Duplicate payment"
    }
...
  ]
}

For more information, see Cancel a payment​.

Troubleshoot requests

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

For a 401 Unauthorized response, check that the access token is valid and contains the correct scope. For a 403 Forbidden response, check that the identity client has the correct role.

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

Next steps

Use a returned ReasonId in the ReasonId field when cancelling a payment. For instructions, see Cancel a payment.