Update a programme
Use the Vitesse API to change a programme's configuration. You can update the entire programme or target a specific section, such as its details, eligible accounts, verification methods, trust methods, notification settings or branding.
Endpoints
Choose the base URL for your environment, then append the path for the operation you want to use.
| Environment | Base URL |
|---|---|
| Staging | https://api.staging.vitesse.io/v1/payment-initiation |
| Production – UK Hub | https://api.vitesse.io/v1/payment-initiation |
| Production – US Hub | https://api.us.vitesse.io/v1/payment-initiation |
For help choosing an environment, see Environment.
| Operation | Method and path |
|---|---|
| Update a programme | PUT /programmes/{id} |
| Update programme details | PUT /programmes/{id}/details |
| Update eligible accounts | PUT /programmes/{id}/eligibleAccounts |
| Update verification methods | PUT /programmes/{id}/eligibleVerificationMethods |
| Update trust methods | PUT /programmes/{id}/eligibleTrustMethods |
| Update notification settings | PUT /programmes/{id}/notificationSettings |
| Update branding | PUT /programmes/{id}/branding |
For example, to update branding in Staging, send a PUT request to https://api.staging.vitesse.io/v1/payment-initiation/programmes/{id}/branding
Replace {id} with the programme's ID.
Access requirements
Configure the following access:
| OAuth scope | Identity client role |
|---|---|
programmes | programmes.manager |
For more information about scopes, see Authentication. For information about the access granted by specific roles, see Identity client roles.
Query parameters
| Parameter | When to use it |
|---|---|
IsDraft | Required. Set to true to create the programme as a draft or false to create it as a non-draft programme. |
Before you begin
- Get the programme's
ProgrammeId. Use List programmes to find it. - If you are updating eligible accounts, get their
AccountIdvalues using List account details.
Send the request
These examples use the Staging environment.
Update a programme
curl --request PUT \
--url 'https://api.staging.vitesse.io/v1/payment-initiation/programmes/4f8a2c31-6d7e-4b90-a123-9c5d7e8f2a61' \
--header 'Authorization: Bearer <access-token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"Name": "UK Motor Claims",
"Description": "Payment journey for UK motor insurance claim settlements",
"EligiblePaymentMethods": [
"BankAccount"
],
"EligibleAccountIds": [
3761
],
"EligibleVerifications": [
{
"VerificationMethodType": "Code",
"Code": {
"Channels": [
"Sms"
]
},
"Passphrase": null,
"IsDefault": true
}
],
"EligibleTrustMethods": [
{
"TrustMethodId": "claim-number",
"Name": "Claim number",
"IsMandatory": true,
"Instructions": "Enter the claim number shown in your settlement letter."
}
],
"Branding": {
"InsurerName": "Northstar Motor Insurance",
"ClaimAdministratorName": "Northstar Claims",
"LogoUrl": "https://assets.northstar.example/logo.svg",
"Instructions": "Contact Northstar Claims if you need help with your payment.",
"PhoneNumber": "01632 960123",
"EmailAddress": "[email protected]",
"WebUrl": "https://www.northstar.example/claims",
"BrandingColours": {
"HeaderColour": "#17324D",
"PrimaryColour": "#007A78"
}
},
"AdditionalSettings": {
"LinkExpirationPeriodInDays": 7
},
"NotificationSettings": {
"ReminderNotifications": [
{
"Channel": "Sms",
"RemindAfter": "1d"
}
],
"RecipientDetailsNeededNotification": {
"Channels": [
"Email"
]
},
"RecipientDetailsReceivedNotification": {
"Channels": [
"Email"
]
},
"TransactionSucceededNotification": {
"Channels": [
"Email"
]
}
},
"AcceptanceNarrative": {
"Message": "By accepting this offer, you agree to the settlement amount for your motor claim.",
"Active": true
}
}'Update programme details
curl --request PUT \
--url 'https://api.staging.vitesse.io/v1/payment-initiation/programmes/4f8a2c31-6d7e-4b90-a123-9c5d7e8f2a61/details?IsDraft=false' \
--header 'Authorization: Bearer <access-token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"Name": "UK Motor Claims",
"Description": "Payment journey for UK motor insurance claim settlements",
"EligiblePaymentMethods": [
"BankAccount"
],
"AdditionalSettings": {
"LinkExpirationPeriodInDays": 7
},
"AcceptanceNarrative": {
"Message": "By accepting this offer, you agree to the settlement amount for your motor claim.",
"Active": true
}
}'Update eligible accounts
curl --request PUT \
--url 'https://api.staging.vitesse.io/v1/payment-initiation/programmes/4f8a2c31-6d7e-4b90-a123-9c5d7e8f2a61/eligibleAccounts?IsDraft=false' \
--header 'Authorization: Bearer <access-token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"EligibleAccountsIds": [
3761
]
}'Update verification methods
curl --request PUT \
--url 'https://api.staging.vitesse.io/v1/payment-initiation/programmes/4f8a2c31-6d7e-4b90-a123-9c5d7e8f2a61/eligibleVerificationMethods?IsDraft=false' \
--header 'Authorization: Bearer <access-token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"EligibleVerifications": [
{
"VerificationMethodType": "Code",
"Code": {
"Channels": [
"Sms"
]
},
"Passphrase": null,
"IsDefault": true
}
]
}'Update trust methods
curl --request PUT \
--url 'https://api.staging.vitesse.io/v1/payment-initiation/programmes/4f8a2c31-6d7e-4b90-a123-9c5d7e8f2a61/eligibleTrustMethods?IsDraft=false' \
--header 'Authorization: Bearer <access-token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"EligibleTrustMethods": [
{
"TrustMethodId": "claim-number",
"Name": "Claim number",
"IsMandatory": true,
"Instructions": "Enter the claim number shown in your settlement letter."
}
]
}'Update notification settings
curl --request PUT \
--url 'https://api.staging.vitesse.io/v1/payment-initiation/programmes/4f8a2c31-6d7e-4b90-a123-9c5d7e8f2a61/notificationSettings?IsDraft=false' \
--header 'Authorization: Bearer <access-token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"ReminderNotifications": [
{
"Channel": "Sms",
"RemindAfter": "1d"
}
],
"RecipientDetailsNeededNotification": {
"Channels": [
"Email"
]
},
"RecipientDetailsReceivedNotification": {
"Channels": [
"Email"
]
},
"TransactionSucceededNotification": {
"Channels": [
"Email"
]
}
}'Update branding
curl --request PUT \
--url 'https://api.staging.vitesse.io/v1/payment-initiation/programmes/4f8a2c31-6d7e-4b90-a123-9c5d7e8f2a61/branding?IsDraft=false' \
--header 'Authorization: Bearer <access-token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"InsurerName": "Northstar Motor Insurance",
"ClaimAdministratorName": "Northstar Claims",
"LogoUrl": "https://assets.northstar.example/logo.svg",
"Instructions": "Contact Northstar Claims if you need help with your payment.",
"PhoneNumber": "01632 960123",
"EmailAddress": "[email protected]",
"WebUrl": "https://www.northstar.example/claims",
"BrandingColours": {
"HeaderColour": "#17324D",
"PrimaryColour": "#007A78"
}
}'Replace <access-token> with a valid access token that contains the required scope, and any example values with your own details.
Include the JSON body required by that operation. Check the API Reference for the request schema for the operation you choose.
Troubleshoot requests
If the request fails, use the returned HTTP status code to identify the likely cause and corrective action.
Also check that the ProgrammeID is correct, that you used the path for the section you want to update, and that the request body matches that operation's schema. Ensure the access token contains the required scope and the identity client has the required role.
For error response formats, additional HTTP status codes and error-handling guidance, see Error responses.
Next steps
To check the saved configuration, see Retrieve a programme. To change its availability, see Activate or deactivate a programme.
Updated 18 days ago