Documentation
User guideDeveloper guideAPI ReferenceContact
  1. API Guide
  2. Welcome to the Transaction API
  3. Administration

Manage recipients

You can provide recipient details directly in a transaction request, or reference a stored recipient using an external identifier. For more information, see Payment recipients.

Recipient details must satisfy the rules for the payment route, destination country, and currency. These rules determine which Account, Recipient and Address fields are required.

For information about how required fields are determined, see Rules.

To retrieve the applicable rules through the API, see Rules API.

Some countries and payment methods also require a recipient address. For information about address requirements, see Structured addresses.

Inline recipient

Include a Recipient object when you want to provide recipient details directly in the transaction request.

Example request (truncated)

POST https://staging-api.vitessepsp.com/api/transactionrequests

Request body:

{
  "SendValue": 100.00,
  "SendCurrency": "EUR",
  "Recipient": {
    "Name": "Victoria Lau",
    "Country": "GB",
    "Currency": "GBP",
    "RecipientReference": "Claim-51837",
    "Account": {
      "SortCode": "112233",
      "AccountNumber": "22233445"
    }
  }
}

Stored recipient

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

Each stored recipient is identified by an ExternalStoredRecipientId, which you use to create, retrieve, update, delete, and reference the recipient.

About ExternalStoredRecipientId

ExternalStoredRecipientId is a merchant-defined identifier that links the stored recipient in Vitesse to the corresponding recipient record in your own systems.

Choose a value that is meaningful within your organisation, such as an internal payee ID, ERP identifier, GUID, or database key.

Vitesse uses this identifier to locate the stored recipient in subsequent API requests, including when creating transactions.

Create a stored recipient

Creates a new stored recipient record.

POST /api/storedRecipient

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

Example request

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

Request body:

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

Example response (truncated)

{
  "ExternalStoredRecipientId": "PAYEE-782441",
  "Name": "Victoria Lau",
  "Country": "GB",
  "Currency": "GBP",
  "Type": "Person",
  "Status": "Approved"
}

List stored recipients

List all stored recipients for your organisation.

GET /api/storedRecipient

For full request and response details, see List stored recipients.

Example request

GET https://staging-api.vitessepsp.com/api/storedRecipient

Example response

[
  {
    "ExternalStoredRecipientId": "PAYEE-782441",
    "Name": "Victoria Lau",
    "Country": "GB",
    "Currency": "GBP",
    "Type": "Person",
    "Status": "Approved",
    "Account": {
      "SortCode": "112233",
      "AccountNumber": "22233445"
    },
    "UpdatedOn": "2026-06-03T10:15:00Z"
  },
  {
    "ExternalStoredRecipientId": "SUPPLIER-44521",
    "Name": "Northside Repairs Ltd",
    "Country": "GB",
    "Currency": "GBP",
    "Type": "Business",
    "Status": "Approved",
    "Account": {
      "SortCode": "223344",
      "AccountNumber": "66778899"
    },
    "UpdatedOn": "2026-06-02T14:20:00Z"
  }
]

Retrieve a stored recipient

Retrieve a stored recipient using the external stored recipient identifier.

GET /api/storedrecipient/{externalStoredRecipientId}

For full request and response details, see Retrieve stored recipient.

Example request

GET https://staging-api.vitessepsp.com/api/storedrecipient/PAYEE-782441

Example response (truncated)

{
  "StoredRecipientId": "376184d2-d92d-49d0-8b99-fd7906885813",
  "ExternalStoredRecipientId": "PAYEE-782441",
  "Name": "Victoria Lau",
  "Country": "GB",
  "Currency": "GBP",
  "Type": "Person",
  "Account": {
    "SortCode": "112233",
    "AccountNumber": "22233445"
  }
}

Update a stored recipient

Update a stored recipient using your external stored recipient identifier. You must define the recipient in full, including fields that are unchanged.

PUT /api/storedRecipient/{externalStoredRecipientId}

For full request and response details, see Update stored recipient.

When updating a stored recipient, provide the full recipient definition, including fields that have not changed.

Example request

PUT https://staging-api.vitessepsp.com/api/storedrecipient/PAYEE-782441

Request body:

{
  "Account": {
    "SortCode": "112233",
    "AccountNumber": "22233445"
  },
  "Address": {
    "AddressLine1": "22 Bishopsgate",
    "City": "London",
    "PostCode": "EC2N 4BQ",
    "Country": "GB"
  },
  "Birthdate": "1985-04-12T00:00:00Z",
  "Country": "GB",
  "Currency": "GBP",
  "Email": "[email protected]",
  "ExternalStoredRecipientId": "PAYEE-782441",
  "Name": "Victoria Lau",
  "Nationality": "GB",
  "PhoneNumber": "+447700900123",
  "ReferencePrefix": "CLM",
  "Type": "Person"
}

Example response (truncated)

{
  "ExternalStoredRecipientId": "PAYEE-782441",
  "Name": "Victoria Lau",
  "Country": "GB",
  "Currency": "GBP",
  "Email": "[email protected]",
  "PhoneNumber": "+447700900123",
  "Type": "Person",
  "Status": "Approved",
  "UpdatedOn": "2026-06-03T10:15:00Z"
}

Delete a stored recipient

Delete a stored recipient using the external stored recipient identifier.

DELETE /api/storedRecipient/{externalStoredRecipientId}

For full request and response details, see Delete stored recipient.

Example request

DELETE https://staging-api.vitessepsp.com/api/storedrecipient/PAYEE-782441

Example response

HTTP/1.1 200 OK

Use a stored recipient in a transaction request

After you create a stored recipient, you can reference it when creating a transaction, using the external stored recipient identifier.

Example request

POST https://staging-api.vitessepsp.com/api/transactionrequests

Request body:

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

Example response (truncated)

{
  "TransactionId": "ae6ca885-8694-4a96-9922-6451671e8603",
  "Status": "Pending",
  "SendCurrency": "EUR",
  "SendValue": 100.0,
  "Recipient": {
    "Name": "Victoria Lau",
    "Country": "GB",
    "Currency": "GBP",
    "RecipientReference": "Claim-4312"
  }
}

Vitesse retrieves the stored recipient details, then validates and processes the transaction.