Documentation
User guideDeveloper guideAPI ReferenceContact
  1. API Guide
  2. Webhooks

Webhook subscription event reference

This section describes the webhook subscription events that are delivered by the Vitesse API.

For information about Transactions API webhooks, speak to Support.

Event Structure

Each webhook delivery contains a JSON object with the following structure:

{
  "EventId": "00000000-0000-0000-0000-000000000001",
  "EventType": "PaymentRequestInitiated",
  "TimestampUTC": "2026-07-30T00:00:12.345Z",
  "Data": { ... }
}
  • EventId – Unique identifier for the event (UUID)
  • EventType – The event name
  • TimestampUTC – Time at which the event was generated, in ISO 8601 format (UTC)
  • Data – Event-specific payload

Event Types

The following event types are available for webhook delivery.

Payment request events

Event TypeDescription
PaymentRequestInitiatedThe payment request has been successfully created and validated.
PaymentRequestTransactionCreatedThe payment request has originated a transaction, individually or as part of a batch.
PaymentRequestTransactionReturnedThe paid out transaction has been returned to Vitesse.
PaymentRequestSucceededThe payment request has been successfully processed and dispatched to the payout channel.
PaymentRequestCancelledThe payment request has been cancelled. This is a terminal state.
PaymentRequestFailedThe payment request has failed and will not be retried. This is a terminal state.
PaymentRequestsFittedBatchSucceededA batch transaction has been successfully executed, covering grouped payment requests.

See Payment request event payload examples below for more information.

Recipient capture events

Event TypeDescription
RecipientCaptureInitiatedThe recipient capture process has been initiated.
RecipientCaptureBlockedFive incorrect passphrase attempts have been recorded.
RecipientCaptureSecureLinkOpenedThe payee has opened the secure recipient capture link.
RecipientCaptureCompletedThe recipient capture process has been completed with valid payment details.
RecipientCaptureReminderTriggeredA reminder has been triggered for the capture process.
RecipientCaptureExpiredThe recipient capture process has expired without completion.
RecipientCaptureCancelledThe recipient capture process has been cancelled, explicitly or due to the payment being cancelled.
RecipientCaptureDeclinedThe recipient has declined to provide details via the capture process.
RecipientCaptureVerificationAttemptFailedA verification attempt failed (for example, identity or bank validation).

See Recipient Capture event payload examples below for more information.

Cheque events

Event TypeDescription
ChequeIssuedA cheque payment was sent.
ChequeCashedVitesse has received confirmation that a cheque was cashed.
ChequeUncashedA cheque payment has entered the “Uncashed” status.
ChequeVoidedA Cheque Void request has completed successfully.
ChequeVoidRequestCreatedA Cheque Void request has been manually created using the Vitesse portal.
ChequeVoidRequestApprovedA Cheque Void request has been manually approved using the Vitesse portal, and will be processed.
ChequeVoidRequestRejectedA Cheque Void request has been rejected.
ChequeVoidRequestCancelledA Cheque Void request has been cancelled.

See Cheque event payload examples below for more information.

Event examples

The examples below show representative webhook deliveries. All webhook events follow the standard event structure described above. The Data object may include additional fields, depending on configuration.

Payment request event payload examples

PaymentRequestInitiated

{
  "EventId": "00000000-0000-0000-0000-000000000091",
  "EventType": "PaymentRequestInitiated",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "PaymentRequestId": "b9fbfa0e-881f-45f2-bbd3-11d9f5f741c0",
    "SendAccountId": 1234,
    "PaymentMethod": "BankAccount",
    "SendValue": 100.00,
    "SendCurrency": "GBP",
    "ReceiveCurrency": "GBP",
    "Recipient": {
      "Type": "Person",
      "Name": "Bianca Kingsley",
      "PhoneNumber": "+12025550183",
      "Email": "[email protected]",
      "Country": "GB",
      "Capture": {
        "ProgrammeId": "04133b6f-03da-4e63-aec8-e1450b6a72db",
        "TrustMethods": [
          {
            "TrustMethodId": "policy-number",
            "Value": "POL123"
          }
        ],
        "AllowedPaymentMethods": [
          "Card",
          "BankAccount"
        ]
      }
    },
    "RecipientReference": "REF-10234",
    "PaymentDescription": "Claim reimbursement",
    "ExternalReference1": "POL-998877",
    "ExternalReference2": "CLM-123456",
    "ExternalReference3": "CASE-ABC-2025",
    "Extra": {},
    "Originator": {
      "Name": "Insurance Services Ltd",
      "Address": "1 Example Place, London EC2Y 5AU, United Kingdom",
      "Identifier": "GB-REG-09234567"
    },
    "Status": "Initiated"
  }
}

