API Reference - Cheqpay

Overview

The Cheqpay API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

PCI Compliance for Card PaymentsWhen using the Payments API to process card payments with raw card data (card number, CVV, expiry), your business must maintain PCI DSS compliance.If your business is not PCI compliant, use our hosted payment page or JavaScript SDK instead. These options handle card data securely without requiring PCI compliance from your business.Contact support@cheqpay.mx to learn more about hosted payment options.

Base URLs

Sandbox

https://api.sandbox.cheqpay.mx/pos

Use sandbox for testing and development. No real money is processed.

Production

https://prod.cheqpay.mx/pos

Use production for processing live payments.

Authentication

Authenticate your API requests with your API key in the x-api-key header. The x-merchant-id header is optional:

x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_MERCHANT_ID

Keep your API keys secure. Never share them publicly or commit them to version control.

Request Format

All POST requests should include:

Content-Type: application/json

Request body should be valid JSON:

{
  "externalId": "order-123",
  "amount": 10000,
  "currency": "MXN"
}

Response Format

All responses are returned as JSON:

{
  "paymentOrder": {
    "id": "ord_abc123",
    "status": "COMPLETED",
    "amount": 10000,
    "currency": "MXN"
  }
}

HTTP Status Codes

Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Invalid or missing API key
`404`	Not Found	Resource not found
`409`	Conflict	Duplicate resource or conflicting state
`422`	Unprocessable Entity	Payment declined or business logic error
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error (rare)
`503`	Service Unavailable	Temporary service disruption

Key Endpoints

Payment Orders

Create and manage payment orders for card payments, SPEI transfers, PayCash cash payments, CIE Cash Net deposits, and batch processing.

Payment Orders Guide

Learn about payment orders

Card Payments Guide

Process card payments

Refunds

POST /v2/payment-orders/:id/refund

Issue full or partial refunds.

Refunds Guide

Learn how to process refunds

Customers

GET /customers/:id

Retrieve customer information and saved payment methods.

Customers Guide

Learn about customer management

3D Secure Validation

POST /v2/payment-orders/:id/payer-authentication/validate

Validate 3D Secure authentication after customer completes challenge.

3D Secure Guide

Learn about 3DS authentication

Common Fields

Amounts

Amounts are always specified in cents (minor currency units):

{
  "amount": 10000  // = $100.00 MXN
}

Amount	Represents
100	$1.00 MXN
1000	$10.00 MXN
10000	$100.00 MXN
999999	$9,999.99 MXN

Currency

ISO 4217 currency codes:

{
  "currency": "MXN"  // Mexican Peso
}

Supported currencies:

MXN - Mexican Peso
USD - US Dollar

Dates

ISO 8601 format with timezone:

{
  "createdAt": "2025-10-30T14:30:00.000Z"
}

IDs

Two types of IDs for most resources:

{
  "id": "ord_abc123",           // Cheqpay ID
  "externalId": "order-12345"   // Your ID
}

Use externalId to link Cheqpay resources with your system and enable idempotency.

Payment Order Statuses

Status	Description
`PENDING`	Payment is being processed
`PROCESSING`	Payment in progress
`REFERENCE_GENERATED`	Payment reference issued (SPEI CLABE / cash reference), awaiting the customer’s deposit
`COMPLETED`	Payment successful
`FAILED`	Payment declined
`PAYER_AUTHENTICATION_DEVICE_DATA_REQUIRED`	3DS data collection needed
`PAYER_AUTHENTICATION_CHALLENGE_REQUIRED`	3DS verification needed
`PARTIALLY_REFUNDED`	Partial refund issued
`REFUNDED`	Fully refunded

Idempotency

Use externalId to safely retry requests without creating duplicates:

{
  "externalId": "order-12345",
  "amount": 10000,
  "currency": "MXN"
}

If you send the same request twice:

Successful payment → Returns existing payment (no duplicate)
Failed payment → Creates new payment (allows retry)

Always use your order ID or transaction ID as the externalId.

Rate Limits

API requests are rate limited to ensure system stability:

Default limit: 100 requests per minute per API key
Burst limit: 10 requests per second

If you exceed limits, you’ll receive:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "retryAfter": 60
  }
}

Contact support@cheqpay.mx if you need higher rate limits.

Pagination

List endpoints support pagination:

GET /v2/payment-orders?limit=20&offset=0

Parameter	Type	Default	Description
`limit`	integer	20	Number of results (max 100)
`offset`	integer	0	Pagination offset

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 150,
    "hasMore": true
  }
}

Versioning

The API version is part of the URL path, and it varies by resource:

https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/:id/payer-authentication/validate

Payment orders use v2 (e.g. /v2/payment-orders).
Subscriptions and plans use v1 (e.g. /v1/subscriptions, /v1/plans).
Some endpoints, such as customers and payment methods, have no version prefix.

Always use the path shown for each endpoint in its reference. We maintain backward compatibility and give advance notice of breaking changes.

Testing

Use the sandbox environment for testing:

https://api.sandbox.cheqpay.mx/pos

Complete Testing Guide

Learn about test cards and scenarios

SDKs and Libraries

Official SDKs coming soon. Currently use the REST API directly with your preferred HTTP client.

// Node.js example - See feature guides for complete examples
const axios = require('axios');

const response = await axios.post(
  'https://api.sandbox.cheqpay.mx/pos/v2/payment-orders',
  paymentData,
  {
    headers: {
      'x-api-key': API_KEY,
      'x-merchant-id': MERCHANT_ID,
      'Content-Type': 'application/json'
    }
  }
);

OpenAPI Specification

Full OpenAPI specification coming soon. This will enable automatic API client generation for your preferred language.

API Endpoints Reference

View detailed endpoint documentation

Support

Need help with the API?

Email Support

Get help from our integration team

Testing Guide

Test your integration

Error Reference

View all error codes

​Overview

​Base URLs

​Sandbox

​Production

​Authentication

​Request Format

​Response Format

​HTTP Status Codes

​Key Endpoints

​Payment Orders

Payment Orders Guide

Card Payments Guide

​Refunds

Refunds Guide

​Customers

Customers Guide

​3D Secure Validation

3D Secure Guide

​Common Fields

​Amounts

​Currency

​Dates

​IDs

​Payment Order Statuses

​Idempotency

​Rate Limits

​Pagination

​Versioning

​Testing

Complete Testing Guide

​SDKs and Libraries

​OpenAPI Specification

API Endpoints Reference

​Support

Email Support

Testing Guide

Error Reference

Overview

Base URLs

Sandbox

Production

Authentication

Request Format

Response Format

HTTP Status Codes

Key Endpoints

Payment Orders

Refunds

Customers

3D Secure Validation

Common Fields

Amounts

Currency

Dates

IDs

Payment Order Statuses

Idempotency

Rate Limits

Pagination

Versioning

Testing

SDKs and Libraries

OpenAPI Specification

Support