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

# Hosted Payment Page

> Integrate Cheqpay's Hosted Payment Page (HPP) to deliver a seamless payment experience

## Overview

Cheqpay's Hosted Payment Page (HPP) allows you to accept payments with minimal integration effort. Create a payment link with a single API call, then redirect customers to Cheqpay's hosted checkout page where they can complete their payment securely.

## Integration Flow

The Hosted Payment Page integration involves three main steps:

1. **Create Payment Link** - Your backend creates a payment link via API
2. **Customer Checkout** - Customer is redirected to Cheqpay's hosted payment page
3. **Payment Completion** - Customer is redirected back to your site with payment status

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant Customer
    participant Merchant
    participant Cheqpay HPP
    participant Cheqpay API

    Customer->>Merchant: Initiates checkout
    Merchant->>Cheqpay API: POST /lps/payment-links<br/>(with products, totals, redirectUrl)
    Cheqpay API-->>Merchant: Payment link URL
    Merchant->>Customer: Redirect to payment link URL
    Customer->>Cheqpay HPP: Visits payment page
    Cheqpay HPP->>Customer: Displays checkout form
    Customer->>Cheqpay HPP: Enters payment details
    Customer->>Cheqpay HPP: Submits payment
    Cheqpay HPP->>Cheqpay API: Processes payment
    Cheqpay HPP->>Customer: Redirect to redirectUrl<br/>(with cp_status & cp_invoice_id)
    Customer->>Merchant: Returns to your site
    Merchant->>Cheqpay API: GET /lps/invoices/{id}
    Cheqpay API-->>Merchant: Invoice details
```

## Before You Start

### Prerequisites

* Cheqpay merchant account with API credentials
* Backend server to create payment links
* Redirect URL endpoint to handle payment completion

### Authentication

All API requests require authentication using your API key:

```http theme={null}
x-api-key: YOUR_API_KEY
```

## Step 1: Create Payment Link

Create a payment link by making a POST request to the payment links endpoint. For complete API documentation, see the [Create Payment Link API Reference](/api-reference/payment-links/create-payment-link).

### Endpoint

```http theme={null}
POST https://api.sandbox.cheqpay.mx/lps/payment-links
x-api-key: YOUR_API_KEY
Content-Type: application/json
```

### Payment methods

Pass one or more methods in `paymentMethods`. Values are **lowercase** and must be enabled on your merchant account:

| Value          | Description                                                                               |
| -------------- | ----------------------------------------------------------------------------------------- |
| `card`         | Credit and debit cards                                                                    |
| `spei`         | Bank transfer (SPEI) — customer receives a CLABE on checkout                              |
| `paycash`      | Cash at PayCash collection points — customer receives a reference on checkout             |
| `cie_cash_net` | BBVA cash and bank deposit — customer receives reference, convenio, and CLABE on checkout |

You can offer a single method or let the customer choose if you have more than one method enabled on your merchant account, for example `["card", "spei", "paycash", "cie_cash_net"]`.

### Request examples

<Tabs>
  <Tab title="Card only">
    ```json theme={null}
    {
      "products": [
        {
          "name": "Premium Plan",
          "description": "Monthly subscription",
          "qty": 1,
          "price": 10.20,
          "total": 10.20,
          "imageUrl": "https://example.com/product.jpg"
        }
      ],
      "currency": "MXN",
      "totals": {
        "total": 10.20
      },
      "paymentMethods": ["card"],
      "redirectUrl": "https://yourdomain.com/checkout/complete?cp_status={status}&cp_invoice_id={invoiceId}",
      "cancelUrl": "https://yourdomain.com/cart"
    }
    ```
  </Tab>

  <Tab title="SPEI only">
    Same product and totals as card; only `paymentMethods` changes. The customer selects SPEI on the hosted page and receives a CLABE to complete the transfer from their bank.

    ```json theme={null}
    {
      "products": [
        {
          "name": "Premium Plan",
          "description": "Monthly subscription",
          "qty": 1,
          "price": 10.20,
          "total": 10.20
        }
      ],
      "currency": "MXN",
      "totals": {
        "total": 10.20
      },
      "paymentMethods": ["spei"],
      "redirectUrl": "https://yourdomain.com/checkout/complete?cp_status={status}&cp_invoice_id={invoiceId}"
    }
    ```
  </Tab>

  <Tab title="PayCash only">
    Same structure; the customer receives a PayCash reference and pays in cash at a collection point.

    ```json theme={null}
    {
      "products": [
        {
          "name": "Premium Plan",
          "description": "Monthly subscription",
          "qty": 1,
          "price": 10.20,
          "total": 10.20
        }
      ],
      "currency": "MXN",
      "totals": {
        "total": 10.20
      },
      "paymentMethods": ["paycash"],
      "redirectUrl": "https://yourdomain.com/checkout/complete?cp_status={status}&cp_invoice_id={invoiceId}"
    }
    ```
  </Tab>

  <Tab title="CIE Cash Net only">
    Same structure; the customer receives CIE payment instructions (reference, convenio, and CLABE) to complete a BBVA cash or bank deposit.

    ```json theme={null}
    {
      "products": [
        {
          "name": "Premium Plan",
          "description": "Monthly subscription",
          "qty": 1,
          "price": 10.20,
          "total": 10.20
        }
      ],
      "currency": "MXN",
      "totals": {
        "total": 10.20
      },
      "paymentMethods": ["cie_cash_net"],
      "redirectUrl": "https://yourdomain.com/checkout/complete?cp_status={status}&cp_invoice_id={invoiceId}"
    }
    ```
  </Tab>

  <Tab title="Multiple methods">
    Let the customer choose card, SPEI, PayCash, or CIE Cash Net at checkout:

    ```json theme={null}
    {
      "products": [
        {
          "name": "Premium Plan",
          "qty": 1,
          "price": 10.20,
          "total": 10.20
        }
      ],
      "currency": "MXN",
      "totals": {
        "total": 10.20
      },
      "paymentMethods": ["card", "spei", "paycash", "cie_cash_net"],
      "redirectUrl": "https://yourdomain.com/checkout/complete?cp_status={status}&cp_invoice_id={invoiceId}"
    }
    ```
  </Tab>
</Tabs>

<Warning>
  For **SPEI**, **PayCash**, and **CIE Cash Net**, funds are confirmed asynchronously after the customer leaves checkout. Always confirm the final status with [Get Invoice](/api-reference/invoices/get-invoice) or [webhooks](/features/webhooks)—do not rely on `cp_status` alone for fulfillment.
</Warning>

<Tip>
  See [Card Payments](/features/card-payments), [SPEI Transfers](/features/spei-transfers), [PayCash Payments](/features/paycash-payments), and [CIE Cash Net Payments](/features/cie-cash-net-payments) for method-specific behavior, testing, and webhooks.
</Tip>

### Response

Upon successful creation, you'll receive a payment link object with a `url` field that you'll use to redirect the customer. See the [Create Payment Link API Reference](/api-reference/payment-links/create-payment-link) for the complete response schema.

<Info>
  Use the `url` field from the response to redirect your customer to the payment page.
</Info>

## Step 2: Redirect Customer to Payment Page

Once you receive the payment link URL, redirect your customer to it:

```javascript theme={null}
// Example: Redirect customer to payment page
window.location.href = paymentLink.url;
```

Or on the server side:

```http theme={null}
HTTP/1.1 302 Found
Location: https://pay.sandbox.cheqpay.mx/VOv6xvWaNIjB
```

### Let Customers Cancel

Optionally set `cancelUrl` when creating the link. The hosted page then shows a "Cancel and return" link, and clicking it sends the customer back to that URL. No query parameters are added. App deep links (for example `myapp://cart`) are supported.