PaymentRequestTransactionCreated

{
  "EventId": "00000000-0000-0000-0000-000000000859",
  "EventType": "PaymentRequestTransactionCreated",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "PaymentRequestId": "6492a759-6237-4735-9c5b-7b394e82ebb6",
    "ExternalReference1": "POL-998900",
    "ExternalReference2": "CLM-456001",
    "ExternalReference3": "CASE-DEF-2025",
    "TransactionRequestId": "cbf775cb-7d3c-4bfc-88db-da97ef129f96"
  }
}

PaymentRequestTransactionReturned

{
  "EventId": "00000000-0000-0000-0000-000000000311",
  "EventType": "PaymentRequestTransactionReturned",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "PaymentRequestId": "6492a759-6237-4735-9c5b-7b394e82ebb6",
    "TransactionRequestId": "cbf775cb-7d3c-4bfc-88db-da97ef129f96",
    "ReturnedAt": "2025-07-30T00:00:13.345Z"
  }
}

PaymentRequestSucceeded

{
  "EventId": "00000000-0000-0000-0000-000000000641",
  "EventType": "PaymentRequestSucceeded",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "PaymentRequestId": "6492a759-6237-4735-9c5b-7b394e82ebb6",
    "ExternalReference1": "POL-554600",
    "ExternalReference2": "CLM-103425",
    "ExternalReference3": "CASE-GHI-2025",
    "Extra": {},
    "TransactionRequestId": "cbf775cb-7d3c-4bfc-88db-da97ef129f96",
    "RoutingDetails": {
      "SendCurrency": "GBP",
      "SendValue": 1,
      "ReceiveCurrency": "USD",
      "ReceiveValue": 1.23,
      "RateGroupId": 123,
      "Rate": 1.23
    }
  }
}

PaymentRequestCancelled

{
  "EventId": "00000000-0000-0000-0000-000000000355",
  "EventType": "PaymentRequestCancelled",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "PaymentRequestId": "6492a759-6237-4735-9c5b-7b394e82ebb6",
    "CancellationDetails": {
      "ReasonId": "ReasonId",
      "Description": "Description"
    }
  }
}

PaymentRequestFailed

{
  "EventId": "00000000-0000-0000-0000-000000000119",
  "EventType": "PaymentRequestFailed",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "PaymentRequestId": "6492a759-6237-4735-9c5b-7b394e82ebb6",
    "MerchantId": "04133b6f-03da-4e63-aec8-e1450b6a72db",
    "FailedAt": "2025-07-30T00:00:12.678Z",
    "FailureReason": "TransactionFailed",
    "TransactionFailureType": "AmountAboveAccountLimit",
    "TransactionFailureReason": "The transaction amount of 205.00 GBP is above the account limit of 100.00 USD."
  }
}

PaymentRequestsFittedBatchSucceeded

{
  "EventId": "00000000-0000-0000-0000-000000000001",
  "EventType": "PaymentRequestsFittedBatchSucceeded",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "PaymentRequests": [
      {
        "PaymentRequestId": "6492a759-6237-4735-9c5b-7b394e82ebb6",
        "ExternalReference1": "POL-987654",
        "ExternalReference2": "CLM-564738",
        "ExternalReference3": "CASE-HIJ-2025"
      },
      {
        "PaymentRequestId": "ac39231a-272d-4591-b36e-cfc8d0683183",
        "ExternalReference1": "POL-102938",
        "ExternalReference2": "CLM-000123",
        "ExternalReference3": "CASE-CBA-2025"
      }
    ],
    "TransactionRequestId": "cbf775cb-7d3c-4bfc-88db-da97ef129f96",
    "RecipientReference": "2521202712",
    "PaymentDetails": {
      "Iban": "3801"
    },
    "RateGroupId": 4914815,
    "ExchangeRate": 1.18402
  }
}

Recipient Capture event payload examples

RecipientCaptureInitiated

{
  "EventId": "00000000-0000-0000-0000-000000009834",
  "EventType": "RecipientCaptureInitiated",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "RecipientCaptureId": "6492a759-6237-4735-9c5b-7b394e82ebb6",
    "ProgrammeId": "04133b6f-03da-4e63-aec8-e1450b6a72db",
    "Recipient": {
      "Type": "Person",
      "Name": "Jude Smith",
      "Email": "[email protected]",
      "PhoneNumber": "+12025550183"
    },
    "PaymentDetails": {
      "PaymentRequestId": "526800f1-287b-423a-9cd3-588e52c8f799",
      "Amount": 100.00,
      "Currency": "USD",
      "Country": "US",
      "PaymentReference": "REF-10234",
      "PaymentDescription": "Claim reimbursement",
      "ExternalReference1": "POL-993377",
      "ExternalReference2": "CLM-123456",
      "ExternalReference3": "CASE-ABC-2025"
    },
    "ExpireAt": "2025-08-25T00:00:12.345Z",
    "Link": "https://payee-choice.test.vitesse.io/link/5Ul6MHxrJU4Q8fX969bJnE6SMHaMbNjSYtKvGj"
  }
}

