# Payments

This section explains how to integrate the **Mozrest Payment Widget** into your website or app to support booking flows that require customer payment. It complements the [Booking flow](/bc-api/bookings) where payment is required.

## 1. Receiving the Payment URL

When committing a [Pending Booking](/bc-api/bookings#commit-pending-booking) that requires payment, the response includes two key fields:


```json
{
  "status": "require_payment",
  "mzPaymentUrl": "https://payments.mozrest.com?token=example-token"
}
```

| Field | Description |
|  --- | --- |
| `status` | Will be `require_payment` when a payment is expected before confirming the booking. |
| `mzPaymentUrl` | The URL to the Mozrest payment widget. This URL can be opened in a new tab or embedded in an iframe. |


## 2. Embedding the Payment Widget

To embed the Mozrest Payment Widget in your interface, place the `mzPaymentUrl` inside an `<iframe>`.

Some payment gateways allow css customisation. If that's the case, you can customise the appearance by appending the `customCss` query param containing a **base64-encoded URL** to a CSS file:


```text
https://payments.mozrest.com?token=example-token&customCss=aHR0cHM6Ly9nb29nbGUuY29tL215Y3NzLmNzcw==
```

Example:


```html
<iframe
  src="https://payments.mozrest.com?token=example-token&customCss=aHR0cHM6Ly9nb29nbGUuY29tL215Y3NzLmNzcw=="
  width="100%"
  height="700"
  frameborder="0">
</iframe>
```

## 3. Example Views

**Default Payment Widget View:**
This is the standard look without custom CSS applied.

![Default View](https://mozrest-statics.s3.eu-west-1.amazonaws.com/payment-gateway/default-view.png)

**Custom CSS Styled Widget:**
This view demonstrates a fully branded appearance using custom styles.

![Custom CSS View](https://mozrest-statics.s3.eu-west-1.amazonaws.com/payment-gateway/customised-view.png)

### CSS Classes Available

| Class | Purpose |
|  --- | --- |
| `.mz_body` | Base page styles |
| `.mz_content` | Container box |
| `.mz_title` | Title (“Card details”) |
| `.mz_button` | Main call-to-action button |
| `.mz_label` | Input field labels |
| `.mz_input` | Input field elements |
| `.mz_text` | General text elements |
| `.mz_terms` | Terms and conditions text |


➡️ **Download example CSS**

## 4. Listening to Payment Events

The Mozrest Payment Widget sends postMessage events you can listen to via JavaScript in the parent window. These allow your app to respond to booking status changes, errors, or UI updates.

### General Event Format


```json
{
  "event": "event-name",
  "data": {
    // Event-specific payload
  }
}
```

| Event | Type | Description |
|  --- | --- | --- |
| `booking-created` | Success | Booking was created successfully. |
| `payment-page-height-update` | Info | Indicates iframe height changed. |
| `booking-create-failed` | Error | Booking failed. |
| `booking-token-expired` | Error | Token expired before payment. |
| `payment-session-expired` | Error | Payment session expired. |
| `payment-failed` | Error | Payment could not be completed. |
| `payment-3ds-failed` | Error | 3D Secure verification failed. |


## 5. Event Examples

### Booking Created


```json
{
  "event": "booking-created",
  "data": {
    "bookingId": "my-booking-id",
    "paymentMeta": {
      "type": "deposit",
      "cardType": "VISA",
      "lastFour": "4242",
      "amount": 6000,
      "currency": "GBP"
    }
  }
}
```

### Iframe Height Updated


```json
{
  "event": "payment-page-height-update",
  "data": {
    "height": 896
  }
}
```

### Booking or Payment Errors

**Booking Creation Failed**


```json
{
  "event": "booking-create-failed",
  "data": {
    "message": "Error creating the booking"
  }
}
```

**Booking Token Expired**


```json
{
  "event": "booking-token-expired",
  "data": {
    "message": "Booking token expired"
  }
}
```

**Payment Session Expired**


```json
{
  "event": "payment-session-expired",
  "data": {
    "message": "The payment session has expired."
  }
}
```

**Payment Failed**


```json
{
  "event": "payment-failed",
  "data": {
    "message": "The payment failed."
  }
}
```

**3D Secure Failed**


```json
{
  "event": "payment-3ds-failed",
  "data": {
    "message": "The 3D Secure (3DS) payment verification failed."
  }
}
```

This integration ensures your Booking Channel experience supports secure, customizable and user-friendly payment handling.