Skip to main content

​
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

​
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
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.cheqpay.dev/lps/payment-links
x-api-key: YOUR_API_KEY
Content-Type: application/json

​
Request Example

{
  "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[...]?cp_status={status}&cp_invoice_id={invoiceId}"
}

​
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.cheqpay.dev/VOv6xvWaNIjB

​
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.cheqpay.dev/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

  • 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
  • Handle network errors when creating payment links
  • Implement retry logic for failed API calls
  • Show user-friendly error messages
  • Log errors for debugging
  • 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.cheqpay.dev/lps/payment-links
Test cards and scenarios are available in the Testing Guide.

​
Next Steps