Create a stored recipient

Create a stored recipient for a person or business. Include the recipient’s country, currency, payment method and the corresponding bank account details.

You can reuse this object in payment requests. Vitesse assigns a StoredRecipientId. Alternatively, you can provide an ExternalStoredRecipientId to connect the record to your own system.

Endpoints

EnvironmentMethod and URL
StagingPOST https://api.staging.vitesse.io/v1/payment-initiation/storedRecipients
Production – UK HubPOST https://api.vitesse.io/v1/payment-initiation/storedRecipients
Production – US HubPOST https://api.us.vitesse.io/v1/payment-initiation/storedRecipients

For help choosing an environment, see Environment.

Access requirements

Configure at least one of the following access combinations:

OAuth scopeIdentity client roleRequired for
stored-recipientsstored-recipients.managerManaging stored recipients, including listing, searching, retrieving details and history, retrieving search filters, creating and updating recipients, and activating, deactivating and archiving them.

For more information about scopes, see Authentication. For information about the access granted by specific roles, see Identity client roles.

Before you begin

Use Rules to check the country and currency available to your identity client. Gather the recipient details and the bank account fields required for the destination country.

Send the request

This example uses the Staging environment:

curl --request POST \
  --url 'https://api.staging.vitesse.io/v1/payment-initiation/storedRecipients' \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "Country": "GB",
    "Currency": "GBP",
    "Type": "Person",
    "Name": "Emma Thornton",
    "Email": "[email protected]",
    "PhoneNumber": "+442079460123",
    "PaymentMethod": "BankAccount",
    "BankAccountDetails": {
      "AccountNumber": "88877665",
      "SortCode": "112233"
    },
    "Address": {
      "StreetName": "High Street",
      "BuildingNumber": "10",
      "PostCode": "SW1A 1AA",
      "TownName": "London",
      "CountrySubDivision": "Greater London",
      "Country": "GB",
      "AddressLine1": "Flat 2"
    }
  }'

Replace <access-token> with a valid access token that contains the required scope, and any example values with your own details.

Type is either Person or Business. Supported PaymentMethod values are BankAccount, ECheck and PostalCheque. Include the person or business details that apply to the recipient.

Example response

A successful request returns 201 Created with the new recipient’s identifier and status:

{
  "StoredRecipientId": "7d978f47-1907-4d5d-8f85-8f40a96d21c8",
  "Status": "Active"
}

Use StoredRecipientId in subsequent stored recipient operations.

Troubleshoot requests

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

For error response formats, additional HTTP status codes and error-handling guidance, see Error responses.

Next steps

Use Retrieve a stored recipient to confirm the saved details.