Create an account movement

Create a request to transfer funds from one account to another. Specify the accounts and the amount you want Vitesse to debit or credit.

Vitesse creates the movement with a Pending status. You must approve it before Vitesse processes the transfer.

Endpoints

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

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.

Create the account movement

This example uses Staging and creates an account movement to debit 4873.29 from account 4152 in that account's currency, and credit account 4111:

📘

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

curl --request POST \
  --url 'https://staging-api.vitessepsp.com/api/accountmovements' \
  --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.

  • 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.

Expected response

A successful creation returns 201 Created with the account movement details.

Retain AccountMovementId so that you can approve, cancel or retrieve the account movement. Check the calculated debit and credit amounts, exchange rate and fee before approving it.

Approve the request before ExpiresOn. The default expiry period is 15 minutes. You cannot update an expired account movement.

Troubleshoot the requests

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

If Vitesse rejects either request, use the returned error details to identify what to correct.

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

To approve or cancel the request, use Approve or cancel an account movement. To check its status, use Retrieve an account movement.