RecipientCaptureBlocked

{
  "EventId": "00000000-0000-0000-0000-000000001234",
  "EventType": "RecipientCaptureBlocked",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "RecipientCaptureId": "6492a759-6237-4735-9c5b-7b394e82ebb6",
    "ProgrammeId": "04133b6f-03da-4e63-aec8-e1450b6a72db",
    "PaymentRequestId": "526800f1-287b-423a-9cd3-588e52c8f799",
    "BlockedAt": "2025-07-30T00:00:13.345Z",
    "Reason": "Reason",
    "VerificationMethodName": "VerificationMethodName"
  }
}

RecipientCaptureSecureLinkOpened

{
  "EventId": "00000000-0000-0000-0000-000000007684",
  "EventType": "RecipientCaptureSecureLinkOpened",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "RecipientCaptureId": "6492a759-6237-4735-9c5b-7b394e82ebb6",
    "PaymentRequestId": "526800f1-287b-423a-9cd3-588e52c8f799",
    "ClientInfo": {
      "UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "IpAddress": "83.27.12.74",
      "Referer": "http://mailchimp.com",
      "Accept-Language": "en-GB,en-US"
    },
    "OpenedAt": "2025-07-30T08:00:13.345Z",
    "Link": "https://payee-choice.test.vitesse.io/link/5Ul6MHxrJU4Q8fX969bJnE6SMHaMbNjSYtKvGj"
  }
}

RecipientCaptureCompleted

{
  "EventId": "00000000-0000-0000-0000-000000001432",
  "EventType": "RecipientCaptureCompleted",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "RecipientCaptureId": "6492a759-6237-4735-9c5b-7b394e82ebb6",
    "PaymentRequestId": "526800f1-287b-423a-9cd3-588e52c8f799",
    "SelectedPaymentMethod": "Card",
    "Link": "https://payee-choice.test.vitesse.io/link/5Ul6MHxrJU4Q8fX969bJnE6SMHaMbNjSYtKvGj"
  }
}

RecipientCaptureReminderTriggered

{
  "EventId": "00000000-0000-0000-0000-000000008695",
  "EventType": "RecipientCaptureReminderTriggered",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "RecipientCaptureId": "6492a759-6237-4735-9c5b-7b394e82ebb6",
    "PaymentRequestId": "526800f1-287b-423a-9cd3-588e52c8f799",
    "ReminderNo": 1,
    "Channel": "Email",
    "ExpireAt": "2025-08-25T00:00:12.345Z",
    "Link": "https://payee-choice.test.vitesse.io/link/5Ul6MHxrJU4Q8fX969bJnE6SMHaMbNjSYtKvGj"
  }
}

RecipientCaptureExpired

{
  "EventId": "00000000-0000-0000-0000-000000002432",
  "EventType": "RecipientCaptureExpired",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "RecipientCaptureId": "6492a759-6237-4735-9c5b-7b394e82ebb6",
    "PaymentRequestId": "526800f1-287b-423a-9cd3-588e52c8f799",
    "Link": "https://payee-choice.test.vitesse.io/link/5Ul6MHxrJU4Q8fX969bJnE6SMHaMbNjSYtKvGj",
    "ExpireAt": "2025-08-25T00:00:12.345Z"
  }
}

RecipientCaptureCancelled

{
  "EventId": "00000000-0000-0000-0000-000000006748",
  "EventType": "RecipientCaptureCancelled",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "RecipientCaptureId": "6492a759-6237-4735-9c5b-7b394e82ebb6",
    "PaymentRequestId": "526800f1-287b-423a-9cd3-588e52c8f799",
    "Link": "https://payee-choice.test.vitesse.io/link/5Ul6MHxrJU4Q8fX969bJnE6SMHaMbNjSYtKvGj"
  }
}

RecipientCaptureDeclined

{
  "EventId": "00000000-0000-0000-0000-000000003455",
  "EventType": "RecipientCaptureDeclined",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "RecipientCaptureId": "6492a759-6237-4735-9c5b-7b394e82ebb6",
    "PaymentRequestId": "526800f1-287b-423a-9cd3-588e52c8f799",
    "Link": "https://payee-choice.test.vitesse.io/link/5Ul6MHxrJU4Q8fX969bJnE6SMHaMbNjSYtKvGj",
    "DeclineAt": "2025-07-30T00:00:13.345Z"
  }
}

