Skip to main content

​
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

Charge via API

You collect the customer’s payment details and charge the pending order from your backend when they’re ready to pay.

Share a Hosted Link

You send the customer a hosted payment page link. They complete the payment on Cheqpay’s UI — no charge call required.

​
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. 
POST /payment-orders
x-api-key: YOUR_API_KEY
Content-Type: application/json

​
Request Example

{
  "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"
}
amount unit is the smallest currency unit (e.g., cents). So for MXN, 100 MXN = 10000 cents
When pending is true, paymentMethod is not required. You attach the payment method later when you charge the order.

​
Response

The order is returned with status: "PENDING" and no payment method attached. 
{
  "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

FieldTypeRequiredDescription
externalIdstringYesYour unique order ID
pendingbooleanYesSet to true to create the order without charging
amountintegerYesAmount in cents (10000 = $100.00)
currencystringYesISO currency code (MXN, USD)
customer.firstNamestringYesCustomer’s first name
customer.lastNamestringYesCustomer’s last name
customer.emailstringYesCustomer’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. 
POST /payment-orders/:id/charge
x-api-key: YOUR_API_KEY
Content-Type: application/json

​
How It Works

1

Create the Pending Order

Create the order with pending: true. It starts in PENDING status with no payment method.
2

Collect Payment Details

When the customer is ready, collect their card or other payment method.
3

Charge the Order

Call the charge endpoint with the payment method. Cheqpay attaches it and processes the payment.
4

Status Updates

The order moves to COMPLETED on success, or FAILED if the payment is declined.

​
Card Payment Example

{
  "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).

Card Payments

Accept credit and debit cards

SPEI Transfers

Bank transfers in Mexico
persist is not supported when charging a pending order. To save a card for future use, create the payment method on the customer separately.

​
Example Request

curl -X POST https://prod.cheqpay.mx/payment-orders/ord_abc123/charge \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": {
      "type": "card",
      "cardDetails": {
        "number": "4000000000002503",
        "expiryMonth": "12",
        "expiryYear": "25",
        "cvc": "123"
      }
    }
  }'

​
Response

{
  "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"
    }
  }
}
Only orders in PENDING, PROCESSING, 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.
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.cheqpay.dev/en/invoices/<payment-order-id>
For example: 
https://pay.cheqpay.dev/en/invoices/a789ca4c-1577-4094-8391-8440de2c5806
<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.
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.

Hosted Payment Page

Learn more about Cheqpay’s hosted checkout experience

​
Next Steps

Payment Orders

Track status and prevent duplicate charges

Card Payments

Accept credit and debit cards

Hosted Payment Page

Let customers pay on Cheqpay’s UI

Refunds

Issue full or partial refunds