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

Route types

The RouteType determines how a payment is delivered to the recipient. Vitesse supports multiple route types, including bank transfers, electronic cheques (eChecks), and physical postal cheques. Each route type has specific mandatory fields and validation rules.

If you do not specify a RouteType, the API defaults to BankAccount.

Route Type: BankAccount

BankAccount represents a standard bank transfer.

The required account details depend on the destination country and are defined in our Rules.

For example, when sending funds to the UK, you may provide either:

  • SortCode and AccountNumber, or
  • IBAN and SWIFT
{
  SendValue: 100.00,
  SendCurrency: 'EUR',
  Recipient: {
    Name: 'Alison Obi',
    RecipientReference: 'Claim-67493',
    Country: 'GB',
    Currency: 'GBP',
    Account: {
      SortCode: '112233',
      AccountNumber: '22233445'
    }
  },
  RouteType: 'BankAccount'
}

Cheque route types

📘

We support sending cheques in USD to recipients based in the US only.

We support two cheque delivery methods:

  • Cheque – An electronic cheque (eCheck), delivered via a secure link

  • PostalCheque – A physical cheque, printed and mailed

Each route type has distinct data requirements.

Cheque structured address format

For both eChecks and postal cheques, you must provide a valid structured US postal address using the fields defined in Structured postal address format (ISO 20022).

Route Type: Cheque

Cheque represents an electronic cheque (eCheck). We notify the recipient by email and provide a secure link to access the eCheck.

📘

For RouteType: "Cheque", the API also accepts the synonyms Check, ElectronicCheque, and ElectronicCheck. All values are normalised to Cheque for processing and reporting.

To send an eCheck, you must:

  • Provide the recipient’s email address
  • Include an empty Account object
  • Include a structured address
  • Specify a verification method (Passphrase or SmsCode)
    📘

    When using Passphrase, you must inform Vitesse in advance about which field to use as the secret.

    📘

    When using Smscode, you must include a mobile phone number in international format.

Bank account details are not required for eChecks.

Example: eCheck using passphrase verification
{
  SendValue: 250.00,
  SendCurrency: "GBP",
  Recipient: {
    Name: "Michael Thompson",
    Country: "US",
    Currency: "USD",
    RecipientReference: "Claim-45821",
    Email: "[email protected]",
    Account: {},
    Address: {
      StreetName: "Main Street",
      BuildingNumber: "742",
      TownName: "Springfield",
      PostCode: "62704",
      CountrySubDivision: "IL",
      Country: "US"
    }
  },
  ECheque: {
    Verification: {
      Type: "Passphrase",
      Passphrase: "<Secret>"
    }
  },
  RouteType: "Cheque"
}
Example: eCheck using SMS verification
{
  SendValue: 250.00,
  SendCurrency: "GBP",
  Recipient: {
    Name: "Michael Thompson",
    Country: "US",
    Currency: "USD",
    RecipientReference: "Claim-45821",
    Email: "[email protected]",
    PhoneNumber: "+15551234567",
    Account: {},
    Address: {
      StreetName: "Main Street",
      BuildingNumber: "742",
      TownName: "Springfield",
      PostCode: "62704",
      CountrySubDivision: "IL",
      Country: "US"
    }
  },
  ECheque: {
    Verification: {
      Type: "SmsCode"
    }
  },
  RouteType: "Cheque"
}

Route Type: PostalCheque

PostalCheque represents a a physical cheque that is printed and mailed to the recipient. For more information, see Issuing cheques.

To send a postal cheque, you must:

  • Provide a structured postal address
  • Include an empty Account object
Example
{
  "SendValue": 1250.00,
  "SendCurrency": "USD",
  "RouteType": "PostalCheque",
  "Recipient": {
    "Name": "Michael Thompson",
    "Country": "US",
    "Currency": "USD",
    "RecipientReference": "Claim-45821",
    "Account": {},
    "Address": {
      "StreetName": "Main Street",
      "BuildingNumber": "742",
      "TownName": "Springfield",
      "PostCode": "62704",
      "CountrySubDivision": "IL",
      "Country": "US"
    }
  }
}

If any mandatory address fields are missing or invalid, we reject the request and do not produce the cheque. The API error response includes validation details. For example, it will suggest values if the CountrySubDivision does not match a valid US state.

Example error response
{
  "Code": "ArgumentInvalid",
  "Message": "One or more arguments passed to the API call have an invalid value.",
  "MoreInfo": "https://docs.vitessepsp.com/reference/errors#argumentinvalid",
  "ModelState": {
    "request.Recipient.Address.CountrySubDivision": {
      "Errors": [
        {
          "ErrorMessage": "The value 'MAS' does not match any state in the US. The closest matches were 'Mass,MA,MS'"
        }
      ]
    }
  }
}

Optional fields in the Extra data field

The Extra object supports the same optional metadata fields defined in Issuing cheques.

{
  SendValue: 1250.00,
  SendCurrency: "GBP",
  Recipient: {
    Name: "Bennett Restoration Services",
    Country: "US",
    Currency: "USD",
    RecipientReference: "Property Damage Claim-45821",
    Account: {},
    Address: {
      StreetName: "Oak Avenue",
      BuildingNumber: "118",
      TownName: "Boston",
      PostCode: "02116",
      CountrySubDivision: "MA",
      Country: "US",
      Line1: "Suite 400",
      Line2: "Accounts Payable"
    }
  },
  ExternalReference1: "CLM-45821",
  RouteType: "PostalCheque",
  Extra: {
    "CLAIMANT NAME": "Michael Thompson",
    "CHECK DATE": "2026-02-15",
    "ADJUSTER": "James Carter",
    "DATE OF LOSS": "2026-01-12",
    "SERVICE DATES": "2026-01-20",
    "PAYEE NAME": "Bennett Restoration Services",
    "COMMENTS": "Property damage settlement paid directly to contractor.",
    "PERSONAL MESSAGE": "Please retain this cheque for your records."
  }
}

Updated 17 days ago

Related information