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.

EnvironmentBase URL
Staginghttps://api.staging.vitesse.io/v1/payment-initiation
Production – UK Hubhttps://api.vitesse.io/v1/payment-initiation
Production – US Hubhttps://api.us.vitesse.io/v1/payment-initiation

For help choosing an environment, see Environment.

OperationMethod and path
Update a programmePUT /programmes/{id}
Update programme detailsPUT /programmes/{id}/details
Update eligible accountsPUT /programmes/{id}/eligibleAccounts
Update verification methodsPUT /programmes/{id}/eligibleVerificationMethods
Update trust methodsPUT /programmes/{id}/eligibleTrustMethods
Update notification settingsPUT /programmes/{id}/notificationSettings
Update brandingPUT /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 scopeIdentity client role
programmesprogrammes.manager

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

Query parameters

ParameterWhen to use it
IsDraftRequired. Set to true to create the programme as a draft or false to create it as a non-draft programme.

Before you begin

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.