Prioritise a Vendor Pay payment request
Prioritise a queued, scheduled payment request to give it precedence over other requests in the next batch when funds are limited.
Prioritising does not process the payment request immediately. To request immediate processing, see Process a scheduled payment request now.
Endpoints
| Environment | Method and URL |
|---|---|
| Staging | PUT https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests/{id}/prioritise |
| Production – UK Hub | PUT https://api.vitesse.io/v1/payment-initiation/paymentRequests/{id}/prioritise |
| Production – US Hub | PUT https://api.us.vitesse.io/v1/payment-initiation/paymentRequests/{id}/prioritise |
Replace {id} with the payment request's PaymentRequestId.
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
Get the request's PaymentRequestId. Use List payment requests or Search payment requests to find it.
Confirm that the request has Pending status, was created as a scheduled payment and is not already prioritised. Use Retrieve a payment request to check its status and existing prioritisation details.
Send the request
You must include a reason for prioritising the payment request. Choose a ReasonId from the list:
ReasonId | When to select it |
|---|---|
hardship | Delaying payment would cause serious financial difficulty or prevent someone from meeting an essential need. |
medical-emergency | The payment will cover urgent medical treatment, care or related costs. |
catastrophic-damage | The payment will fund recovery from major damage or loss, such as damage caused by a disaster. |
legal-regulatory | A legal, regulatory or court deadline requires you to make the payment promptly. |
customer-service | The payment will help resolve an urgent customer complaint, service failure or compensation issue. |
supplier-relationship-urgency | Prompt payment will protect an important supplier relationship or keep essential goods or services flowing. |
business-interruption | Prompt payment will help your business resume or maintain operations after a disruption. |
reputational-damage | A payment delay could damage trust in your organisation; prompt payment could limit that damage. |
other | None of the listed reasons fits. Explain why you want to prioritise the payment in Description. |
When ReasonId is other, you must include a Description (15 to 256 characters). Description is optional for the other reasons.
This example uses the Staging environment:
curl --request PUT \
--url 'https://api.staging.vitesse.io/v1/payment-initiation/paymentRequests/95a54a33-32cb-4415-94f7-607dc0fd1a6c/prioritise' \
--header 'Authorization: Bearer <access-token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"ReasonId": "medical-emergency",
"Description": "Urgent payment for a ski accident."
}'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 or 204 No Content. The response has no body.
Troubleshoot requests
If the request fails, use the returned HTTP status code to identify the likely cause and corrective action.
If the request returns 400 Bad Request, check that the PaymentRequestId is a valid ID, the ReasonId is in the list above, and any Description is within the allowed length. The request must have Pending status, is scheduled and is not already prioritised.
If the request returns 404 Not Found, check that the PaymentRequestId is correct and that you called the environment where the request exists.
For error response formats, additional HTTP status codes and error-handling guidance, see Error responses.
Next steps
Use Retrieve a payment request to confirm its PrioritisationDetails. Prioritising gives the payment request precedence in the next batch when funds are limited, but it does not process the payment request immediately. To request immediate processing, see Process a scheduled payment request now.
Subscribe to webhook events or retrieve the request using its PaymentRequestId to track its progress. Check its status to determine the outcome rather than submitting another payment.
For notifications, see Webhooks. For statuses and their meanings, see Payment lifecycle.
Updated 17 days ago