curl --request POST \
--url https://api.sandbox.cheqpay.mx/pos/v2/payment-orders \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--header 'x-merchant-id: <api-key>' \
--data '
{
"customer": {
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"phoneNumber": "+525512345678"
},
"paymentMethod": {
"type": "card",
"cardDetails": {
"number": "4111111111111111",
"expiryMonth": "12",
"expiryYear": "25",
"cvc": "123"
},
"persist": false
},
"amount": 250,
"currency": "MXN",
"description": "Payment for order #12345",
"externalId": "ORDER-12345",
"billingAddress": {
"address": "Av. Reforma 123",
"city": "Mexico City",
"state": "CDMX",
"postalCode": "01000",
"country": "MX"
},
"metadata": {
"orderId": "ORD-123",
"source": "web"
}
}
'import requests
url = "https://api.sandbox.cheqpay.mx/pos/v2/payment-orders"
payload = {
"customer": {
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"phoneNumber": "+525512345678"
},
"paymentMethod": {
"type": "card",
"cardDetails": {
"number": "4111111111111111",
"expiryMonth": "12",
"expiryYear": "25",
"cvc": "123"
},
"persist": False
},
"amount": 250,
"currency": "MXN",
"description": "Payment for order #12345",
"externalId": "ORDER-12345",
"billingAddress": {
"address": "Av. Reforma 123",
"city": "Mexico City",
"state": "CDMX",
"postalCode": "01000",
"country": "MX"
},
"metadata": {
"orderId": "ORD-123",
"source": "web"
}
}
headers = {
"x-api-key": "<api-key>",
"x-merchant-id": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-api-key': '<api-key>',
'x-merchant-id': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
customer: {
firstName: 'John',
lastName: 'Doe',
email: 'john.doe@example.com',
phoneNumber: '+525512345678'
},
paymentMethod: {
type: 'card',
cardDetails: {number: '4111111111111111', expiryMonth: '12', expiryYear: '25', cvc: '123'},
persist: false
},
amount: 250,
currency: 'MXN',
description: 'Payment for order #12345',
externalId: 'ORDER-12345',
billingAddress: {
address: 'Av. Reforma 123',
city: 'Mexico City',
state: 'CDMX',
postalCode: '01000',
country: 'MX'
},
metadata: {orderId: 'ORD-123', source: 'web'}
})
};
fetch('https://api.sandbox.cheqpay.mx/pos/v2/payment-orders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.cheqpay.mx/pos/v2/payment-orders",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'customer' => [
'firstName' => 'John',
'lastName' => 'Doe',
'email' => 'john.doe@example.com',
'phoneNumber' => '+525512345678'
],
'paymentMethod' => [
'type' => 'card',
'cardDetails' => [
'number' => '4111111111111111',
'expiryMonth' => '12',
'expiryYear' => '25',
'cvc' => '123'
],
'persist' => false
],
'amount' => 250,
'currency' => 'MXN',
'description' => 'Payment for order #12345',
'externalId' => 'ORDER-12345',
'billingAddress' => [
'address' => 'Av. Reforma 123',
'city' => 'Mexico City',
'state' => 'CDMX',
'postalCode' => '01000',
'country' => 'MX'
],
'metadata' => [
'orderId' => 'ORD-123',
'source' => 'web'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>",
"x-merchant-id: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.cheqpay.mx/pos/v2/payment-orders"
payload := strings.NewReader("{\n \"customer\": {\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phoneNumber\": \"+525512345678\"\n },\n \"paymentMethod\": {\n \"type\": \"card\",\n \"cardDetails\": {\n \"number\": \"4111111111111111\",\n \"expiryMonth\": \"12\",\n \"expiryYear\": \"25\",\n \"cvc\": \"123\"\n },\n \"persist\": false\n },\n \"amount\": 250,\n \"currency\": \"MXN\",\n \"description\": \"Payment for order #12345\",\n \"externalId\": \"ORDER-12345\",\n \"billingAddress\": {\n \"address\": \"Av. Reforma 123\",\n \"city\": \"Mexico City\",\n \"state\": \"CDMX\",\n \"postalCode\": \"01000\",\n \"country\": \"MX\"\n },\n \"metadata\": {\n \"orderId\": \"ORD-123\",\n \"source\": \"web\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("x-merchant-id", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sandbox.cheqpay.mx/pos/v2/payment-orders")
.header("x-api-key", "<api-key>")
.header("x-merchant-id", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"customer\": {\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phoneNumber\": \"+525512345678\"\n },\n \"paymentMethod\": {\n \"type\": \"card\",\n \"cardDetails\": {\n \"number\": \"4111111111111111\",\n \"expiryMonth\": \"12\",\n \"expiryYear\": \"25\",\n \"cvc\": \"123\"\n },\n \"persist\": false\n },\n \"amount\": 250,\n \"currency\": \"MXN\",\n \"description\": \"Payment for order #12345\",\n \"externalId\": \"ORDER-12345\",\n \"billingAddress\": {\n \"address\": \"Av. Reforma 123\",\n \"city\": \"Mexico City\",\n \"state\": \"CDMX\",\n \"postalCode\": \"01000\",\n \"country\": \"MX\"\n },\n \"metadata\": {\n \"orderId\": \"ORD-123\",\n \"source\": \"web\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.cheqpay.mx/pos/v2/payment-orders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["x-merchant-id"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"customer\": {\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phoneNumber\": \"+525512345678\"\n },\n \"paymentMethod\": {\n \"type\": \"card\",\n \"cardDetails\": {\n \"number\": \"4111111111111111\",\n \"expiryMonth\": \"12\",\n \"expiryYear\": \"25\",\n \"cvc\": \"123\"\n },\n \"persist\": false\n },\n \"amount\": 250,\n \"currency\": \"MXN\",\n \"description\": \"Payment for order #12345\",\n \"externalId\": \"ORDER-12345\",\n \"billingAddress\": {\n \"address\": \"Av. Reforma 123\",\n \"city\": \"Mexico City\",\n \"state\": \"CDMX\",\n \"postalCode\": \"01000\",\n \"country\": \"MX\"\n },\n \"metadata\": {\n \"orderId\": \"ORD-123\",\n \"source\": \"web\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "123e4567-e89b-12d3-a456-426614174000",
"externalMerchantReference": "ORDER-12345",
"amount": 250,
"orderNumber": "C25123101",
"currency": "MXN",
"status": "PENDING",
"description": "Payment for order #12345",
"metadata": {
"orderId": "ORD-123",
"source": "web"
},
"createdAt": "2025-10-20T10:00:00.000Z",
"paymentMethod": {
"type": "card",
"cardDetails": {
"last4": "1111",
"brand": "VISA",
"country": "US",
"expiryMonth": "12",
"expiryYear": "25"
}
},
"customer": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"phoneNumber": "+525512345678"
}
}Create a payment order (v2)
Creates a new payment order with customer and payment method information. Can accept an existing customer by ID or create a new customer. Supports card payments, saved payment methods, SPEI transfers, and CIE Cash Net payments. For card payments, billing address is required. CIE Cash Net payments generate a reference number for cash payments at convenience stores. Returns payment order details including 3DS authentication information when required.
Supports two-step payment processing: set pending: true to create the order without processing payment immediately. The order will be created in PENDING status with no payment method required. Use the charge endpoint (POST /v2/payment-orders//charge) to process the payment later. This is an internal endpoint.
curl --request POST \
--url https://api.sandbox.cheqpay.mx/pos/v2/payment-orders \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--header 'x-merchant-id: <api-key>' \
--data '
{
"customer": {
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"phoneNumber": "+525512345678"
},
"paymentMethod": {
"type": "card",
"cardDetails": {
"number": "4111111111111111",
"expiryMonth": "12",
"expiryYear": "25",
"cvc": "123"
},
"persist": false
},
"amount": 250,
"currency": "MXN",
"description": "Payment for order #12345",
"externalId": "ORDER-12345",
"billingAddress": {
"address": "Av. Reforma 123",
"city": "Mexico City",
"state": "CDMX",
"postalCode": "01000",
"country": "MX"
},
"metadata": {
"orderId": "ORD-123",
"source": "web"
}
}
'import requests
url = "https://api.sandbox.cheqpay.mx/pos/v2/payment-orders"
payload = {
"customer": {
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"phoneNumber": "+525512345678"
},
"paymentMethod": {
"type": "card",
"cardDetails": {
"number": "4111111111111111",
"expiryMonth": "12",
"expiryYear": "25",
"cvc": "123"
},
"persist": False
},
"amount": 250,
"currency": "MXN",
"description": "Payment for order #12345",
"externalId": "ORDER-12345",
"billingAddress": {
"address": "Av. Reforma 123",
"city": "Mexico City",
"state": "CDMX",
"postalCode": "01000",
"country": "MX"
},
"metadata": {
"orderId": "ORD-123",
"source": "web"
}
}
headers = {
"x-api-key": "<api-key>",
"x-merchant-id": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'x-api-key': '<api-key>',
'x-merchant-id': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
customer: {
firstName: 'John',
lastName: 'Doe',
email: 'john.doe@example.com',
phoneNumber: '+525512345678'
},
paymentMethod: {
type: 'card',
cardDetails: {number: '4111111111111111', expiryMonth: '12', expiryYear: '25', cvc: '123'},
persist: false
},
amount: 250,
currency: 'MXN',
description: 'Payment for order #12345',
externalId: 'ORDER-12345',
billingAddress: {
address: 'Av. Reforma 123',
city: 'Mexico City',
state: 'CDMX',
postalCode: '01000',
country: 'MX'
},
metadata: {orderId: 'ORD-123', source: 'web'}
})
};
fetch('https://api.sandbox.cheqpay.mx/pos/v2/payment-orders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.sandbox.cheqpay.mx/pos/v2/payment-orders",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'customer' => [
'firstName' => 'John',
'lastName' => 'Doe',
'email' => 'john.doe@example.com',
'phoneNumber' => '+525512345678'
],
'paymentMethod' => [
'type' => 'card',
'cardDetails' => [
'number' => '4111111111111111',
'expiryMonth' => '12',
'expiryYear' => '25',
'cvc' => '123'
],
'persist' => false
],
'amount' => 250,
'currency' => 'MXN',
'description' => 'Payment for order #12345',
'externalId' => 'ORDER-12345',
'billingAddress' => [
'address' => 'Av. Reforma 123',
'city' => 'Mexico City',
'state' => 'CDMX',
'postalCode' => '01000',
'country' => 'MX'
],
'metadata' => [
'orderId' => 'ORD-123',
'source' => 'web'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>",
"x-merchant-id: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.cheqpay.mx/pos/v2/payment-orders"
payload := strings.NewReader("{\n \"customer\": {\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phoneNumber\": \"+525512345678\"\n },\n \"paymentMethod\": {\n \"type\": \"card\",\n \"cardDetails\": {\n \"number\": \"4111111111111111\",\n \"expiryMonth\": \"12\",\n \"expiryYear\": \"25\",\n \"cvc\": \"123\"\n },\n \"persist\": false\n },\n \"amount\": 250,\n \"currency\": \"MXN\",\n \"description\": \"Payment for order #12345\",\n \"externalId\": \"ORDER-12345\",\n \"billingAddress\": {\n \"address\": \"Av. Reforma 123\",\n \"city\": \"Mexico City\",\n \"state\": \"CDMX\",\n \"postalCode\": \"01000\",\n \"country\": \"MX\"\n },\n \"metadata\": {\n \"orderId\": \"ORD-123\",\n \"source\": \"web\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("x-merchant-id", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.sandbox.cheqpay.mx/pos/v2/payment-orders")
.header("x-api-key", "<api-key>")
.header("x-merchant-id", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"customer\": {\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phoneNumber\": \"+525512345678\"\n },\n \"paymentMethod\": {\n \"type\": \"card\",\n \"cardDetails\": {\n \"number\": \"4111111111111111\",\n \"expiryMonth\": \"12\",\n \"expiryYear\": \"25\",\n \"cvc\": \"123\"\n },\n \"persist\": false\n },\n \"amount\": 250,\n \"currency\": \"MXN\",\n \"description\": \"Payment for order #12345\",\n \"externalId\": \"ORDER-12345\",\n \"billingAddress\": {\n \"address\": \"Av. Reforma 123\",\n \"city\": \"Mexico City\",\n \"state\": \"CDMX\",\n \"postalCode\": \"01000\",\n \"country\": \"MX\"\n },\n \"metadata\": {\n \"orderId\": \"ORD-123\",\n \"source\": \"web\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.cheqpay.mx/pos/v2/payment-orders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["x-merchant-id"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"customer\": {\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phoneNumber\": \"+525512345678\"\n },\n \"paymentMethod\": {\n \"type\": \"card\",\n \"cardDetails\": {\n \"number\": \"4111111111111111\",\n \"expiryMonth\": \"12\",\n \"expiryYear\": \"25\",\n \"cvc\": \"123\"\n },\n \"persist\": false\n },\n \"amount\": 250,\n \"currency\": \"MXN\",\n \"description\": \"Payment for order #12345\",\n \"externalId\": \"ORDER-12345\",\n \"billingAddress\": {\n \"address\": \"Av. Reforma 123\",\n \"city\": \"Mexico City\",\n \"state\": \"CDMX\",\n \"postalCode\": \"01000\",\n \"country\": \"MX\"\n },\n \"metadata\": {\n \"orderId\": \"ORD-123\",\n \"source\": \"web\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "123e4567-e89b-12d3-a456-426614174000",
"externalMerchantReference": "ORDER-12345",
"amount": 250,
"orderNumber": "C25123101",
"currency": "MXN",
"status": "PENDING",
"description": "Payment for order #12345",
"metadata": {
"orderId": "ORD-123",
"source": "web"
},
"createdAt": "2025-10-20T10:00:00.000Z",
"paymentMethod": {
"type": "card",
"cardDetails": {
"last4": "1111",
"brand": "VISA",
"country": "US",
"expiryMonth": "12",
"expiryYear": "25"
}
},
"customer": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"phoneNumber": "+525512345678"
}
}Authorizations
API key for authentication (required)
Merchant ID for identifying the merchant (required)
Body
- Option 1
- Option 2
Show child attributes
Show child attributes
Payment amount (must be positive)
x > 0100.5
Three-letter currency code (ISO 4217)
3"MXN"
External reference ID from merchant system (required)
1"ORDER-12345"
When set to true, creates the payment order in PENDING status without processing payment immediately. The payment can later be charged using the charge endpoint (POST /v2/payment-orders/{id}/charge). When pending is true, paymentMethod is not required.
When set to true, the order accepts multiple Payments via the addPayment endpoint (POST /v2/payment-orders/{id}/payments) until the order amount is fully covered. While the order is open, the merchant can use mixed payment methods (CARD, SPEI, CIE, PayCash) across the same order. A refund on any of those Payments re-activates the order back to PARTIALLY_PAID so a new Payment can fill the gap. Only honored when pending: true — orders with a synchronous payment method on creation are not split-tender.
Payment method to use for the order. Required when pending is false (default). Not required when pending is true — in that case, the payment method is provided later via the charge endpoint.
- Option 1
- Option 2
- Option 3
- Option 4
Show child attributes
Show child attributes
Payment order description
"Payment for order #12345"
Merchant-provided invoice number; shown to customers instead of orderNumber when present
64"INV-2026-001"
Billing address (required when paymentMethod.type is 'card')
Show child attributes
Show child attributes
Device and browser information for fraud detection
Show child attributes
Show child attributes
Arbitrary JSON metadata to store with the payment order
{ "orderId": "ORD-123", "source": "web" }
Whether the payment originates from a Virtual Terminal. When true, the 3DS flow is skipped in the Decision Manager.
Optional due date for the payment order. Used for payment reminders. Must be an ISO 8601 date-time string.
"2026-04-15T00:00:00.000Z"
End customer's fiscal data, used to issue the CFDI when the order is stamped. All fields optional — taxId (RFC) can be added later via the manual stamp endpoint with fiscalConfig override.
Show child attributes
Show child attributes
Line items that make up the order. The sum of quantity * unitPrice across all items must equal the order amount (with a 0.001 tolerance). Used to populate the CFDI conceptos when stamping.
Show child attributes
Show child attributes
Response
Payment order created successfully
Payment order unique identifier
"123e4567-e89b-12d3-a456-426614174000"
Total amount charged to the customer (subtotalAmount + surchargeAmount).
257.5
Currency code
"MXN"
Payment order status
PENDING, PROCESSING, REFERENCE_GENERATED, AUTHORIZED, PARTIALLY_AUTHORIZED, ACTION_REQUIRED, COMPLETED, PARTIALLY_PAID, CANCELLATION_REQUESTED, CANCELLED, FAILED, REFUND_PROCESSING, PARTIALLY_REFUNDED, REFUNDED "PENDING"
External merchant reference ID
"ORDER-12345"
Merchandise subtotal — the amount agreed before any surcharge. Immutable after order creation.
250
Surcharge applied on top of subtotalAmount. Null when no surcharge applies.
7.5
Snapshot of the merchant's surcharge rate (percent) at charge time. Null when no surcharge applies.
3
System-generated order number
"C25123101"
Payment order description
"Payment for order #12345"
Arbitrary JSON metadata stored with the payment order
{ "orderId": "ORD-123", "source": "web" }
Due date for the payment order
"2026-04-15T00:00:00.000Z"
Timestamp when the payment order first reached COMPLETED (actual payment date, not creation).
"2025-10-20T10:05:00.000Z"
Timestamp when the payment order was first refunded.
"2025-10-21T09:00:00.000Z"
Creation timestamp
"2025-10-20T10:00:00.000Z"
Show child attributes
Show child attributes
Echoes the allowPartials flag from creation. When true, the order accepts additional Payments via the addPayment endpoint until it is fully covered.
true
Cumulative sum of captured amounts on this order. On split-tender orders that get partially refunded and re-paid, this can grow beyond amount because it is a historical ledger; use amountPending (or compute amountPaid - amountRefunded) to know the live balance.
200
Outstanding amount left to cover, derived as max(0, amount - (amountPaid - amountRefunded)). Reaches 0 when the order is fully paid net of refunds.
50
Cumulative sum of refunded amounts across the order's Payments. Like amountPaid, this is a historical ledger and is bounded per Payment by module-payment.
50
The Payment that triggered this response (the one just created for the addPayment / charge call, or the original Payment for a regular create).
Show child attributes
Show child attributes
All Payments associated with this order, ordered by creation time (oldest first), including the one in the payment field. Useful for split-tender clients that need to enumerate every Payment.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
3DS authentication details (when required)
Show child attributes
Show child attributes