Payment notifications

Payment notifications are currently available in Private Beta.

Introduction

You can subscribe to receive notifications when an event occurs on your initiated payments. This removes the need to manually poll the Get Payment Details endpoint to check the status of a payment.

Yapily currently offers payment notifications based on the initiation status of a payment.

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.

Events

The following event types are available:

Event Description eventTypeId
Payment Initiation Status Notification that the payment status has transitioned to COMPLETED or FAILED. payment.status
Payment Initiation Completed Notification that the payment status has transitioned to COMPLETED. payment.status.completed
Payment ISO Status Notification that the payment ISO status has changed. payment.isoStatus

Notes:

  • Notifications are for single payments only.
  • The payment status only has 1 status transition. The payment ISO status can have multiple status transitions.
  • Some exceptional institutions don't provide payment status updates.

Payload

Each event type has a common eventPayload. The payload contains the complete payment object.

For payment.status and payment.status.completed event types, the notification alerts to a change in the value of the status field.

For the payment.isoStatus event type, the notifications alert to a change in the statusDetails.isoStatus field. For more information about ISO status, see Processing & Execution Status.

Example payment notification:

Copy
Copied
{
   "id":"2124343e-7b92-4da8-8424-52c6a7e3a56d",
   "eventType":"PAYMENT_STATUS_COMPLETED",
   "applicationId":"d60ebb6f-8935-4e58-999c-966fe6a05ef5",
   "organisationId":"41a3c16b-11f5-43fa-90ff-eff63ecb8eeb",
   "institutionId":"mock-sandbox",
   "eventPayload":{
      "id":"PDC_35c0ab52-6cd0-4b98-ab78-9e2611151bb6",
      "institutionConsentId":"PDC_4e6d9667-baed-4437-b50a-29a24dd1cd56",
      "paymentIdempotencyId":"c23b0f0baa464dc781005cfc07e5aed4",
      "paymentLifecycleId":"4dea5e70cfc500187c",
      "status":"COMPLETED",
      "statusDetails":{
         "status":"COMPLETED",
         "statusUpdateDate":"2020-04-30T10:26:44.876Z",
         "isoStatus": {
            "code":"ACSC",
            "name":"AcceptedSettlementCompleted"
         }
      },
      "payeeDetails":{
         "name":"TestPayee",
         "accountIdentifications":[
            {
               "type":"SORT_CODE",
               "identification":"402502"
            },
            {
               "type":"ACCOUNT_NUMBER",
               "identification":"52461838"
            }
         ]
      },
      "reference":"n",
      "amount":10.0,
      "currency":"GBP",
      "amountDetails":{
         "amount":10.0,
         "currency":"GBP"
      },
      "createdAt":"2020-04-30T10:26:44.879Z"
   },
   "objectId":"PDC_35c0ab52-6cd0-4b98-ab78-9e2611151bb6",
   "consentToken":"eyJraWQiOiI3MmFmYjM5MS03MzRiLTQ4OTEtOWM4NC01OTgzODdiNmVkMWIiLCJhbGciOiJFUzI1NiJ9.eyJJTlNUSVRVVElPTiI6Im1vY2stc2FuZGJveCIsIkNPTlNFTlQiOiJmYTkxZWZmYy0yNzFiLTQ0ZGUtYmUxMC1kY2Y3ZmNiM2ZiMmQiLCJBUFBMSUNBVElPTl9VU0VSX0lEIjoidXNlcl8wLjQwNDQwOTgxODAxNzQ4MjY2IiwiVVNFUiI6Ijc1NGY0NTEzLTk2YmYtNDQyYy05MGUwLTc5OGMwNTZhNzYzNSJ9.q1lu8sfN2CfOILdyzm5949PI3quBZe0bRLZzpi-xZVBZviozXBiMXYhycigsHHeJkoC2NisBYwqfe5-GLD31aQ",
   "created":"2022-05-11T13:57:07.638Z",
   "url":"https://webhook.site/7304256a-14cb-413c-ac17-d6df48c3dc50",
   "notificationStatus":"DELIVERED"
}

Delivery

Yapily guarantees a payment will reach either a COMPLETED or FAILED status and therefore a notification will be delivered, unless there's an unexpected exception.

Yapily will attempt to send a notification to you immediately after the institution has updated the payment status.

The exact length of time before the delivery of a notification depends on how quickly an institution processes a payment and updates the payment status.

Note: Yapily currently timeouts notifications at 72 hours. If the payment status has not been updated in this time, a notification will not be delivered.

Unexpected exceptions could include:

  • the institution doesn't update the status of a payment as expected
  • the notification fails to deliver to you after retrying