Cancel a payment

Cancel a payment request while its status is Initiated, PendingApproval, Approved, InputNeeded, VendorOnboardingNeeded or Pending. You cannot cancel requests with other statuses. Include a reason so the cancellation is recorded.

Endpoints

EnvironmentMethod and URL
StagingPUT https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests/{id}/cancel
Production – UK HubPUT https://api.vitesse.io/v1/payment-initiation/paymentRequests/{id}/cancel
Production – US HubPUT https://api.us.vitesse.io/v1/payment-initiation/paymentRequests/{id}/cancel

Replace {id} with the payment request’s ID.

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.

Before you begin

Find the payment request with List payment requests. Use Retrieve a payment request to confirm its current status and check that it is eligible for cancellation.

Choose a valid ReasonId. For the available reasons, see List cancellation reasons.

ReasonIdUse it when
claim-status-changeA change in claim or case status means the payment is no longer required.
client-requestThe client or an authorised party has requested cancellation.
duplicateThe payment request was submitted more than once for the same amount.
expiredA Payee Choice or Vendor Pay request has expired because the recipient did not act within the designated period.
incorrect-payee-detailsThe recipient's identity or beneficiary details are incorrect.
incorrect-payment-detailsThe payment amount, currency or other payment details are incorrect.
paid-via-alternate-meansThe payment was already settled through another method or channel.
system-issueA technical issue prevented the payment from proceeding as intended.
otherNone of the listed reasons apply. You must include a Description of 15 to 256 characters.

Send the request

Include a valid access token in the Authorization header and provide the ReasonId in the request body.

This example uses the Staging environment and cancels a duplicate payment request:

curl --request PUT \
  --url 'https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests/95a54a33-32cb-4415-94f7-607dc0fd1a6c/cancel' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "ReasonId": "duplicate"
  }'

Replace <access-token> with a valid access token that contains the required scope, and any example values with your own details.

For ReasonId other, include a Description between 15 and 256 characters:

{
  "ReasonId": "other",
  "Description": "The payment is no longer required following a review."
}

Example response

A successful request returns 200 OK and sets the payment request's status to Cancelled.

{
  "Status": "Cancelled"
}

Troubleshoot requests

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

Check that the payment request is in an eligible status, and the ReasonId is valid.

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

Next steps

Use Retrieve a payment request to review the cancelled request. Use List payment requests to find other requests.