Notifications for Virtual Accounts

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

Introduction

You can choose to receive notifications when one of the following events occurs on your virtual account:

Event Description eventTypeId
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
Pay Out return Notification that a pay out has been returned due to being rejected by the beneficiary bank virtualAccount.payOut.return
Refund status Notification that the status of one your refund requests has been updated virtualAccount.refund.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
note

You 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 is successfully processed and funds have settled into your account.

Table of eventPayload fields
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.

Table of eventPayload fields
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"
}

Pay Out return

A Pay Out return notification is sent when a Pay Out has been returned to your virtual account due to being rejected by the beneficiary bank.

Table of eventPayload fields
Property Data Type Description Notes
payment.id string Unique id of the payment -
payment.createdDate date-time Date and time that the payment was created -
payment.type string The type of payment Always RETURN_IN
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 BENEFICIARY
payment.source.beneficiaryId object The unique id of the beneficiary from which the payment was returned -
payment.destination object Details of the account to which the payment was returned -
payment.destination.type string The type of payment destination Always ACCOUNT
payment.destination.accountId string The id of the account to which the pay out was returned -
payment.originalPaymentId string The id of the original payment which has been returned -

Example notification:

Copy
Copied
{
  "id": "2f43e5b1-f6df-49b6-94ea-642b69146b20",
  "eventType": "virtualAccount.payOut.return",
  "applicationId": "4b445f6e-dad8-4382-b282-4ae54c72094b",
  "organisationId": "126fb315-db66-42a4-a292-2c3112dc47a3",
  "institutionId": null,
  "eventPayload": {
    "clientId": "5a7294ab-6b7d-4681-835a-f9b9775c75db",
    "payment": {
      "id": "53a71430-0ee5-4884-a22d-e32c78373a36",
      "createdDate": "2022-10-04T14:44:16.329Z",
      "type": "RETURN_IN",
      "amount": {
        "amount": 1,
        "currency": "GBP"
      },
      "reference": "Transaction returned",
      "status": "COMPLETED",
      "source": {
        "type": "BENEFICIARY",
        "beneficiaryId": "85f39962-08e8-4ea3-ba49-fd1d715f3b4f"
      },
      "destination": {
        "type": "ACCOUNT",
        "accountId": "5f03230f-a926-4c4f-87bd-25f453130944"
      },
      "originalPaymentId": "29e2680a-6fd8-42a7-b4f7-6797a2ef7e88"
    }
  },
  "objectId": "53a71430-0ee5-4884-a22d-e32c78373a36",
  "consentToken": null,
  "created": "2023-03-14T16:56:31.836Z",
  "url": "https://webhook.site/474ca4b0-2fe3-48bc-8cd5-2eb26babc072",
  "notificationStatus": "DELIVERED"
}

Refund status

A refund status notification is sent when the status of a refund has been updated.

The eventPayload is the same refund object you receive from Get Refund.

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":"46d3349e-6733-459d-a6da-71850a7e8076",   
        "originalPayment": {
            "paymentInitiationId": "abc"
        },
        "status": "INITIATED",
        "amount": {
            "amount": 10,
            "currency": "GBP"
        },
        "reason": "REQUESTED_BY_CUSTOMER",
        "paymentDate": "2022-08-28",
        "reference": "Refund 123",
        "beneficiaryType": "INDIVIDUAL",
        "createdDateTime": "2022-04-31T15:00:57.345Z",  
        "updatedDateTime": "2022-05-31T14:00:57.751Z"  
    },
    "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 contains core information regarding the account including its new status. It also includes the client-id that holds the account.

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": {
     "clientId": "4147dfe5-f4c4-5bbb-169a-516993691b66",
     "virtualAccount": {
        "id": "26f23a4d-d936-4d84-893e-0c283bc1d94b",
        "status": "ACTIVE",
        "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"
}