Notifications

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

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 Notification that a payment has been made into one of your accounts virtualAccount.payIn.status
Pay Out Status Notification that the status of one your payment requests has been updated virtualAccount.payOut.status
Account Status Notification that the status of one of your accounts has changed virtualAccount.account.status
Create Beneficiary Status Notification that processing of your beneficiary request has been completed and its status updated virtualAccount.createBeneficiary.status
Client Status Notification that the status of one of your clients has changed virtualAccount.client.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

A Pay In Status notification is sent 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 -
paymentInitiationId string The id of the initiated Yapily Payment that instructed funds into the account Only present where the Pay In could be successfully reconciled to a previous Yapily Payment

Example notification:

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"
           }
       },
       "paymentInitiationId": "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

A Pay Out Status notification is sent 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 -

Example notification:

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

An Account Status notification is sent 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

Example notification:

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 Status

A Create Beneficiary Status notification is sent 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.

Example notification:

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

Client Status

A Client Status notification is sent when a client that you have onboarded has undergone a change in status.

The eventPayload is the same account object returned by the Get Clients endpoint for an individual or business client type.

Example notification (individual):

Copy
Copied
{
    "id": "0b0621da-c0e6-4f40-b85f-0422eeb868b7",
    "eventType": "virtualAccount.client.status",
    "applicationId": "4b445f6e-dad8-4382-b282-4ae54c72094b",
    "organisationId": "126fb315-db66-42a4-a292-2c3112dc47a3",
    "institutionId": null,
    "eventPayload": {
    "id": "dd0817e2-01eb-4544-9abe-1f59dffcc2ad",
    "type": "INDIVIDUAL",
    "kycStatus": "VERIFIED",
    "status": "ACTIVE",
    "createdDateTime": "2022-08-29T13:57:18.654Z",
    "individual": {
        "firstName": "Test1",
        "middleName": "Test2",
        "lastName": "Test3",
        "address": {
        "addressLine1": "Test 42",
        "addressLine2": "2-1",
        "townName": "Barcelona",
        "postCode": "08031",
        "country": "ES"
        },
        "birthDate": "1990-10-04",
        "email": "iHPTmge6Qu@example.com",
        "phone": "447956783777"
    }
    },
    "objectId": "dd0817e2-01eb-4544-9abe-1f59dffcc2ad",
    "consentToken": null,
    "created": "2022-08-29T16:30:04.853Z",
    "url": "https://webhook.site/0fddde9e-952f-4b7d-b7cc-fb200325db67",
    "notificationStatus": "DELIVERED"
}

Example notification (business):

Copy
Copied
{
  "id": "0b0621da-c0e6-4f40-b85f-0422eeb868b7",
  "eventType": "virtualAccount.client.status",
  "applicationId": "4b445f6e-dad8-4382-b282-4ae54c72094b",
  "organisationId": "126fb315-db66-42a4-a292-2c3112dc47a3",
  "institutionId": null,
  "eventPayload": {
    "id": "dd0817e2-01eb-4544-9abe-1f59dffcc2ad",
    "type": "BUSINESS",
    "kycStatus": "VERIFIED",
    "status": "ACTIVE",
    "createdDateTime": "2022-08-29T13:57:18.654Z",
    "business": {
      "name": "Test1",
      "type": "SOLE_TRADER",
      "registrationNumber": "12345",
      "registeredAddress": {
        "addressLine1": "Test 42",
        "addressLine2": "2-1",
        "townName": "Barcelona",
        "postCode": "08031",
        "country": "ES"
      },
      "tradingAddress": {
        "addressLine1": "Test 42",
        "addressLine2": "2-1",
        "townName": "Barcelona",
        "postCode": "08031",
        "country": "ES"
      },
      "contactName": "Test2",
      "email": "iHPTmge6Qu@example.com",
      "phone": "447956783777"
    }
  },
  "objectId": "dd0817e2-01eb-4544-9abe-1f59dffcc2ad",
  "consentToken": null,
  "created": "2022-08-29T16:30:04.853Z",
  "url": "https://webhook.site/0fddde9e-952f-4b7d-b7cc-fb200325db67",
  "notificationStatus": "DELIVERED"
}