API Reference

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.

Base URLs

Sandbox

https://api.cheqpay.dev

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

Production

https://prod.cheqpay.mx

Use production for processing live payments.

Authentication

Authenticate your API requests by including your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

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, 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
`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 [email protected] if you need higher rate limits.

Pagination

List endpoints support pagination:

GET /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 is versioned using the URL path:

https://prod.cheqpay.mx/v2/payment-orders/:id/payer-authentication/validate

Most endpoints use the implicit v1 (no version in path). We maintain backward compatibility and give advance notice of breaking changes.

Testing

Use the sandbox environment for testing:

https://api.cheqpay.dev

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://prod.cheqpay.mx/payment-orders',
  paymentData,
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      '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

Getting Started

Essentials

Features

Guides

OpenAPI Reference

Link Product API

​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