Skip to main content

​
Overview

Complete reference for all Cheqpay API endpoints. Full OpenAPI specification coming soon.
We’re currently preparing a complete OpenAPI specification that will provide comprehensive endpoint documentation with request/response schemas, examples, and the ability to generate API clients automatically.

​
Payment Orders

​
Create Payment Order

Create a payment order for card or SPEI transfer. See the feature-specific guides for detailed implementation: Reference:

Card Payments

Complete guide with examples

​
Get Payment Order

Retrieve payment order details by ID. 
GET /payment-orders/:id
Parameters:
  • :id - Payment order ID (Cheqpay ID or external ID)
Reference:

Payment Orders

Complete guide with status reference

​
List Payment Orders

Retrieve a list of payment orders with filtering and pagination. 
GET /payment-orders?limit=20&offset=0
Query Parameters:
ParameterTypeDescription
limitintegerNumber of results (default: 20, max: 100)
offsetintegerPagination offset (default: 0)
statusstringFilter by status
customerIdstringFilter by customer ID
startDatedateFilter from date (ISO 8601)
endDatedateFilter to date (ISO 8601)

​
3D Secure

​
Validate Authentication

Validate 3D Secure authentication after customer completes challenge. 
POST /v2/payment-orders/:id/payer-authentication/validate
Parameters:
  • :id - Payment order ID
Reference:

3D Secure

Complete 3DS implementation guide

​
Refunds

​
Create Refund

Issue full or partial refund on a completed payment. 
POST /v2/payment-orders/:id/refund
Parameters:
  • :id - Payment order ID
Request Body: 
{
  "amount": 5000,  // Optional: omit for full refund
  "reason": "Customer requested refund"
}
Reference:

Refunds

Complete refund guide

​
List Refunds

Get all refunds for a payment order. 
GET /payment-orders/:id/refunds
Parameters:
  • :id - Payment order ID

​
Customers

​
Get Customer

Retrieve customer information and saved payment methods. 
GET /customers/:id
Parameters:
  • :id - Customer ID (Cheqpay ID or external ID)
Reference:

Customers

Complete customer management guide

​
List Customers

Retrieve a list of customers with pagination. 
GET /customers?limit=20&offset=0
Query Parameters:
ParameterTypeDescription
limitintegerNumber of results (default: 20, max: 100)
offsetintegerPagination offset (default: 0)
emailstringFilter by email address
externalIdstringFilter by external ID

​
Payment Methods

​
List Payment Methods

Get saved payment methods for a customer. 
GET /customers/:customerId/payment-methods
Parameters:
  • :customerId - Customer ID
Reference:

Payment Methods

Complete payment methods guide

​
Delete Payment Method

Remove a saved payment method. 
DELETE /customers/:customerId/payment-methods/:paymentMethodId
Parameters:
  • :customerId - Customer ID
  • :paymentMethodId - Payment method ID

​
Common Request Fields

​
Customer Object

{
  "customer": {
    "externalId": "user_123",
    "firstName": "María",
    "lastName": "González",
    "email": "[email protected]",
    "phoneNumber": "+521555123456"
  }
}

​
Billing Address Object

{
  "billingAddress": {
    "address": "Av. Reforma 123",
    "city": "Mexico City",
    "state": "CDMX",
    "postalCode": "01000",
    "country": "MX"
  }
}

​
Payment Method Object (Card)

{
  "paymentMethod": {
    "type": "card",
    "options": {
      "card": {
        "number": "4000000000002503",
        "expiryMonth": "12",
        "expiryYear": "2025",
        "cvc": "123"
      }
    },
    "persist": true
  }
}

​
Payment Method Object (Saved Card)

{
  "paymentMethod": {
    "type": "payment_method_id",
    "paymentMethodId": "pm_abc123",
    "cvc": "123"
  }
}

​
Device Information Object

{
  "deviceInformation": {
    "ipAddress": "192.168.1.100",
    "userAgent": "Mozilla/5.0...",
    "httpBrowserLanguage": "es-MX",
    "httpBrowserScreenWidth": "1920",
    "httpBrowserScreenHeight": "1080"
  }
}

​
Response Objects

​
Payment Order Object

{
  "id": "ord_abc123",
  "externalId": "order-12345",
  "status": "COMPLETED",
  "amount": 10000,
  "currency": "MXN",
  "description": "Order payment",
  "createdAt": "2025-10-30T10:00:00.000Z",
  "completedAt": "2025-10-30T10:00:05.000Z"
}

​
Customer Object

{
  "id": "cus_xyz789",
  "externalId": "user_123",
  "firstName": "María",
  "lastName": "González",
  "email": "[email protected]",
  "phoneNumber": "+521555123456",
  "createdAt": "2025-10-30T10:00:00.000Z"
}

​
Payment Method Object

{
  "id": "pm_abc123",
  "type": "card",
  "card": {
    "brand": "visa",
    "last4": "1111",
    "expiryMonth": "12",
    "expiryYear": "2025"
  },
  "createdAt": "2025-10-30T10:00:00.000Z"
}

​
OpenAPI Specification

Full OpenAPI 3.0 specification coming soon. This will include:
  • Complete endpoint documentation
  • Request/response schemas
  • Example requests and responses
  • Data type definitions
  • Enum values
  • Validation rules
The OpenAPI spec will enable you to:
  • Generate API clients automatically
  • Import into Postman or Insomnia
  • Generate documentation
  • Validate requests/responses
  • Mock API responses for testing
Contact [email protected] if you need early access to the OpenAPI specification.

​
Feature-Specific Documentation

For detailed guides and examples, see our feature documentation:

Card Payments

Process credit and debit cards

3D Secure

Implement authentication

Refunds

Issue refunds

Customers

Manage customers

Payment Methods

Save payment methods

​
Need Help?

Testing Guide

Test all endpoints in sandbox

Error Reference

View all error codes

Quickstart

Process your first payment

Contact Support

Get integration help