RecipientCaptureVerificationAttemptFailed

{
  "EventId": "00000000-0000-0000-0000-000000008761",
  "EventType": "RecipientCaptureVerificationAttemptFailed",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "RecipientCaptureId": "6492a759-6237-4735-9c5b-7b394e82ebb6",
    "PaymentRequestId": "526800f1-287b-423a-9cd3-588e52c8f799",
    "VerificationType": "Passphrase",
    "FailedAt": "2025-07-30T00:00:13.345Z",
    "Code": {
      "Channel": "Email"
    },
    "Passphrase": {
      "Id": "f917b317-2c90-4eee-bb0f-5c3026b3d741",
      "Name": "BOL",
      "ValueProvided": "123456",
      "AttemptNumber": 1
    }
  }
}

Cheque event payload examples

ChequeIssued

📘

Postal cheque events include the recipient mailing address. eCheck events include the recipient email address instead.

For Postal Cheque:
{
  "EventId": "00000000-0000-0000-0000-000000000001", 
  "EventType": "ChequeIssued",
  "TimestampUTC": "2025-07-30T00:00:123456Z",
  "Data": {
   "TransactionRequestId": "00000000-0000-0000-0000-000000000789",
    "ChequeNumber": "123",
    "IssuedOn": "2026-01-19T13:33:11.535Z",
    "AutoVoidAfter": "2026-02-18T13:33:11.535Z",
    "Address": {
      "StreetName": "Wall St.",
      "BuildingNumber": "1 A",
      "PostCode": "10005",
      "TownName": "New York",
      "CountrySubDivision": "NY",
      "Country": "US",
      "AddressLines": [
        "Suite 123"
      ]
    },
    "Email": null,
    "ChequeType": "PostalCheque"
  }
}
For eCheque:
{
  "EventId": "00000000-0000-0000-0000-000000000001", 
  "EventType": "ChequeIssued",
  "TimestampUTC": "2025-07-30T00:00:123456Z",
  "Data": {
    "TransactionRequestId": "00000000-0000-0000-0000-000000000678",
    "ChequeNumber": "400",
    "IssuedOn": "2026-01-19T08:44:28.425Z",
    "AutoVoidAfter": "2026-02-18T08:44:28.425Z",
    "Address": null,
    "Email": "[email protected]",
    "ChequeType": "ECheque"
  }
}

ChequeCashed

{
  "EventId": "00000000-0000-0000-0000-0000000005641",
  "EventType": "ChequeCashed",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "TransactionRequestId": "00000000-0000-0000-0000-000000000789",
    "UpdatedOn": "2025-07-30T00:00:12.345Z"
  }
}

ChequeUncashed

{
  "EventId": "00000000-0000-0000-0000-000000000675",
  "EventType": "ChequeUncashed",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "TransactionRequestId": "00000000-0000-0000-0000-000000000678",
    "UpdatedOn": "2025-07-30T00:00:12.345Z"
  }
}

ChequeVoided

{
  "EventId": "00000000-0000-0000-0000-000000000987",
  "EventType": "ChequeVoided",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "TransactionRequestId": "00000000-0000-0000-0000-000000000567",
    "UpdatedOn": "2025-07-30T00:00:12.345Z"
  }
}

ChequeVoidRequestCreated

{
  "EventId": "00000000-0000-0000-0000-000000000342",
  "EventType": "ChequeVoidRequestCreated",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "TransactionRequestId": "00000000-0000-0000-0000-000000000456",
    "CreatedOn": "2025-07-30T00:00:12.345Z"
  }
}

ChequeVoidRequestCancelled

{
  "EventId": "00000000-0000-0000-0000-000000000765",
  "EventType": "ChequeVoidRequestCancelled",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "TransactionRequestId": "00000000-0000-0000-0000-000000000345",
    "CreatedOn": "2025-07-30T00:00:12.345Z"
  }
}

ChequeVoidRequestRejected

{
  "EventId": "00000000-0000-0000-0000-000000000432",
  "EventType": "ChequeVoidRequestRejected",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "TransactionRequestId": "00000000-0000-0000-0000-000000000234",
    "CreatedOn": "2025-07-30T00:00:12.345Z"
  }
}

ChequeVoidRequestApproved

{
  "EventId": "00000000-0000-0000-0000-000000000321",
  "EventType": "ChequeVoidRequestApproved",
  "TimestampUTC": "2025-07-30T00:00:12.345Z",
  "Data": {
    "TransactionRequestId": "00000000-0000-0000-0000-000000000123",
    "CreatedOn": "2025-07-30T00:00:12.345Z"
  }
}

Updated 10 days ago

Related information