Manage stored recipients

Stored recipients allow you to save recipient details and reuse them when creating transactions.

Using stored recipients reduces the recipient data you send with each transaction request and simplifies recurring payment workflows.

📘

Vitesse validates stored recipient details when the recipient is created and again when the recipient is used in a transaction request. This ensures the recipient details remain valid against the current routing and validation rules.

For information about recipients, see Recipients.

Create a stored recipient

Creates a new stored recipient record.

POST /api/storedRecipient

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

About ExternalStoredRecipientId

ExternalStoredRecipientId is the optional external identifier that lets you associate a stored recipient in Vitesse with a corresponding recipient record in your own systems.

For example, you may use an internal payee ID, ERP identifier, GUID, or database key.

You can later use this value to retrieve or reference the stored recipient when creating transactions.

Example request

POST /api/storedRecipients
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "Name": "Victoria Lau",
  "Country": "GB",
  "Currency": "GBP",
  "ExternalStoredRecipientId": "PAYEE-782441",
  "Account": {
    "SortCode": "112233",
    "AccountNumber": "22233445"
  }
}

For full schema details, see Create stored recipient.

Example response

{
  "StoredRecipientId": "376184d2-d92d-49d0-8b99-fd7906885813",
  "Name": "Victoria Lau",
  "Country": "GB",
  "Currency": "GBP"
}

Retrieve a stored recipient

Retrieve the recipient using the internal Vitesse ID.

GET /api/storedrecipient/{id}

For full schema details, see Retrieve specific stored recipient using an internal ID.

You can also retrieve recipients using an external identifier.

GET /api/storedrecipient/{ExternalStoredRecipientId}

For full schema details, see Retrieve specific stored recipient using an external ID.

Update a stored recipient

Updates the stored recipient details. You must define the recipient in full, including fields that are unchanged.

PUT /api/storedrecipient/{id}

For full schema details, see Update an existing recipient.

Delete a stored recipient

Deletes the stored recipient record.

DELETE /api/storedrecipient/{id}

For full schema details, see Delete a stored recipient.

Use a stored recipient in a transaction request

After you create a stored recipient, you can reference it when creating a transaction.

You can reference stored recipients using either:

• StoredRecipientId – the internal Vitesse stored recipient ID
• ExternalStoredRecipientId – your own external recipient identifier

Example request

{
  "SendValue": 100.00,
  "SendCurrency": "EUR",
  "StoredRecipient": {
    "ExternalStoredRecipientId": "PAYEE-782441",
    "RecipientReference": "Claim-4312"
  }
}

Vitesse uses the stored recipient details to complete the transaction request before validating and processing the payment.