> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yapily.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosted Payment Webhooks

> Receive real-time notifications on the status of hosted payments

<Note>
  Hosted Pages is available as a [Beta version](/getting-started/overview#yapily-hosted-pages-beta).
  Please contact your Customer Success Manager if you would like to access it.
</Note>

## 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](/tools-and-services/hosted-pages/payment-tutorial-hosted-pages#retrieve-details-of-the-payment-request), 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](/tools-and-services/webhooks/get-started) 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/tools-and-services/webhooks/introduction#your-callback-server).

***

## Related Resources

### Hosted Pages Resources

* [Payment Tutorial](/tools-and-services/hosted-pages/payment-tutorial-hosted-pages) - Complete payment integration guide
* [Payment Statuses & Phases](/tools-and-services/hosted-pages/payment-status-and-phase) - Understanding payment lifecycle

### Webhook Resources

* [Get Started with Webhooks](/tools-and-services/webhooks/get-started) - Register and configure webhooks
* [Webhooks Introduction](/tools-and-services/webhooks/introduction) - Webhook infrastructure overview

### Implementation Resources

* [Error Handling](/resources/errors) - Handle payment failures gracefully
* [Support](/resources/support) - Get help with webhook integration