Payment Orders - Cheqpay

Understanding Payment Orders

Every payment you process creates a payment order. Track the status, retrieve transaction details, and prevent duplicate charges automatically.

Create a Payment Order

Create a payment order to process card payments, SPEI transfers, PayCash cash payments, CIE Cash Net deposits, or batch payments. Each payment type uses the same endpoint with different payment method configurations.

PCI Compliance Required for Direct Card IntegrationIf you handle raw card data (card number, CVV, expiry) through this API, your business must be PCI DSS compliant. This involves security audits, vulnerability scans, and strict compliance requirements.Not PCI compliant? Use our hosted payment page or JavaScript SDK instead. These solutions handle card data for you and keep your business out of PCI scope.Contact support@cheqpay.mx for hosted payment options.

POST /v2/payment-orders
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_MERCHANT_ID
Content-Type: application/json

Card Payment Example

{
  "externalId": "order-123",
  "customer": {
    "externalId": "customer-abc",
    "firstName": "María",
    "lastName": "González",
    "email": "maria@example.com",
    "phoneNumber": "+521555123456"
  },
  "billingAddress": {
    "address": "Av. Reforma 123",
    "city": "Mexico City",
    "state": "CDMX",
    "postalCode": "01000",
    "country": "MX"
  },
  "amount": 10000,
  "currency": "MXN",
  "description": "Order #12345",
  "paymentMethod": {
    "type": "card",
    "cardDetails": {
      "number": "4000000000002503",
      "expiryMonth": "12",
      "expiryYear": "25",
      "cvc": "123"
    }
  }
}

amount unit is the smallest currency unit (e.g., cents). So for MXN, 100 MXN = 10000 cents

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": "1111",
      "expiryMonth": "12",
      "expiryYear": "25"
    }
  }
}

Required Fields

