Webhooks are a crucial mechanism for merchants to receive notifications about Account Verification creation and Account Verification status changes. All Account Verification webhooks have a webhook_type that begins with ACCOUNT_VERIFICATION_.

Webhook processing and Security

Yaspa Webhooks are sent via HTTPS and are signed. For information on processing and around Webhook security, see the section here - Webhooks.

Pay-in Webhook Events

Webhook	Description	Pay-in Transaction Status
`ACCOUNT_VERIFICATION_CREATED`	Account verification journey was created	`CREATED`
`ACCOUNT_VERIFICATION_REDIRECT`	The user has selected a bank and been redirected to that bank	`PENDING_USER_AUTHORISATION`
`ACCOUNT_VERIFICATION_DECISION`	Account verification journey was completed.	`ACCEPTED or CANCELLED or FAILED`
`ACCOUNT_VERIFICATION_ERROR`	An error occurred	`ERROR`

Account Verification Webhook payload and Parameters

The Account Verification webhooks are HTTPS post requests and a typical example of the request body is as follows:

{
  "type": "ACCOUNT_VERIFICATION_DECISION",
  "data": {
    "id": "68625365e58f37487929e820",
    "citizenTransactionId": "b2f0bbfa-f5c9-7047-b8fc-4b4c11",
    "merchantId": "67cb0ccd3790837e4659c60e",
    "merchantTradingName": "Stagecoach Alpha RP",
    "customerIdentifier": "mq5l1rkols20",
    "financialServiceProvider": "CITIZEN_TEST_BANK",
    "version": "2",
    "journeyType": "HOSTED_ACCOUNT_VERIFICATION",
    "transactionType": "ACCOUNT_VERIFICATION",
    "transactionStatus": "ACCEPTED",
    "creationDate": 1751274341597,
    "testParameters": {},
    "language": "en",
    "accounts": [
      {
        "id": "0daec12a-0958-452e-8be3-f2b80cd1517f",
        "accountName": "John Smith Current",
        "accountHolderName": "John Smith",
        "number": "12345678",
        "partialAccountNumber": "676",
        "sortCode": "040075",
        "iban": "GB71REVO00000000000000",
        "partialIban": "496",
        "bic": "REVOGB21",
        "balance": "10.00",
        "type": "CURRENT",
        "bank": "CITIZEN_TEST_BANK"
      },
      {
        "id": "4dc41311-4793-4841-aa66-73fb8a642fc9",
        "accountName": "John Smith Spend",
        "accountHolderName": "John Smith",
        "number": "87654321",
        "partialAccountNumber": "676",
        "sortCode": "123456",
        "iban": "GB71REVO00000000000001",
        "partialIban": "496",
        "bic": "REVOGB21",
        "balance": "10.00",
        "type": "CURRENT",
        "bank": "CITIZEN_TEST_BANK"
      }
    ]
   }
}

There will often be other parameters in the body, such as some of the optional parameters will be carried through the system, as such it's critically important merchant servers do not use strict mode parsing on the above JSON format, otherwise there will be failures to read data from Yaspa.

Parameter list:

Parameter	Description
citizenTransactionId	Citizen transaction ID
merchantId	The ID of your Merchant
merchantTradingName	The trading name of your Merchant
customerIdentifier	Customer ID in your system
transactionStatus	Current status of the transaction (e.g. `CREATED`)
creationDate	Date of creation
version	Version of the API
accounts.id	Account Id. This can be used for direct Payouts, to make payouts directly to this account.
accounts.accountName	Name of the account (eg Current/Credit)
accounts.accountHolderName	Name of the accountholder
accounts.number	bank account number (UK)
accounts.partialAccountNumber	Three digits of decrypted bank account number (UK)
accounts.sortCode	Bank account sort code (UK)
accounts.iban	IBAN (EU)
accounts.partialIban	Three digits decrypted of IBAN (EU)
accounts.bic	Bank identifier (EU, eg Swift code)
accounts.balance	Balance of the account
accounts.type	Account type
accounts.bank	Bank of the account

Pay-in Status

The events above each contain a status; the table below provides more details on what each status means.

TransactionStatus	Description	Terminal Status
CREATED	The journey has begun and the user is about to select the bank he want to verify the account from
PENDING_USER_AUTHORISATION	The user has selected the bank he wants to verify and has been redirected to his bank
PENDING_ASPSP_ACCEPTANCE	The request is processing from the bank
ACCEPTED	The transaction has been completed	Yes
CANCELLED	The transaction has been cancelled by the user	Yes
FAILED	The transaction failed	Yes
ERROR	An error occured processing the transaction	Yes