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
| Environment | Method and URL |
|---|---|
| Staging | POST https://api.staging.vitesse.io/v1/payment-initiation/storedRecipients |
| Production – UK Hub | POST https://api.vitesse.io/v1/payment-initiation/storedRecipients |
| Production – US Hub | POST 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 scope | Identity client role | Required for |
|---|---|---|
stored-recipients | stored-recipients.manager | Managing 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.
Updated 15 days ago