Payment Orders

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, or batch payments. Each payment type uses the same endpoint with different payment method configurations.

POST /payment-orders
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Card Payment Example

{
  "externalId": "order-123",
  "customer": {
    "externalId": "customer-abc",
    "firstName": "María",
    "lastName": "González",
    "email": "[email protected]",
    "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": "[email protected]"
  },
  "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, etc.)

Card Payments

Accept credit and debit cards

SPEI Transfers

Bank transfers in Mexico

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
`AUTHORIZED`	Payment authorized but not captured	Capture or void 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

Common Statuses: Most payment orders will only see PENDING → PROCESSING → COMPLETED. 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 /payment-orders/:id
Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET https://prod.cheqpay.mx/payment-orders/ord_abc123 \
  -H "x-api-key: YOUR_API_KEY"

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": "[email protected]"
  },
  "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 /payment-orders?limit=20&offset=0
Authorization: Bearer YOUR_API_KEY

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

Getting Started

Essentials

Features

Guides

API Reference

OpenAPI Reference

Link Product API

Understanding Payment Orders

Create a Payment Order

Card Payment Example

Response

Required Fields

Card Payments

SPEI Transfers

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

Getting Started

Essentials

Features

Guides

API Reference

OpenAPI Reference

Link Product API

​Understanding Payment Orders

​Create a Payment Order

​Card Payment Example

​Response

​Required Fields

Card Payments

SPEI Transfers

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