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:
|
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:
{
"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:
|
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:
|
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:
{
"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:
{
"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:
{
"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):
{
"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):
{
"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"
}