Notifications

Virtual Accounts feature is available as a Private Beta version. Please contact your Customer Success Manager if you would like to access it.

Further reading on receiving notifications on Virtual Account event updates via webhook.

Notifications for Virtual Accounts

With virtual accounts, you have the choice to receive notifications when one of the following events occur:

Event Description eventType
Pay In Status Update Notification that a payment has been made into one of your accounts virtualAccount.payIn.status
Pay Out Status Update Notification that the status of one your payment requests has been updated virtualAccount.payOut.status
Account Status Update Notification that the status of one of your accounts has changed virtualAccount.account.status
Create Beneficiary Status Update Notification that processing of your beneficiary request has been completed and its status updated virtualAccount.createBeneficiary.status

You will need to subscribe to the types of the event you wish to receive notifications for and ensure your application is set up to receive them.

Pay In Status Notification

The Pay In Status Notification will be sent to you when a pay in has been successfully processed and funds have been settled into your account.

The eventPayload contains:

Property Data Type Description Notes
payment.id string Unique id of the payment -
payment.createdAt date-time Date and time that the payment was created -
payment.type string The type of payment Always PAY_IN
payment.paymentScheme string The payment scheme through which the payment was processed One of:
  • FASTER_PAYMENTS
  • SEPA_CREDIT
  • SEPA_INSTANT
  • SWIFT
  • SWIFT_EXPRESS
  • CHAPS
  • IAT
  • ACH
  • WIRE
payment.amount object The monetary value of the payment -
payment.amount.amount number The value -
payment.amount.currency string The ISO 4217 currency code -
payment.reference string Reference associated with the payment, as provided by the sender -
payment.status string Current status of the payment Always COMPLETED
payment.source object Details of payment sender / source -
payment.source.name string The name of the sender -
payment.source.address string The address of the sender -
payment.source.type string The type of payment source Always EXTERNAL
payment.source.accountIdentfications object Identifiers (e.g. IBAN, SORT_CODE) for the source account -
payment.source.
accountIdentifications[].type
string Identifier type (e.g. IBAN) -
payment.source.
accountIdentifications[].identificiation
string Identifier Value -
payment.destination object Details of the virtual account on which the pay in arrived -
payment.destination.type string The type of payment destination Always ACCOUNT
payment.destination.accountId string The id of the account the pay in has arrived on -
reconciledPaymentInitiationId string The id of the initiated Yapily Payment or Yapily Bulk Payment that instructed funds into the account Only present where the Pay In could be successfully reconciled to a previous Yapily Payment or Yapily Bulk Payment

An example notification is as follows:

Copy
Copied
{
   "id": "4b91e372-bcf7-450d-bfa1-a0572e36318c",
   "eventType": "virtualAccount.payIn.status",
   "applicationId": "4b445f6e-dad8-4382-b282-4ae54c72094b",
   "organisationId": "126fb315-db66-42a4-a292-2c3112dc47a3",
   "institutionId": null,
   "eventPayload": {
       "payment": {
           "id": "b9ecb137-1358-4c2e-8f0e-bfcd407cdb1b",
           "createdAt": "2022-07-06T16:24:11.49Z",
           "type": "PAY_IN",
           "paymentScheme": "FASTER_PAYMENTS",
           "amount": {
               "amount": 1.0,
               "currency": "GBP"
           },
           "reference": "PAYIN-REF",
           "status": "COMPLETED",
           "source": {
               "name": "Test",
               "type": "ACCOUNT",
               "accountId": "709515f0-63d6-40f1-9336-f267a5984366",
               "address": "55-59 Wall St, New York, NY 10005, USA"
           },
           "destination": {
               "type": "ACCOUNT",
               "accountId": "899515f0-63d6-40f1-9336-f267a5984367"
           }
       },
       "reconciledPaymentInitiationId": "1e4b7830-3c79-44d6-ad10-bb2b7e2ab14f"
   },
   "objectId": "5a43119c-4509-42ae-8944-ebdcb8154998",
   "consentToken": null,
   "created": "2022-07-05T06:27:04.268Z",
   "url": "https://webhook.site/a683440a-38ae-4cc3-a44a-5131152f8664",
   "notificationStatus": "DELIVERED"
}

Pay Out Status Notification

The Pay Out Status Notification will be sent to you when a Pay Out that you have previously requested has undergone a change in status.

The eventPayload contains:

Property Data Type Description Notes
payment.id string Unique id of the payment -
payment.createdAt date-time Date and time that the payment was created -
payment.paymentDate date Date on which the payment instruction will be executed, that may be in the future -
payment.type string The type of payment Always PAY_IN
payment.paymentScheme string The payment scheme through which the payment was processed One of:
  • FASTER_PAYMENTS
  • SEPA_CREDIT
  • SEPA_INSTANT
  • SWIFT
  • SWIFT_EXPRESS
  • CHAPS
  • IAT
  • ACH
  • WIRE
payment.amount object The monetary value of the payment -
payment.amount.amount number The value -
payment.amount.currency string The ISO 4217 currency code -
payment.reference string Reference associated with the payment, and that was sent to the beneficiary -
payment.status string Current status of the payment One of:
  • INITIATED
  • PROCESSING
  • COMPLETED
  • FAILED
payment.source object Details of payment sender / source -
payment.source.type string The type of payment source Always ACCOUNT
payment.source.accountId object The unique id of the virtual account from which the payment was made -
payment.destination object Details of the beneficiary of the payment -
payment.destination.type string The type of payment destination Always BENEFICIARY
payment.destination.beneficiaryId string The id of the beneficiary of the payment -

An example notification is as follows:

