Validate an account movement

You can validate the details of an account movement before creating it, in order to identify problems.

Endpoints

EnvironmentMethod and URL
StagingPOST https://staging-api.vitessepsp.com/api/accountmovements/validate
Production – UK HubPOST https://api.vitessepsp.com/api/accountmovements/validate
Production – US HubPOST https://api.us.vitesse.io/api/accountmovements/validate

For help choosing an environment, see Environment.

Access requirements

Configure the following access:

OAuth scopeIdentity client role
APIAccountMovements.Create

For more information about scopes, see Authentication. For information about the access granted by specific roles, see Identity client roles.

Before you begin

Obtain an AccountId for each account: the account supplying the funds and the one receiving them.

Prepare the request details

  • Set DebitAccountId to the account supplying the funds.
  • Set CreditAccountId to the account receiving the funds.
  • Supply either DebitAmount or CreditAmount, but not both. Use DebitAmount to control how much leaves the debit account, or CreditAmount to control how much reaches the credit account.
  • Include PaymentReference, MerchantReference and Narrative to help you match the movement to your records.

If the accounts use different currencies, Vitesse calculates the corresponding debit or credit amount using the applicable exchange rate.

Send the request

📘

Validation does not create an account movement or transfer funds.

This example uses Staging and checks a request to debit 4873.29 in account 4152's currency and credit account 4111:

curl --request POST \
  --url 'https://staging-api.vitessepsp.com/api/accountmovements/validate' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "DebitAccountId": 4152,
  "CreditAccountId": 4111,
  "DebitAmount": 4873.29,
  "PaymentReference": "MOV-20261006-001",
  "MerchantReference": "CLAIMS-FUNDING-001",
  "Narrative": "Transfer funds between claims accounts"
}'

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

Expected response

A successful validation returns 200 OK without a response body. If Vitesse returns an error, correct the reported problem before creating the account movement.

Vitesse also performs checks during creation and approval. Successful validation does not guarantee that those later requests will succeed.

Troubleshoot the requests

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

If Vitesse returns AccountMovementDisabled, contact Support to check whether account movements are enabled for your organisation.

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

Next steps

After validation succeeds, create the account movement. See Create an account movement​.