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
| Environment | Method and URL |
|---|---|
| Staging | PUT https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests/{id}/cancel |
| Production – UK Hub | PUT https://api.vitesse.io/v1/payment-initiation/paymentRequests/{id}/cancel |
| Production – US Hub | PUT 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 scope | Identity client role |
|---|---|
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.
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.
ReasonId | Use it when |
|---|---|
claim-status-change | A change in claim or case status means the payment is no longer required. |
client-request | The client or an authorised party has requested cancellation. |
duplicate | The payment request was submitted more than once for the same amount. |
expired | A Payee Choice or Vendor Pay request has expired because the recipient did not act within the designated period. |
incorrect-payee-details | The recipient's identity or beneficiary details are incorrect. |
incorrect-payment-details | The payment amount, currency or other payment details are incorrect. |
paid-via-alternate-means | The payment was already settled through another method or channel. |
system-issue | A technical issue prevented the payment from proceeding as intended. |
other | None 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.
Updated 17 days ago