> ## 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. # API Reference > Complete reference for the Cheqpay API ## 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 Payments** When 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](mailto: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: ```bash theme={null} 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: ```bash theme={null} Content-Type: application/json ``` Request body should be valid JSON: ```json theme={null} { "externalId": "order-123", "amount": 10000, "currency": "MXN" } ``` ## Response Format All responses are returned as JSON: ```json theme={null} { "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. Learn about payment orders Process card payments ### Refunds ```http theme={null} POST /v2/payment-orders/:id/refund ``` Issue full or partial refunds. Learn how to process refunds ### Customers ```http theme={null} GET /customers/:id ``` Retrieve customer information and saved payment methods. Learn about customer management ### 3D Secure Validation ```http theme={null} POST /v2/payment-orders/:id/payer-authentication/validate ``` Validate 3D Secure authentication after customer completes challenge. Learn about 3DS authentication ## Common Fields ### Amounts Amounts are always specified in cents (minor currency units): ```json theme={null} { "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: ```json theme={null} { "currency": "MXN" // Mexican Peso } ``` Supported currencies: * `MXN` - Mexican Peso * `USD` - US Dollar ### Dates ISO 8601 format with timezone: ```json theme={null} { "createdAt": "2025-10-30T14:30:00.000Z" } ``` ### IDs Two types of IDs for most resources: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests", "retryAfter": 60 } } ``` Contact [support@cheqpay.mx](mailto:support@cheqpay.mx) if you need higher rate limits. ## Pagination List endpoints support pagination: ```http theme={null} 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: ```json theme={null} { "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 ``` Learn about test cards and scenarios ## SDKs and Libraries Official SDKs coming soon. Currently use the REST API directly with your preferred HTTP client. ```javascript theme={null} // 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. View detailed endpoint documentation ## Support Need help with the API? Get help from our integration team Test your integration View all error codes