Request Formats

Request Format


act	always The type of event that happened, values can be payment_started, payment_updated, payment_confirmed
options	always The optional string that can be passed on the initial payment request. this can be null
reference_id	always Unique reference you your system (sessionid, paymentid). This is passed on the initial payment request.
payment_request_id	always The ID of the payment request received on the request-payment API request
payment_id	always The ID of the payment
status	conditional The status of the payment This is present on payment_updated act. Single Payments and QR Payments: COMPLETED, PENDING, FAILED.

Payment Status

Single Payments and QR / Link Payments
A payment can be considered successful when the status is COMPLETED. Initiation request has passed validation checks and been accepted by the Bank. Settlement is expected to happen in due course.

payment_confirmed act is triggered when we have the confirmation that the funds are received.

Verify Webhooks

You are able to verify that a webhook has been received from an authorised source. All webhooks you receive will have 2 additional headers, signature and application-key.

Obtaining the secret

You can go into the API Settings on the Payment Profile, and you will be able to see a "Callback secret", if you want to generate a new webhook secret, you can click the refresh icon.

Verifying the signature

$computedSignature = hash_hmac('sha256', file_get_contents('php://input'), $configuredSigningSecret);

Payment Started

This request will be executed when the user will select the bank

{
"act": "payment_started",
"options": "optional string",
"payment_id": 752,
"reference_id": "123456",
"payment_request_id": 537
}

This request will be executed when the user has processed the payment on their bank.

{
    "act": "payment_consent_received",
    "bank": "Starling Bank",
    "options": "This is the options string",
    "payment_id": 226,
    "reference_id": "123456",
    "payment_request_id": 383
}

Payment Completed

This request will be executed when the payment is completed.

{
  "act": "payment_completed",
  "payor": {
    "name": "Joe Bloggs",
    "sort_code": "123456",
    "account_number": "12345678"
  },
  "options": "optional string",
  "payment_id": 752,
  "reference_id": "123456",
  "transaction_id": 291,
  "payment_reference": "Vnd1C1Vnd",
  "payment_request_id": 537
}

Payment Confirmed

This request will be executed when Vendreo has the confirmation that the funds have reached your account.

{
  "act": "payment_confirmed",
  "bank": "Bank Name",
  "payor": {
    "name": "Joe Bloggs",
    "sort_code": "123456",
    "account_number": "12345678"
  },
  "options": "optional string",
  "payment_id": 752,
  "reference_id": "123456",
  "transaction_id": 291,
  "payment_reference": "Vnd1C1Vnd",
  "payment_request_id": 537
}

In order to receive the payment_confirmed request, you will need to grant Vendreo permission to access your bank account transactions list.

This permission will need to be renewed evey 90 days. You will be notified by email when the permission is due to renew.

Payment Failed

This request will be executed when Vendreo has the confirmation that the payment has failed.

{
    "act": "payment_failed",
    "reference_id": "123456",
    "payment_request_id": 537,
    "payment_reference": "Vnd1C1Vnd",
    "payment_id": 752,
    "options": "optional string"
}

Payment Cancelled

This request will be executed when the user cancelled the payment

{
    "act": "payment_cancelled",
    "options": "THIS is the options string",
    "payment_id": null,
    "reference_id": "123456",
    "payment_reference": "123456",
    "payment_request_id": 158
}

Outgoing Payment Failed

This request will be executed when Vendreo has the confirmation that the payment has failed.

{
  "act": "dynamic_payment_failed",
  "amount": 10,
  "status": "FAILED",
  "sort_code": "123456",
  "account_name": "Joe Bloggs",
  "payment_uuid": "b2ab0f2d-e8c5-41ab-a80b-ed786251de28",
  "account_number": "12345678"
}

Outgoing Payment Completed

This request will be executed when the payment is completed.

{
  "act": "dynamic_payment_completed",
  "amount": 10,
  "status": "COMPLETED",
  "sort_code": "123456",
  "account_name": "Joe Bloggs",
  "completed_at": "2022-05-09T13:42:45.000000Z",
  "payment_uuid": "b2ab0f2d-e8c5-41ab-a80b-ed786251de28",
  "account_number": "12345678"
}