Stored recipients

Stored recipients let you securely manage and reuse payee information (such as bank account and address details) for repeat payments. Instead of including full recipient details in every payment request, you can reference a recipient you've previously stored using either:

• StoredRecipientId — a unique ID generated by Vitesse
• ExternalStoredRecipientId — your own custom identifier

This simplifies recurring payments, improves performance, and reduces the risk of data entry errors.

Create a stored recipient

To create a stored recipient, you must supply at minimum:

• Call:
  POST /api/storedRecipient

{
  "Name": "Emma Thornton",
  "Country": "GB",
  "Currency": "GBP",
  "Account": {
    "AccountNumber": "88877665",
    "SortCode": "112233"
  }
}

Optionally, you can include ExternalStoredRecipientId to link the stored recipient to an internal identifier in your own systems.

For full request and response schema details, see Create a stored recipient.

List all stored recipients

Retrieve a list of all stored recipients available to your account.

• Call:
  GET /api/storedRecipient

Use this endpoint to discover existing recipients and their identifiers before making payments or updates.

For full request and response schema details, see

Retrieve a specific stored recipient

Retrieve a single full stored recipient record, including account details and metadata.

• Call:
  GET /api/storedRecipient/{StoredRecipientId}

For full request and response schema details, see Create a stored recipient

Use a stored recipient in a payment request

When sending payments to a stored recipient, include the StoredRecipient object with either ID.

Only one of StoredRecipientId or ExternalStoredRecipientId should be provided.

Example

{
  "SendAccountId": 1234,
  "SendCurrency": "GBP",
  "ReceiveValue": 100,
  "ReceiveCurrency": "GBP",
  "PaymentMethod": "BankAccount",
  "StoredRecipient": {
    "StoredRecipientId": "00000000-0000-0000-0000-000000000001"
  },
  "RecipientReference": "Invoice #12345",
  "PaymentDescription": "Consulting fees"
}

Update a stored recipient

To update a stored recipient, call:

PUT /api/storedRecipient/{StoredRecipientId}

Partial updates are not supported. You must include the full updated object in the update.

Delete a stored recipient

To delete a stored recipient, call

DELETE /api/storedRecipient/{StoredRecipientId}

Best practices

• Use ExternalStoredRecipientId to align with your organisation's internal system identifiers.
• Validate stored recipient data using the Rules configuration to ensure required fields for each route (for example, IBAN or ABA code) are correct.
• Consider storing recipient metadata for reporting or reconciliation.