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. Periodic Payments: SCHEDULED, PENDING, FAILED.
date_scheduled	conditional The status estimate date of the next payment This is present on payment_updated act for periodic payments.

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.

Periodic Payments
A payment can be considered scheduled when the status is SCHEDULED. The estimate date of the first payment will be present on the callback request (date_scheduled)

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

First payment date is different for each bank and it can take up to 5 working days!

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 Scheduled

This request will be executed when the payment is scheduled.

{
"act": "payment_scheduled",
"reference_id": "123456",
"transaction_id": 291,
"payment_request_id": 537,
"payment_reference": "Vnd1C1Vnd",
"payment_id": 752,
"options": "optional string",
"date_scheduled": "1970-01-01 15:00:00",
}

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",
  "date_scheduled": "2022-05-18T09:14:48.000000Z",
  "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.

For Periodic Payments, this confirmation request will be executed evey time a new scheduled payment was completed (evey day, week or month)

Vendreo will not inform you if a Periodic Payment is cancelled or if the payment fails.

You will only be informed when the payment is successfully scheduled and if the funds reach your bank account

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"
}