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
| Environment | Method and URL |
|---|---|
| Staging | POST https://staging-api.vitessepsp.com/api/accountmovements |
| Production – UK Hub | POST https://api.vitessepsp.com/api/accountmovements |
| Production – US Hub | POST https://api.us.vitesse.io/api/accountmovements |
For help choosing an environment, see Environment.
Access requirements
Configure the following access:
| OAuth scope | Identity client role |
|---|---|
API | AccountMovements.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
DebitAccountIdto the account supplying the funds. -
Set
CreditAccountIdto the account receiving the funds. -
Supply either
DebitAmountorCreditAmount, but not both. UseDebitAmountto control how much leaves the debit account, orCreditAmountto control how much reaches the credit account. -
Include
PaymentReference,MerchantReferenceandNarrativeto 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.
Updated 17 days ago