Skip to main content
Hosted Pages is available as a Beta version. Please contact your Customer Success Manager if you would like to access it.

​
Introduction

Webhooks are the recommended approach for monitoring the status of hosted payments. They provide real-time HTTP notifications when a payment completes successfully or fails, enabling you to reliably update your internal systems and customer journeys. Benefits of using webhooks:
  • Immediate status updates - Receive notifications as soon as the payment reaches a terminal state
  • Reduced API calls - No need to poll the GET endpoint repeatedly, resulting in cost savings for both parties
  • Better user experience - Provide faster feedback to your customers
While you can monitor payment status by polling the GET endpoint, webhooks provide a more efficient and scalable solution.

​
Webhook Registration

Before receiving webhook events, you must register a webhook for your application and subscribe to the relevant Hosted PIS webhook event types. Please follow the Webhook Registration Guide to:
  • Register your webhook URL
  • Configure authentication and security
  • Subscribe to the Hosted PIS event types listed below

​
Supported Event Types

To be notified when a hosted payment reaches a terminal state, subscribe to the following events:
Event TypeDescription
hosted_pis.payment_status.completed.v1Triggered when a hosted payment has completed successfully
hosted_pis.payment_status.failed.v1Triggered when a hosted payment fails to execute and an error is received

​
Success Event Example

The following example shows a webhook payload delivered when a hosted payment completes successfully: 
{
  "type": "hosted_pis.payment_status.completed.v1",
  "applicationId": "a75620ec-8a74-408d-b13f-84227036cf43",
  "id": "b59e9533-24a0-4fd0-afc8-0c0c1a186f34",
  "event": {
    "consentId": "2427faa9-08e2-404e-90f1-4a312dc5f80d",
    "institutionId": "mock-sandbox",
    "paymentId": "9c5f7701-5275-442f-9d86-80d3ddc5cccc",
    "paymentRequestId": "dedcc4f9-7d6d-451c-accc-8a322f153a56",
    "isoStatus": {
      "code": "ACSC",
      "name": "AcceptedSettlementCompleted"
    },
    "status": "COMPLETED"
  },
  "metadata": {
    "tracingId": "6cf5ef06-9f96-4f24-8bab-32ab09128010",
    "user": {
      "key": "value"
    }
  }
}

​
Success Event Fields

PropertyTypeDescription
idStringThe webhook delivery ID
applicationIdStringThe application that registered the webhook
typeStringThe triggered event type
event.consentIdStringConsent ID associated with the payment
event.institutionIdStringInstitution from which the payment was initiated
event.paymentIdStringPayment ID (typically provided by the institution)
event.paymentRequestIdStringPayment Request ID created at payment initiation
event.statusStringFinal payment status (COMPLETED)
event.isoStatus.codeStringOptional ISO 20022 status code
event.isoStatus.nameStringHuman-readable ISO status name
metadata.tracingIdStringTracing ID for observability and debugging
metadata.userObjectOptional metadata provided at webhook registration

​
Failure Event Example

The following example shows a webhook payload delivered when a hosted payment fails: 
{
  "type": "hosted_pis.payment_status.failed.v1",
  "applicationId": "a75620ec-8a74-408d-b13f-84227036cf43",
  "id": "b59e9533-24a0-4fd0-afc8-0c0c1a186f34",
  "event": {
    "consentId": "2427faa9-08e2-404e-90f1-4a312dc5f80d",
    "institutionId": "mock-sandbox",
    "paymentId": "9c5f7701-5275-442f-9d86-80d3ddc5cccc",
    "paymentRequestId": "dedcc4f9-7d6d-451c-accc-8a322f153a56",
    "isoStatus": {
      "code": "RJCT",
      "name": "Rejected"
    },
    "status": "FAILED"
  },
  "metadata": {
    "tracingId": "6cf5ef06-9f96-4f24-8bab-32ab09128010",
    "user": {
      "key": "value"
    }
  }
}

​
Failure Event Fields

PropertyTypeDescription
idStringThe webhook delivery ID
applicationIdStringThe application that registered the webhook
typeStringThe triggered event type
event.consentIdStringConsent ID associated with the payment
event.institutionIdStringInstitution from which the payment was initiated
event.paymentIdStringPayment ID (typically provided by the institution)
event.paymentRequestIdStringPayment Request ID created at payment initiation
event.statusStringFinal payment status (FAILED)
event.isoStatus.codeStringOptional ISO 20022 status code
event.isoStatus.nameStringHuman-readable ISO status name
metadata.tracingIdStringTracing ID for observability and debugging
metadata.userObjectOptional metadata provided at webhook registration

​
Delivery

Yapily attempts to send webhooks immediately after the hosted payment reaches a terminal state (COMPLETED or FAILED). Delivery guarantees:
  • Yapily guarantees that a payment will reach either a COMPLETED or FAILED status, and therefore a webhook will be delivered, unless there’s an unexpected exception
  • The exact timing depends on how quickly the institution processes the payment and updates the payment status
  • Include the tracingId when contacting support to help identify your specific webhook delivery
Unexpected exceptions that may prevent webhook delivery include:
  • The institution doesn’t update the status of a payment as expected
  • The webhook fails to deliver to your endpoint after retrying
For more information on webhook reliability, timeout handling, and retry logic, see the Webhooks Introduction.

​
Hosted Pages Resources

​
Webhook Resources

​
Implementation Resources