Hosted Payment Webhooks

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 Type	Description
`hosted_pis.payment_status.completed.v1`	Triggered when a hosted payment has completed successfully
`hosted_pis.payment_status.failed.v1`	Triggered 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

Property	Type	Description
`id`	String	The webhook delivery ID
`applicationId`	String	The application that registered the webhook
`type`	String	The triggered event type
`event.consentId`	String	Consent ID associated with the payment
`event.institutionId`	String	Institution from which the payment was initiated
`event.paymentId`	String	Payment ID (typically provided by the institution)
`event.paymentRequestId`	String	Payment Request ID created at payment initiation
`event.status`	String	Final payment status (`COMPLETED`)
`event.isoStatus.code`	String	Optional ISO 20022 status code
`event.isoStatus.name`	String	Human-readable ISO status name
`metadata.tracingId`	String	Tracing ID for observability and debugging
`metadata.user`	Object	Optional 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

Property	Type	Description
`id`	String	The webhook delivery ID
`applicationId`	String	The application that registered the webhook
`type`	String	The triggered event type
`event.consentId`	String	Consent ID associated with the payment
`event.institutionId`	String	Institution from which the payment was initiated
`event.paymentId`	String	Payment ID (typically provided by the institution)
`event.paymentRequestId`	String	Payment Request ID created at payment initiation
`event.status`	String	Final payment status (`FAILED`)
`event.isoStatus.code`	String	Optional ISO 20022 status code
`event.isoStatus.name`	String	Human-readable ISO status name
`metadata.tracingId`	String	Tracing ID for observability and debugging
`metadata.user`	Object	Optional 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

Payment Tutorial - Complete payment integration guide
Payment Statuses & Phases - Understanding payment lifecycle

Webhook Resources

Get Started with Webhooks - Register and configure webhooks
Webhooks Introduction - Webhook infrastructure overview

Implementation Resources

Error Handling - Handle payment failures gracefully
Support - Get help with webhook integration

Learn

Build

Payments

Data

Hosted Pages

Resources

Introduction

Webhook Registration

Supported Event Types

Success Event Example

Success Event Fields

Failure Event Example

Failure Event Fields

Delivery

Hosted Pages Resources

Webhook Resources

Implementation Resources

​Introduction

​Webhook Registration

​Supported Event Types

​Success Event Example

​Success Event Fields

​Failure Event Example

​Failure Event Fields

​Delivery

​Related Resources

​Hosted Pages Resources

​Webhook Resources

​Implementation Resources

Introduction

Webhook Registration

Supported Event Types

Success Event Example

Success Event Fields

Failure Event Example

Failure Event Fields

Delivery

Related Resources

Hosted Pages Resources

Webhook Resources

Implementation Resources