> ## 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 Endpoints

> Detailed reference for all API endpoints

## Overview

Complete reference for all Cheqpay API endpoints. Full OpenAPI specification coming soon.

<Note>
  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.
</Note>

## Payment Orders

### Create Payment Order

Create a payment order for card, SPEI transfer, PayCash, or CIE Cash Net payments. See the feature-specific guides for detailed implementation:

**Reference:**

<Card title="Card Payments" icon="credit-card" href="/features/card-payments">
  Card-specific fields, 3DS, and PCI notes
</Card>

<Card title="SPEI Transfers" icon="building-columns" href="/features/spei-transfers">
  Bank transfer implementation guide
</Card>

<Card title="PayCash Payments" icon="money-bill" href="/features/paycash-payments">
  Offline cash payment implementation guide
</Card>

<Card title="CIE Cash Net Payments" icon="building-columns" href="/features/cie-cash-net-payments">
  BBVA cash and bank deposit implementation guide
</Card>

***

### Get Payment Order

Retrieve payment order details by ID.

```http theme={null}
GET /v2/payment-orders/:id
```

**Parameters:**

* `:id` - Payment order ID (Cheqpay ID or external ID)

**Reference:**

<Card title="Payment Orders" icon="file-invoice" href="/features/payment-orders">
  Complete guide with status reference
</Card>

### List Payment Orders

Retrieve a list of payment orders with filtering and pagination.

```http theme={null}
GET /v2/payment-orders?limit=20&offset=0
```

**Query Parameters:**

| Parameter    | Type    | Description                               |
| ------------ | ------- | ----------------------------------------- |
| `limit`      | integer | Number of results (default: 20, max: 100) |
| `offset`     | integer | Pagination offset (default: 0)            |
| `status`     | string  | Filter by status                          |
| `customerId` | string  | Filter by customer ID                     |
| `startDate`  | date    | Filter from date (ISO 8601)               |
| `endDate`    | date    | Filter to date (ISO 8601)                 |

## 3D Secure

### Validate Authentication

Validate 3D Secure authentication after customer completes challenge.

```http theme={null}
POST /v2/payment-orders/:id/payer-authentication/validate
```

**Parameters:**

* `:id` - Payment order ID

**Reference:**

<Card title="3D Secure" icon="shield" href="/features/3d-secure">
  Complete 3DS implementation guide
</Card>

## Refunds

### Create Refund

Issue full or partial refund on a completed payment.

```http theme={null}
POST /v2/payment-orders/:id/refund
```

**Parameters:**

* `:id` - Payment order ID

**Request Body:**

```json theme={null}
{
  "amount": 5000,  // Required. Minor units (centavos): 5000 = $50.00. Pass the full amount for a full refund.
  "reason": "Customer requested refund"
}
```

**Reference:**

<Card title="Refunds" icon="rotate-left" href="/features/refunds">
  Complete refund guide
</Card>

## Customers

### Get Customer

Retrieve customer information and saved payment methods.

```http theme={null}
GET /customers/:id
```

**Parameters:**

* `:id` - Customer ID (Cheqpay ID or external ID)

**Reference:**

<Card title="Customers" icon="users" href="/features/customers">
  Complete customer management guide
</Card>

### List Customers

Retrieve a list of customers with pagination.

```http theme={null}
GET /customers?limit=20&offset=0
```

**Query Parameters:**

| Parameter    | Type    | Description                               |
| ------------ | ------- | ----------------------------------------- |
| `limit`      | integer | Number of results (default: 20, max: 100) |
| `offset`     | integer | Pagination offset (default: 0)            |
| `email`      | string  | Filter by email address                   |
| `externalId` | string  | Filter by external ID                     |

## Payment Methods

### List Payment Methods

Get saved payment methods for a customer.

```http theme={null}
GET /customers/:customerId/payment-methods
```

**Parameters:**

* `:customerId` - Customer ID

**Reference:**

<Card title="Payment Methods" icon="credit-card" href="/features/payment-methods">
  Complete payment methods guide
</Card>

### Delete Payment Method

Remove a saved payment method.

```http theme={null}
DELETE /customers/:customerId/payment-methods/:paymentMethodId
```

**Parameters:**

* `:customerId` - Customer ID
* `:paymentMethodId` - Payment method ID

## Common Request Fields

### Customer Object

```json theme={null}
{
  "customer": {
    "externalId": "user_123",
    "firstName": "María",
    "lastName": "González",
    "email": "maria@example.com",
    "phoneNumber": "+521555123456"
  }
}
```

### Billing Address Object

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

### Payment Method Object (Card)

```json theme={null}
{
  "paymentMethod": {
    "type": "card",
    "options": {
      "card": {
        "number": "4000000000002503",
        "expiryMonth": "12",
        "expiryYear": "2025",
        "cvc": "123"
      }
    },
    "persist": true
  }
}
```

### Payment Method Object (Saved Card)

```json theme={null}
{
  "paymentMethod": {
    "type": "payment_method_id",
    "paymentMethodId": "pm_abc123",
    "cvc": "123"
  }
}
```

### Payment Method Object (SPEI)

```json theme={null}
{
  "paymentMethod": {
    "type": "spei"
  }
}
```

### Payment Method Object (PAYCASH)

```json theme={null}
{
  "paymentMethod": {
    "type": "paycash"
  }
}
```

### Payment Method Object (CIE\_CASH\_NET)

```json theme={null}
{
  "paymentMethod": {
    "type": "cie_cash_net"
  }
}
```

### Device Information Object

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

## Response Objects

### Payment Order Object

```json theme={null}
{
  "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

```json theme={null}
{
  "id": "cus_xyz789",
  "externalId": "user_123",
  "firstName": "María",
  "lastName": "González",
  "email": "maria@example.com",
  "phoneNumber": "+521555123456",
  "createdAt": "2025-10-30T10:00:00.000Z"
}
```

### Payment Method Object

```json theme={null}
{
  "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

<Tip>
  Contact [support@cheqpay.mx](mailto:support@cheqpay.mx) if you need early access to the OpenAPI specification.
</Tip>

## Feature-Specific Documentation

For detailed guides and examples, see our feature documentation:

<CardGroup cols={2}>
  <Card title="Card Payments" icon="credit-card" href="/features/card-payments">
    Process credit and debit cards
  </Card>

  <Card title="3D Secure" icon="shield" href="/features/3d-secure">
    Implement authentication
  </Card>

  <Card title="Refunds" icon="rotate-left" href="/features/refunds">
    Issue refunds
  </Card>

  <Card title="Customers" icon="users" href="/features/customers">
    Manage customers
  </Card>

  <Card title="Payment Methods" icon="floppy-disk" href="/features/payment-methods">
    Save payment methods
  </Card>
</CardGroup>

## Need Help?

<CardGroup cols={2}>
  <Card title="Testing Guide" icon="flask" href="/guides/testing">
    Test all endpoints in sandbox
  </Card>

  <Card title="Error Reference" icon="triangle-exclamation" href="/api-reference/errors">
    View all error codes
  </Card>

  <Card title="Quickstart" icon="rocket" href="/essentials/quickstart">
    Process your first payment
  </Card>

  <Card title="Contact Support" icon="headset" href="mailto:support@cheqpay.mx">
    Get integration help
  </Card>
</CardGroup>