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

# Pending Orders

> Create payment orders up front and charge them later or via a hosted link

## Understanding Pending Orders

A pending order is a payment order created without a payment method attached. Instead of charging immediately, you create the order up front in `PENDING` status and collect the payment later.

This is useful when you know what the customer owes but they aren't ready to pay yet, when you want to send an invoice, or when you'd rather let the customer pay on a Cheqpay-hosted page than handle card data yourself.

There are two ways to collect payment on a pending order:

* **Charge it yourself** — your backend calls the charge endpoint with the customer's payment method.
* **Share a hosted link** — send the customer a hosted payment page and let them complete the payment. No charge call from your side.

## When to Use Pending Orders

<CardGroup cols={2}>
  <Card title="Charge via API" icon="credit-card">
    You collect the customer's payment details and charge the pending order from your backend when they're ready to pay.
  </Card>

  <Card title="Share a Hosted Link" icon="link">
    You send the customer a hosted payment page link. They complete the payment on Cheqpay's UI — no charge call required.
  </Card>
</CardGroup>

## Create a Pending Order

Create a pending order by sending `pending: true`. No payment method is required — the order is created in `PENDING` status, ready to be charged later or paid through a hosted link.

```http theme={null}
POST /v2/payment-orders
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_MERCHANT_ID
Content-Type: application/json
```

### Request Example

```json theme={null}
{
  "externalId": "order-123",
  "pending": true,
  "customer": {
    "firstName": "María",
    "lastName": "González",
    "email": "maria@example.com",
    "phoneNumber": "+521555123456"
  },
  "amount": 10000,
  "currency": "MXN",
  "description": "Order #12345"
}
```

<Warning>
  `amount` unit is the smallest currency unit (e.g., cents). So for MXN, 100 MXN = 10000 cents
</Warning>

<Note>
  When `pending` is `true`, `paymentMethod` is **not** required. You attach the payment method later when you charge the order.
</Note>

### Response

The order is returned with `status: "PENDING"` and no payment method attached.

```json theme={null}
{
  "paymentOrder": {
    "id": "ord_abc123",
    "externalId": "order-123",
    "amount": 10000,
    "currency": "MXN",
    "status": "PENDING",
    "description": "Order #12345"
  },
  "customer": {
    "id": "cus_xyz789",
    "firstName": "María",
    "lastName": "González",
    "email": "maria@example.com"
  }
}
```

### Required Fields

| Field                | Type    | Required | Description                                        |
| -------------------- | ------- | -------- | -------------------------------------------------- |
| `externalId`         | string  | Yes      | Your unique order ID                               |
| `pending`            | boolean | Yes      | Set to `true` to create the order without charging |
| `amount`             | integer | Yes      | Amount in cents (10000 = \$100.00)                 |
| `currency`           | string  | Yes      | ISO currency code (MXN, USD)                       |
| `customer.firstName` | string  | Yes      | Customer's first name                              |
| `customer.lastName`  | string  | Yes      | Customer's last name                               |
| `customer.email`     | string  | Yes      | Customer's email address                           |

## Charge a Pending Order

When the customer is ready to pay, charge the pending order by attaching a payment method. This processes the payment and moves the order toward `COMPLETED`.

```http theme={null}
POST /v2/payment-orders/:id/charge
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_MERCHANT_ID
Content-Type: application/json
```

### How It Works

<Steps>
  <Step title="Create the Pending Order">
    Create the order with `pending: true`. It starts in `PENDING` status with no payment method.
  </Step>

  <Step title="Collect Payment Details">
    When the customer is ready, collect their card or other payment method.
  </Step>

  <Step title="Charge the Order">
    Call the charge endpoint with the payment method. Cheqpay attaches it and processes the payment.
  </Step>

  <Step title="Status Updates">
    The order moves to `COMPLETED` on success, or `FAILED` if the payment is declined.
  </Step>
</Steps>

### Card Payment Example

