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

# Hosted Payment Pages

> Send customers to your own payment page to pay invoices, using a signed request and response so Nexudus can record the payment.

## Overview

A hosted payment page lets you use a payment provider Nexudus doesn't integrate with. When a customer chooses it to pay an invoice, Nexudus redirects them to a page you build and host. Your page takes the payment with your provider, then sends the customer back to Nexudus with the result, and Nexudus records the payment against the invoice.

Both directions are signed with a shared secret, so Nexudus only accepts results that really came from your page.

You can set up to three hosted payment pages per location.

<Note>Building a hosted payment page needs a developer. Your page must read the request parameters, check the signature, take the payment and build a signed response, as described below.</Note>

## How to access

Go to **Settings → Billing and payments → Payments and currency → Payment methods** and search for **Hosted payment page**. Select **Hosted payment page #1**, **#2** or **#3**.

## Enable a hosted payment page

1. Open a hosted payment page tile.
2. Turn on **Enabled**.
3. Enter a **Name**. Customers see this name as a payment option in the Members Portal.
4. Enter your **Shared secret**.
5. Enter your page's full **Payment URL**, starting with `https://`.
6. Select **Save changes**.

| Field | Description |
| - | - |
| **Enabled** | Shows this payment option to customers. |
| **Name** | The payment option's name in the Members Portal. |
| **Shared secret** | The key both sides use to sign messages. Use a long random value, such as a GUID, and a different secret for each page. Keep it private. |
| **Payment URL** | The full URL of your payment page. Nexudus adds the request parameters to it. |

## The request Nexudus sends

When a customer chooses your page, Nexudus redirects them to your **Payment URL** with these query string parameters:

| Parameter | Type | Description |
| - | - | - |
| `amount` | Integer | The invoice total, multiplied by 100. An invoice for 101.21 gives `10121`. |
| `currency` | String | The ISO currency code to charge in, such as `USD`. |
| `reference` | String | The invoice's payment reference. |
| `identifier` | GUID | The invoice's unique ID. |
| `providerKey` | Integer | Which hosted payment page was used: `1`, `2` or `3`. |
| `signature` | String | An HMAC-SHA256 hash of `{amount}\|{currency}\|{reference}\|{identifier}`, keyed with your shared secret, as lowercase hex. |
| `returnUrl` | String | Where to send the customer when you're done. |

Check the signature before you take any payment. Recalculate it from the other parameters with your shared secret and compare.

## The response your page sends

After processing the payment, redirect the customer to `returnUrl` and append:

| Parameter | Type | Description |
| - | - | - |
| `result` | String | `OK` if the payment succeeded, `FAIL` if it didn't. |
| `amount` | Integer | The amount you actually took, multiplied by 100. |
| `signature` | String | An HMAC-SHA256 hash of `{result}\|{amount}\|{identifier}`, keyed with your shared secret, as lowercase hex. |

If the signature matches and `result` is `OK`, Nexudus records a payment for the `amount` you sent. You can take partial payments or overpayments: Nexudus records whatever amount you return. If the signature doesn't match, the payment is not recorded and the customer sees an error.

## Worked example

An invoice for \$200.00 with payment reference `5843`, unique ID `446f5f1b-8fb1-41b9-b606-0751e55cd9f6` and a shared secret of `Secret`.

**Request.** Nexudus signs `20000|USD|5843|446f5f1b-8fb1-41b9-b606-0751e55cd9f6`, which gives:

```
f5b4c156c29d8fe392fe633e42b42f60d1e394ff4075b480d3456fd67623703f
```

and redirects the customer to:

```
https://yourdomain.com/pay?amount=20000&currency=USD&reference=5843&identifier=446f5f1b-8fb1-41b9-b606-0751e55cd9f6&providerKey=1&signature=f5b4c156c29d8fe392fe633e42b42f60d1e394ff4075b480d3456fd67623703f&returnUrl=...
```

**Response.** After a successful payment of the full amount, your page signs `OK|20000|446f5f1b-8fb1-41b9-b606-0751e55cd9f6`, which gives:

```
bb1fcc7b4d97a91f11253b1f1f34692719c540d9dd5d4669b32355f8d8d47eb5
```

and redirects the customer to the `returnUrl` it received, adding `&result=OK&amount=20000&signature=bb1fcc7b4d97a91f11253b1f1f34692719c540d9dd5d4669b32355f8d8d47eb5`.

## Tips

* Keep `returnUrl` exactly as you received it and append your parameters to it. It already contains the invoice and page details Nexudus needs.
* Hosted payment pages take one-off payments only. Nexudus can't use them to collect later invoices automatically.

## Related

* [Payment gateways](/platform/finance/payment-gateways)
* [Invoices](/platform/finance/invoices)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.