Field	Type	Required	Description
`externalId`	string	Yes	Your unique order ID
`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
`paymentMethod.type`	string	Yes	Payment type (`card`, `spei`, `paycash`, `cie_cash_net`)

Card Payments

Accept credit and debit cards

SPEI Transfers

Immediate bank-to-bank transfers in Mexico

PayCash Payments

Offline cash payments with reference

CIE Cash Net

BBVA cash and bank deposits

Batch Payments

Process multiple payments

Order Status

Payment orders move through different states as they process:

Status	Description	Action
`PENDING`	Payment is being processed	Wait for completion
`PROCESSING`	Payment in progress	Wait for completion
`REFERENCE_GENERATED`	Payment reference issued (SPEI CLABE, CIE or PayCash reference), awaiting the customer’s deposit	Share the reference and wait for the deposit
`AUTHORIZED`	Payment authorized; capture completes automatically	Wait for completion, or refund to reverse the authorization
`PARTIALLY_AUTHORIZED`	Partial amount authorized	Review and process partial amount
`ACTION_REQUIRED`	Additional action needed	Check order details for next steps
`COMPLETED`	Payment successful ✓	Fulfill the order
`PARTIALLY_PAID`	Partial payment received	Track remaining balance
`FAILED`	Payment declined	Show error to customer
`PAYER_AUTHENTICATION_DEVICE_DATA_REQUIRED`	3DS device data collection needed	Show invisible data collection iframe
`PAYER_AUTHENTICATION_CHALLENGE_REQUIRED`	3DS challenge verification needed	Show authentication challenge iframe
`CANCELLATION_REQUESTED`	Cancellation in progress	Wait for cancellation to complete
`CANCELLED`	Payment cancelled	Order cancelled
`REFUND_PROCESSING`	Refund is being processed	Wait for refund completion
`PARTIALLY_REFUNDED`	Partial refund issued	Update order total
`REFUNDED`	Fully refunded	Order fully refunded
`EXPIRED`	Payment reference expired before the customer paid (offline methods)	Create a new order if still needed
`LATE_RECONCILED`	Deposit received and reconciled after the order expired	Review and fulfill or refund

Common Statuses: Most card payments will only see PENDING → PROCESSING → COMPLETED. Offline methods (SPEI, CIE, PayCash) sit in REFERENCE_GENERATED while the customer completes the deposit. The other statuses handle specific scenarios like 3DS authentication, authorizations, cancellations, and refunds.

Status Flow

Most successful payments go directly from PENDING → PROCESSING → COMPLETED in 2-5 seconds.

3D Secure Flow (Summary)

When 3DS is required, the flow adds three steps:

Collect device data (invisible iframe) when status is PAYER_AUTHENTICATION_DEVICE_DATA_REQUIRED.
Check enrollment: POST /v2/payment-orders/:id/payer-authentication → result may be COMPLETED, FAILED, or PAYER_AUTHENTICATION_CHALLENGE_REQUIRED.
If a challenge is required, display the challenge iframe using stepUpUrl and jwt, then validate with POST /v2/payment-orders/:id/payer-authentication/validate.

The authentication method (SMS, biometrics, app, etc.) is decided by the issuing bank, not by Cheqpay or the merchant, and can vary per transaction.

Full 3D Secure Guide

See detailed implementation steps and examples

Track Your Orders

Every payment order has two IDs:

Cheqpay ID - Our internal reference (e.g., ord_abc123)
External ID - Your order or transaction ID (e.g., order-12345)

Retrieve an Order

Use either ID to retrieve order details:

GET /v2/payment-orders/:id
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_MERCHANT_ID

Example Request

curl -X GET https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/ord_abc123 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-merchant-id: YOUR_MERCHANT_ID"

Example Response

{
  "id": "ord_abc123",
  "externalId": "order-12345",
  "status": "COMPLETED",
  "amount": 10000,
  "currency": "MXN",
  "description": "Product purchase",
  "customer": {
    "id": "cus_xyz789",
    "firstName": "María",
    "lastName": "González",
    "email": "maria@example.com"
  },
  "paymentMethod": {
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "1111"
    }
  },
  "createdAt": "2025-10-30T10:00:00.000Z",
  "completedAt": "2025-10-30T10:00:05.000Z"
}

What’s Included

Payment Status

Current status and timestamps for all state changes

Customer Information

Complete customer details including contact information

Payment Method Details

Masked card information or payment method used

Transaction Amounts

Original amount, refunded amounts, and net total

Complete Timeline

Created, processed, completed, and updated timestamps

Prevent Duplicate Charges

Cheqpay automatically prevents duplicate payments using the externalId field. If you send the same request twice, we’ll handle it intelligently:

{
  "externalId": "order-12345"
}

Smart Duplicate Detection

Payment Successful

Returns existing payment (no duplicate charge)

Payment Pending

Returns pending payment (no new request)

Payment Failed

Creates new payment (allows retry)

How It Works

First Request

You create a payment with externalId: "order-12345" and it succeeds.

Duplicate Request

Network issue causes the request to be sent again with the same externalId.

Protected

Cheqpay recognizes the duplicate and returns the existing successful payment. No duplicate charge.

Always use your order ID or transaction ID as the externalId. This protects your customers from being charged twice due to network issues or user errors.

Best Practice

// ✅ Good - Use your order ID
const payment = await createPayment({
  externalId: `order-${orderId}`,
  amount: 10000,
  // ...
});

// ❌ Bad - Random or missing ID
const payment = await createPayment({
  externalId: Math.random().toString(),
  amount: 10000,
  // ...
});

List Payment Orders

Retrieve a list of payment orders for reporting and reconciliation:

GET /v2/payment-orders?limit=20&offset=0
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_MERCHANT_ID

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)

Monitoring Payment Status

You can check payment order status at any time using the GET endpoint to retrieve the latest information.

Next Steps

Process Payments

Learn how to create payment orders

Handle Refunds

Issue full or partial refunds

Manage Customers

Track customer payment history

Error Handling

Handle failed payments gracefully

​Understanding Payment Orders

​Create a Payment Order

​Card Payment Example

​Response

​Required Fields

Card Payments

SPEI Transfers

PayCash Payments

CIE Cash Net

Batch Payments

​Order Status

​Status Flow

​3D Secure Flow (Summary)

Full 3D Secure Guide

​Track Your Orders

​Retrieve an Order

​Example Request

​Example Response

​What’s Included

​Prevent Duplicate Charges

​Smart Duplicate Detection

Payment Successful

Payment Pending

Payment Failed

​How It Works

​Best Practice

​List Payment Orders

​Query Parameters

​Monitoring Payment Status

​Next Steps

Process Payments

Handle Refunds

Manage Customers

Error Handling

Understanding Payment Orders

Create a Payment Order

Card Payment Example

Response

Required Fields

Order Status

Status Flow

3D Secure Flow (Summary)

Track Your Orders

Retrieve an Order

Example Request

Example Response

What’s Included

Prevent Duplicate Charges

Smart Duplicate Detection

How It Works

Best Practice

List Payment Orders

Query Parameters

Monitoring Payment Status

Next Steps