Hosted Payment Page

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:

Create Payment Link - Your backend creates a payment link via API
Customer Checkout - Customer is redirected to Cheqpay’s hosted payment page
Payment Completion - Customer is redirected back to your site with payment status

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:

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.

Endpoint

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

Card only
SPEI only
PayCash only
CIE Cash Net only
Multiple methods

{
  "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"
}

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.

{
  "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}"
}

Same structure; the customer receives a PayCash reference and pays in cash at a collection point.

{
  "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}"
}

Same structure; the customer receives CIE payment instructions (reference, convenio, and CLABE) to complete a BBVA cash or bank deposit.

{
  "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}"
}

Let the customer choose card, SPEI, PayCash, or CIE Cash Net at checkout:

{
  "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}"
}

For SPEI, PayCash, and CIE Cash Net, funds are confirmed asynchronously after the customer leaves checkout. Always confirm the final status with Get Invoice or webhooks—do not rely on cp_status alone for fulfillment.

See Card Payments, SPEI Transfers, PayCash Payments, and CIE Cash Net Payments for method-specific behavior, testing, and webhooks.

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 for the complete response schema.

Use the url field from the response to redirect your customer to the payment page.

Step 2: Redirect Customer to Payment Page

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

// Example: Redirect customer to payment page
window.location.href = paymentLink.url;

Or on the server side:

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

// 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.

Endpoint

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 for the complete response schema.

Best Practices

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

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

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

Testing

Use the staging environment for testing:

POST https://api.sandbox.cheqpay.mx/lps/payment-links

Card: test cards and decline amounts in the Testing Guide
SPEI / PayCash / CIE Cash Net: simulators and webhook flows in Webhook Simulators and the SPEI, PayCash, and CIE Cash Net guides

Next Steps

Learn about Payment Orders for direct API integration
Understand 3D Secure authentication flows
Review Error Handling best practices
Check the Link Product API Reference for complete API documentation

Getting Started

Essentials

Features

Testing

Guides

API Reference

Payment Orchestrator API

Link Product API

Hosted Payment Page

Overview

Integration Flow

Before You Start

Prerequisites

Authentication

Step 1: Create Payment Link

Endpoint

Payment methods

Request examples

Response

Step 2: Redirect Customer to Payment Page

Let Customers Cancel

Step 3: Handle Payment Completion

Example Redirect URL

Handle the Redirect

Step 4: Retrieve Invoice Details

Endpoint

Best Practices

Testing

Next Steps

​Overview

​Integration Flow

​Before You Start

​Prerequisites

​Authentication

​Step 1: Create Payment Link

​Endpoint

​Payment methods

​Request examples

​Response

​Step 2: Redirect Customer to Payment Page

​Let Customers Cancel

​Step 3: Handle Payment Completion

​Example Redirect URL

​Handle the Redirect

​Step 4: Retrieve Invoice Details

​Endpoint

​Best Practices

​Testing

​Next Steps

Overview

Integration Flow

Before You Start

Prerequisites

Authentication

Step 1: Create Payment Link

Endpoint

Payment methods

Request examples

Response

Step 2: Redirect Customer to Payment Page

Let Customers Cancel

Step 3: Handle Payment Completion

Example Redirect URL

Handle the Redirect

Step 4: Retrieve Invoice Details

Endpoint

Best Practices

Testing

Next Steps