## Step 3: Handle Payment Completion

After the customer completes payment (or cancels), Cheqpay redirects them back to your `redirectUrl` with query parameters:

* `cp_status` - Payment status (`success` or `failed`)
* `cp_invoice_id` - Invoice ID for retrieving payment details

### Example Redirect URL

```
https://yourdomain.com[...]?cp_status=success&cp_invoice_id=inv_abc123xyz
```

### Handle the Redirect

```javascript theme={null}
// Example: Handle payment completion redirect
const urlParams = new URLSearchParams(window.location.search);
const status = urlParams.get('cp_status');
const invoiceId = urlParams.get('cp_invoice_id');

if (status === 'success') {
  // Payment successful - fetch invoice details
  fetchInvoiceDetails(invoiceId);
} else {
  // Payment failed
  showErrorMessage('Payment failed. Please try again.');
}
```

## Step 4: Retrieve Invoice Details

After payment completion, retrieve the invoice details to confirm the payment and get order information. For complete API documentation, see the [Get Invoice API Reference](/api-reference/invoices/get-invoice).

### Endpoint

```http theme={null}
GET https://api.sandbox.cheqpay.mx/lps/invoices/{id}
x-api-key: YOUR_API_KEY
```

The response includes invoice details such as order information, customer details, payment method, and status. See the [Get Invoice API Reference](/api-reference/invoices/get-invoice) for the complete response schema.

## Best Practices

<Accordion title="Security">
  * Always validate the `cp_status` and `cp_invoice_id` parameters on your server
  * Never trust client-side status - always verify by fetching invoice details
  * Use HTTPS for all redirect URLs
  * Store API keys securely on your backend, never expose them to the client
</Accordion>

<Accordion title="Error Handling">
  * Handle network errors when creating payment links
  * Implement retry logic for failed API calls
  * Show user-friendly error messages
  * Log errors for debugging
</Accordion>

<Accordion title="User Experience">
  * Show a loading state while creating the payment link
  * Provide clear instructions during redirect
  * Handle payment completion gracefully
  * Send confirmation emails after successful payment
</Accordion>

## Testing

Use the staging environment for testing:

```http theme={null}
POST https://api.sandbox.cheqpay.mx/lps/payment-links
```

* **Card:** test cards and decline amounts in the [Testing Guide](/guides/testing)
* **SPEI / PayCash / CIE Cash Net:** simulators and webhook flows in [Webhook Simulators](/testing/webhook-simulators) and the [SPEI](/features/spei-transfers), [PayCash](/features/paycash-payments), and [CIE Cash Net](/features/cie-cash-net-payments) guides

## Next Steps

* Learn about [Payment Orders](/features/payment-orders) for direct API integration
* Understand [3D Secure](/features/3d-secure) authentication flows
* Review [Error Handling](/guides/error-handling) best practices
* Check the [Link Product API Reference](/api-reference/link-product-openapi.json) for complete API documentation