```json theme={null}
{
  "paymentMethod": {
    "type": "card",
    "cardDetails": {
      "number": "4000000000002503",
      "expiryMonth": "12",
      "expiryYear": "25",
      "cvc": "123"
    }
  },
  "billingAddress": {
    "address": "Av. Reforma 123",
    "city": "Mexico City",
    "state": "CDMX",
    "postalCode": "01000",
    "country": "MX"
  }
}
```

You can charge a pending order with any supported payment method by changing `paymentMethod.type` to `spei`, `cie_cash_net`, `paycash`, or `payment_method_id` (to reuse a saved card).

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

  <Card title="SPEI Transfers" icon="building-columns" href="/features/spei-transfers">
    Bank transfers in Mexico
  </Card>
</CardGroup>

<Warning>
  `persist` is not supported when charging a pending order. To save a card for future use, create the payment method on the customer separately.
</Warning>

### Example Request

```bash theme={null}
curl -X POST https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/ord_abc123/charge \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-merchant-id: YOUR_MERCHANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": {
      "type": "card",
      "cardDetails": {
        "number": "4000000000002503",
        "expiryMonth": "12",
        "expiryYear": "25",
        "cvc": "123"
      }
    }
  }'
```

### Response

```json theme={null}
{
  "paymentOrder": {
    "id": "ord_abc123",
    "externalId": "order-123",
    "amount": 10000,
    "currency": "MXN",
    "status": "COMPLETED",
    "description": "Order #12345"
  },
  "customer": {
    "id": "cus_xyz789",
    "firstName": "María",
    "lastName": "González",
    "email": "maria@example.com"
  },
  "paymentMethod": {
    "id": "pm_def456",
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "2503",
      "expiryMonth": "12",
      "expiryYear": "25"
    }
  }
}
```

<Note>
  Only orders in `PENDING`, `PROCESSING`, `REFERENCE_GENERATED`, or `FAILED` status can be charged. If a charge is declined the order moves to `FAILED` — you can charge it again with a different payment method to retry.
</Note>

## Share as a Hosted Payment Link

For clients who want Cheqpay's hosted checkout UI, you don't need to charge the order yourself. Create the pending order and share its hosted payment page link — the customer completes the payment on Cheqpay's page.

The hosted link follows this pattern:

```
https://pay.sandbox.cheqpay.mx/en/invoices/<payment-order-id>
```

For example:

```
https://pay.sandbox.cheqpay.mx/en/invoices/a789ca4c-1577-4094-8391-8440de2c5806
```

<Info>
  `<payment-order-id>` is the `id` returned when you create the pending order. Drop it into the URL and send the link to your customer.
</Info>

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant Merchant
    participant Cheqpay API
    participant Customer
    participant Cheqpay HPP

    Merchant->>Cheqpay API: POST /v2/payment-orders (pending: true)
    Cheqpay API-->>Merchant: Pending order (id, status PENDING)
    Merchant->>Customer: Share https://pay.sandbox.cheqpay.mx/en/invoices/{id}
    Customer->>Cheqpay HPP: Opens hosted payment page
    Customer->>Cheqpay HPP: Enters details and pays
    Cheqpay HPP->>Cheqpay API: Processes payment
    Cheqpay API-->>Merchant: Order status updates to COMPLETED
```

<Note>
  In this flow the merchant does **not** call the charge endpoint. Payment is completed by the customer on the hosted page, and the order status updates automatically.
</Note>

<Card title="Hosted Payment Page" icon="window-maximize" href="/features/hosted-payment-page">
  Learn more about Cheqpay's hosted checkout experience
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Payment Orders" icon="receipt" href="/features/payment-orders">
    Track status and prevent duplicate charges
  </Card>

  <Card title="Card Payments" icon="credit-card" href="/features/card-payments">
    Accept credit and debit cards
  </Card>

  <Card title="Hosted Payment Page" icon="window-maximize" href="/features/hosted-payment-page">
    Let customers pay on Cheqpay's UI
  </Card>

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