Copy
Copied
{
   "id": "4b91e372-bcf7-450d-bfa1-a0572e36318c",
   "eventType": "virtualAccount.payOut.status",
   "applicationId": "4b445f6e-dad8-4382-b282-4ae54c72094b",
   "organisationId": "126fb315-db66-42a4-a292-2c3112dc47a3",
   "institutionId": null,
   "eventPayload": {
       "id": "b9ecb137-1358-4c2e-8f0e-bfcd407cdb1b",
       "createdDate": "2022-07-05T06:27:04.268Z",
       "type": "PAY_OUT",
       "paymentScheme": "FASTER_PAYMENTS",
       "amount": {
           "amount": 1.0,
           "currency": "GBP"
       },
       "reference": "PAYOUT-REF",
       "status": "COMPLETED",
       "source": {
           "type": "ACCOUNT",
           "accountId": "709515f0-63d6-40f1-9336-f267a5984366"
       },
       "destination": {
           "type": "ACCOUNT",
           "accountId": "899515f0-63d6-40f1-9336-f267a5984367",
           "beneficiaryId": "9a6289d7-3e82-4aba-ae79-26209004829d"
       }
   },
   "objectId": "5a43119c-4509-42ae-8944-ebdcb8154998",
   "consentToken": null,
   "created": "2022-07-05T06:27:04.268Z",
   "url": "https://webhook.site/a683440a-38ae-4cc3-a44a-5131152f8664",
   "notificationStatus": "DELIVERED"
}

Account Status Notification

The Account Status Notification will be sent to you when an account that you hold has undergone a change in status.

The eventPayload is the same account object that you would receive in a Get Account endpoint call.

Please note that the nested bankAccount object may not be returned when the status is not ACTIVE

An example notification is as follows:

Copy
Copied
{
   "id": "4b91e372-bcf7-450d-bfa1-a0572e36318c",
   "eventType": "virtualAccount.account.status",
   "applicationId": "4b445f6e-dad8-4382-b282-4ae54c72094b",
   "organisationId": "126fb315-db66-42a4-a292-2c3112dc47a3",
   "institutionId": null,
   "eventPayload": {
       "id": "26f23a4d-d936-4d84-893e-0c283bc1d94b",
       "createdDateTime": "2022-07-05T06:27:04.268Z",
       "status": "ACTIVE",
       "nickname": "Payments Test",
       "currency": "GBP",
       "balances": [
           {
               "type": "INTERIM_AVAILABLE",
               "balanceAmount": {
                   "amount": 0.0,
                   "currency": "GBP"
               }
           },
           {
               "type": "INTERIM_BOOKED",
               "balanceAmount": {
                   "amount": 0.0,
                   "currency": "GBP"
               }
           }
       ],
       "bankAccount": {
           "currency": "GBP",
           "bankName": "Simulator Bank",
           "bankAddress": "The Bower, 207-211 Old Street, London, England, EC1V 9NR",
           "bankCountry": "GB",
           "accountIdentifications": [
               {
                   "type": "SORT_CODE",
                   "identification": "040509"
               },
               {
                   "type": "IBAN",
                   "identification": "GB34SMLT04050900005568"
               },
               {
                   "type": "ACCOUNT_NUMBER",
                   "identification": "00005568"
               },
               {
                   "type": "BIC",
                   "identification": "SEOUGB21"
               }
           ]
       }
   },
   "objectId": "5a43119c-4509-42ae-8944-ebdcb8154998",
   "consentToken": null,
   "created": "2022-07-05T06:27:04.268Z",
   "url": "https://webhook.site/a683440a-38ae-4cc3-a44a-5131152f8664",
   "notificationStatus": "DELIVERED"
}

Create Beneficiary Notification

The Create Beneficiary Status Notification will be sent to you when the beneficiary creation has been finalised. This may result in the beneficiary being INACTIVE or ACTIVE.

The eventPayload is the same beneficiary object that you would receive in a Get Beneficiary endpoint call.

An example notification is as follows:

Copy
Copied
{
   "id": "4b91e372-bcf7-450d-bfa1-a0572e36318c",
   "eventType": "virtualAccount.createBeneficiary.status",
   "applicationId": "4b445f6e-dad8-4382-b282-4ae54c72094b",
   "organisationId": "126fb315-db66-42a4-a292-2c3112dc47a3",
   "institutionId": null,
   "eventPayload": {
       "id": "5a43119c-4509-42ae-8944-ebdcb8154998",
       "nickname": "Johns Account",
       "type": "INDIVIDUAL",
       "name": "Johns Account",
       "birthDate": "1999-01-01",
       "address": {
           "addressLine": "59 George Street",
           "townName": "WOLVERHAMPTON",
           "postCode": "WV80 0DF",
           "country": "GB"
       },
       "account": {
           "currency": "GBP",
           "bankName": "BANK OF IRELAND (UK) PLC",
           "bankAddress": "4-8 High Street ",
           "bankCountry": "GB",
           "accountIdentifications": [
               {
                   "type": "ACCOUNT_NUMBER",
                   "identification": "29823529"
               },
               {
                   "type": "BIC",
                   "identification": "BOFIGB2BXXX"
               },
               {
                   "type": "SORT_CODE",
                   "identification": "902127"
               },
               {
                   "type": "IBAN",
                   "identification": "GB27BOFI90212729823529"
               }
           ]
       },
       "status": "ACTIVE"
   },
   "objectId": "5a43119c-4509-42ae-8944-ebdcb8154998",
   "consentToken": null,
   "created": "2022-07-05T06:27:04.268Z",
   "url": "https://webhook.site/a683440a-38ae-4cc3-a44a-5131152f8664",
   "notificationStatus": "DELIVERED"
}