Soft delete a payment order

curl --request DELETE \
  --url https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/{id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-merchant-id: <api-key>' \
  --data '
{
  "reason": "<string>"
}
'

import requests

url = "https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/{id}"

payload = { "reason": "<string>" }
headers = {
    "x-api-key": "<api-key>",
    "x-merchant-id": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.delete(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'DELETE',
  headers: {
    'x-api-key': '<api-key>',
    'x-merchant-id': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({reason: '<string>'})
};

fetch('https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/{id}', 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/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => json_encode([
    'reason' => '<string>'
  ]),
  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/{id}"

	payload := strings.NewReader("{\n  \"reason\": \"<string>\"\n}")

	req, _ := http.NewRequest("DELETE", 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.delete("https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/{id}")
  .header("x-api-key", "<api-key>")
  .header("x-merchant-id", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reason\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["x-api-key"] = '<api-key>'
request["x-merchant-id"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"reason\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "856b4a29-a7e5-4726-87d4-77e55d5ecfbf",
  "externalId": "ORDER-123",
  "refundedAmount": 0,
  "amount": 100.5,
  "currency": "USD",
  "status": "PENDING",
  "payments": [
    {
      "id": "856b4a29-a7e5-4726-87d4-77e55d5ecfbf",
      "status": "PENDING_CAPTURE",
      "paymentMethodType": "SPEI",
      "amount": "200.99",
      "refundedAmount": "0.00",
      "currency": "USD",
      "paymentMethodId": "<string>",
      "lastFailedEventReason": "Insufficient funds",
      "lastFailedEventAt": "2025-05-19T18:14:32.424Z",
      "createdAt": "2025-05-19T18:14:32.424Z",
      "updatedAt": "2025-05-19T18:14:32.523Z",
      "billingFirstName": "<string>",
      "billingLastName": "<string>",
      "billingPhoneNumber": "<string>",
      "billingEmail": "jsmith@example.com",
      "billingAddressLine1": "<string>",
      "billingAddressLine2": "<string>",
      "billingCity": "<string>",
      "billingState": "<string>",
      "billingPostalCode": "<string>",
      "billingCountry": "<string>",
      "paymentEvents": [
        {
          "id": "evt-123",
          "action": "AUTHORIZATION",
          "status": "SUCCESS",
          "createdAt": "2025-05-19T18:14:32.424Z",
          "amount": "100.50",
          "currency": "USD",
          "reason": null
        }
      ]
    }
  ],
  "subtotalAmount": 100000,
  "surchargeAmount": 5000,
  "surchargeRate": 5,
  "amountPaid": 50000,
  "amountPending": 55000,
  "allowPartials": false,
  "invoiceType": "PUE",
  "invoiceStatus": "INVOICED",
  "fiscalUuid": "b1c2d3e4-f5g6-h7i8-j9k0-l1m2n3o4p5q6",
  "complements": [
    {
      "id": "9c8b7a6d-5e4f-3c2b-1a0f-9e8d7c6b5a4d",
      "paymentId": "a0b0c9d4-6ce9-40e4-873a-e234c1d93639",
      "amount": 25000,
      "status": "EMITTED",
      "paymentEventId": "20912eee-6047-40c7-97b4-48501bb36ef4",
      "fiscalUuid": "b1c2d3e4-f5g6-h7i8-j9k0-l1m2n3o4p5q6",
      "fiscalInvoiceId": "6a710705bd1842a3122c70ff",
      "pdfKey": "invoices/mch_test_001/order-uuid/rep-payment-uuid.pdf",
      "emittedAt": "2026-08-06T05:37:35.760Z",
      "createdAt": "2026-08-06T05:37:30.100Z"
    }
  ],
  "creditNotes": [
    {
      "id": "9c8b7a6d-5e4f-3c2b-1a0f-9e8d7c6b5a4d",
      "paymentId": "a0b0c9d4-6ce9-40e4-873a-e234c1d93639",
      "amount": 25000,
      "status": "EMITTED",
      "paymentEventId": "20912eee-6047-40c7-97b4-48501bb36ef4",
      "fiscalUuid": "b1c2d3e4-f5g6-h7i8-j9k0-l1m2n3o4p5q6",
      "fiscalInvoiceId": "6a710705bd1842a3122c70ff",
      "pdfKey": "invoices/mch_test_001/order-uuid/rep-payment-uuid.pdf",
      "emittedAt": "2026-08-06T05:37:35.760Z",
      "createdAt": "2026-08-06T05:37:30.100Z"
    }
  ],
  "invoiceSummary": {
    "capturedCount": 4,
    "emittedRepCount": 3,
    "pendingRepCount": 0,
    "failedRepCount": 1,
    "refundEventCount": 1,
    "emittedCreditNoteCount": 1,
    "pendingCreditNoteCount": 0,
    "failedCreditNoteCount": 0,
    "isFullyStamped": false
  },
  "orderNumber": "C25123101",
  "invoiceNumber": "INV-2026-001",
  "description": "Payment for order #123",
  "metadata": {
    "orderId": "ORD-123",
    "source": "web"
  },
  "billingAddressLine": "123 Main St",
  "billingCity": "New York",
  "billingState": "NY",
  "billingPostalCode": "10001",
  "billingCountry": "US",
  "customer": {
    "externalId": "CUST-123",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phoneNumber": "+1234567890",
    "active": true,
    "createdAt": "2024-03-20T10:00:00Z",
    "updatedAt": "2024-03-20T10:00:00Z"
  },
  "dueDate": "2026-04-15T00:00:00.000Z",
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-20T10:00:00Z",
  "paymentMethod": {
    "id": "856b4a29-a7e5-4726-87d4-77e55d5ecfbf",
    "type": "CARD",
    "cardDetails": {
      "id": "<string>",
      "type": "CREDIT",
      "bin": "411111",
      "last4": "1111",
      "brand": "VISA",
      "country": "US",
      "issuerBank": "CHASE",
      "expMonth": 12,
      "expYear": 2025,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    },
    "speiDetails": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "clabe": "123456789012345678",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    },
    "cieDetails": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "reference": "CIE0000000001",
      "convenio": "0123456789",
      "clabe": "012345678901234567",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  }
}

{
  "message": "Validation failed",
  "errors": [
    {
      "field": "name",
      "message": "Required"
    }
  ]
}

{
  "message": "Invalid api key"
}

{
  "message": "Merchant not found"
}

{
  "message": "Error message"
}

{
  "message": "Error message"
}

DELETE

payment-orders

{id}

Soft delete a payment order

curl --request DELETE \
  --url https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/{id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-merchant-id: <api-key>' \
  --data '
{
  "reason": "<string>"
}
'

import requests

url = "https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/{id}"

payload = { "reason": "<string>" }
headers = {
    "x-api-key": "<api-key>",
    "x-merchant-id": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.delete(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'DELETE',
  headers: {
    'x-api-key': '<api-key>',
    'x-merchant-id': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({reason: '<string>'})
};

fetch('https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/{id}', 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/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_POSTFIELDS => json_encode([
    'reason' => '<string>'
  ]),
  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/{id}"

	payload := strings.NewReader("{\n  \"reason\": \"<string>\"\n}")

	req, _ := http.NewRequest("DELETE", 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.delete("https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/{id}")
  .header("x-api-key", "<api-key>")
  .header("x-merchant-id", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reason\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.cheqpay.mx/pos/v2/payment-orders/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["x-api-key"] = '<api-key>'
request["x-merchant-id"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"reason\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "856b4a29-a7e5-4726-87d4-77e55d5ecfbf",
  "externalId": "ORDER-123",
  "refundedAmount": 0,
  "amount": 100.5,
  "currency": "USD",
  "status": "PENDING",
  "payments": [
    {
      "id": "856b4a29-a7e5-4726-87d4-77e55d5ecfbf",
      "status": "PENDING_CAPTURE",
      "paymentMethodType": "SPEI",
      "amount": "200.99",
      "refundedAmount": "0.00",
      "currency": "USD",
      "paymentMethodId": "<string>",
      "lastFailedEventReason": "Insufficient funds",
      "lastFailedEventAt": "2025-05-19T18:14:32.424Z",
      "createdAt": "2025-05-19T18:14:32.424Z",
      "updatedAt": "2025-05-19T18:14:32.523Z",
      "billingFirstName": "<string>",
      "billingLastName": "<string>",
      "billingPhoneNumber": "<string>",
      "billingEmail": "jsmith@example.com",
      "billingAddressLine1": "<string>",
      "billingAddressLine2": "<string>",
      "billingCity": "<string>",
      "billingState": "<string>",
      "billingPostalCode": "<string>",
      "billingCountry": "<string>",
      "paymentEvents": [
        {
          "id": "evt-123",
          "action": "AUTHORIZATION",
          "status": "SUCCESS",
          "createdAt": "2025-05-19T18:14:32.424Z",
          "amount": "100.50",
          "currency": "USD",
          "reason": null
        }
      ]
    }
  ],
  "subtotalAmount": 100000,
  "surchargeAmount": 5000,
  "surchargeRate": 5,
  "amountPaid": 50000,
  "amountPending": 55000,
  "allowPartials": false,
  "invoiceType": "PUE",
  "invoiceStatus": "INVOICED",
  "fiscalUuid": "b1c2d3e4-f5g6-h7i8-j9k0-l1m2n3o4p5q6",
  "complements": [
    {
      "id": "9c8b7a6d-5e4f-3c2b-1a0f-9e8d7c6b5a4d",
      "paymentId": "a0b0c9d4-6ce9-40e4-873a-e234c1d93639",
      "amount": 25000,
      "status": "EMITTED",
      "paymentEventId": "20912eee-6047-40c7-97b4-48501bb36ef4",
      "fiscalUuid": "b1c2d3e4-f5g6-h7i8-j9k0-l1m2n3o4p5q6",
      "fiscalInvoiceId": "6a710705bd1842a3122c70ff",
      "pdfKey": "invoices/mch_test_001/order-uuid/rep-payment-uuid.pdf",
      "emittedAt": "2026-08-06T05:37:35.760Z",
      "createdAt": "2026-08-06T05:37:30.100Z"
    }
  ],
  "creditNotes": [
    {
      "id": "9c8b7a6d-5e4f-3c2b-1a0f-9e8d7c6b5a4d",
      "paymentId": "a0b0c9d4-6ce9-40e4-873a-e234c1d93639",
      "amount": 25000,
      "status": "EMITTED",
      "paymentEventId": "20912eee-6047-40c7-97b4-48501bb36ef4",
      "fiscalUuid": "b1c2d3e4-f5g6-h7i8-j9k0-l1m2n3o4p5q6",
      "fiscalInvoiceId": "6a710705bd1842a3122c70ff",
      "pdfKey": "invoices/mch_test_001/order-uuid/rep-payment-uuid.pdf",
      "emittedAt": "2026-08-06T05:37:35.760Z",
      "createdAt": "2026-08-06T05:37:30.100Z"
    }
  ],
  "invoiceSummary": {
    "capturedCount": 4,
    "emittedRepCount": 3,
    "pendingRepCount": 0,
    "failedRepCount": 1,
    "refundEventCount": 1,
    "emittedCreditNoteCount": 1,
    "pendingCreditNoteCount": 0,
    "failedCreditNoteCount": 0,
    "isFullyStamped": false
  },
  "orderNumber": "C25123101",
  "invoiceNumber": "INV-2026-001",
  "description": "Payment for order #123",
  "metadata": {
    "orderId": "ORD-123",
    "source": "web"
  },
  "billingAddressLine": "123 Main St",
  "billingCity": "New York",
  "billingState": "NY",
  "billingPostalCode": "10001",
  "billingCountry": "US",
  "customer": {
    "externalId": "CUST-123",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phoneNumber": "+1234567890",
    "active": true,
    "createdAt": "2024-03-20T10:00:00Z",
    "updatedAt": "2024-03-20T10:00:00Z"
  },
  "dueDate": "2026-04-15T00:00:00.000Z",
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-20T10:00:00Z",
  "paymentMethod": {
    "id": "856b4a29-a7e5-4726-87d4-77e55d5ecfbf",
    "type": "CARD",
    "cardDetails": {
      "id": "<string>",
      "type": "CREDIT",
      "bin": "411111",
      "last4": "1111",
      "brand": "VISA",
      "country": "US",
      "issuerBank": "CHASE",
      "expMonth": 12,
      "expYear": 2025,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    },
    "speiDetails": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "clabe": "123456789012345678",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    },
    "cieDetails": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "reference": "CIE0000000001",
      "convenio": "0123456789",
      "clabe": "012345678901234567",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  }
}

{
  "message": "Validation failed",
  "errors": [
    {
      "field": "name",
      "message": "Required"
    }
  ]
}

{
  "message": "Invalid api key"
}

{
  "message": "Merchant not found"
}

{
  "message": "Error message"
}

{
  "message": "Error message"
}

Authorizations

x-api-key

string

header

required

API key for authentication (required)

x-merchant-id

string

header

required

Merchant ID for identifying the merchant (required)

Path Parameters

string

required

Payment order unique identifier or external ID

Minimum string length: 1

Body

application/json

reason

string

Optional reason for deleting the payment order. Trimmed before validation; must not exceed 255 characters.

Maximum string length: 255

Response

Payment order soft deleted successfully (or was already deleted)

string

required

Unique payment order ID

Example:

"856b4a29-a7e5-4726-87d4-77e55d5ecfbf"

externalId

string

required

External payment order ID from merchant system

Example:

"ORDER-123"

refundedAmount

number

required

Total refunded amount across all payments (in cents)

Example:

0

amount

number

required

Payment amount

Example:

100.5

currency

string

required

Three-letter currency code (ISO 4217)

Example:

"USD"

status

enum<string>

required

Payment order status

Available options:

PENDING,

PROCESSING,

REFERENCE_GENERATED,

AUTHORIZED,

PARTIALLY_AUTHORIZED,

ACTION_REQUIRED,

COMPLETED,

PARTIALLY_PAID,

CANCELLATION_REQUESTED,

CANCELLED,

FAILED,

REFUND_PROCESSING,

PARTIALLY_REFUNDED,

REFUNDED

payments

object[]

required

List of payments for a payment order, Note: this information is only available on the order details endpoint

Show child attributes

subtotalAmount

number | null

Pre-surcharge subtotal in minor units. Equals amount when no surcharge applies. Null on legacy orders predating subtotal tracking.

Example:

100000

surchargeAmount

number | null

Surcharge component of amount in minor units, or null when none. On split-tender orders this grows as each partial's surcharge lands and shrinks on refund.

Example:

5000

surchargeRate

number | null

Snapshot of the merchant's surcharge rate (percent) captured at order creation, or null when no surcharge applies.

Example:

5

amountPaid

number

Cumulative sum of captured amounts across this order's Payments (in minor units). Historical ledger — on re-activable orders that get partially refunded and re-paid, this can exceed amount. Use amountPending for live balance.

Example:

50000

amountPending

number

Outstanding amount left to cover net of refunds (in minor units). Computed as max(0, amount - (amountPaid - amountRefunded)). Reaches 0 when the order is fully paid net of any refunds — the only live-balance field on the snapshot.

Example:

55000

allowPartials

boolean

True when the order accepts multiple Payments via POST /v2/payment-orders/{id}/payments. Set at creation time.

Example:

false

invoiceType

enum<string> | null

CFDI invoice type derived from the flow. PUE for legacy 1:1 orders (single CFDI). PPD for split-tender orders (parent + REP per capture + credit note per refund). Null when the order is not fiscal.

Available options:

PUE,

PPD

Example:

"PUE"

invoiceStatus

enum<string> | null

Overall CFDI status. For PPD this reflects the parent CFDI; use invoiceSummary for per-REP / per-credit-note granularity.

Available options:

PENDING,

INVOICED,

FAILED

Example:

"INVOICED"

fiscalUuid

string | null

SAT UUID (folio fiscal) of the parent CFDI. Present once invoiceStatus = INVOICED.

Example:

"b1c2d3e4-f5g6-h7i8-j9k0-l1m2n3o4p5q6"

complements

object[]

PPD-only: emitted REP complements (Recibos Electrónicos de Pago). One row per successfully-stamped Payment. Always present as an array (empty [] for PUE / non-fiscal orders).

Show child attributes

creditNotes

object[]

PPD-only: emitted Notas de Crédito. One row per successfully-stamped refund event. Always present as an array (empty [] for PUE / non-fiscal orders).

Show child attributes

invoiceSummary

object

PPD-only: aggregated stamping progress. Undefined for PUE and non-fiscal orders — the UI should treat its absence as 'not a PPD order'.

Show child attributes

orderNumber

string

Unique order number generated by the system

Example:

"C25123101"

invoiceNumber

string | null

Merchant-provided invoice number; shown to customers instead of orderNumber when present

Maximum string length: 64

Example:

"INV-2026-001"

description

string

Payment description

Example:

"Payment for order #123"

metadata

object | null

Arbitrary JSON metadata stored with the payment order

Example:

{ "orderId": "ORD-123", "source": "web" }

billingAddressLine

string

Billing address line

Example:

"123 Main St"

billingCity

string

Billing city

Example:

"New York"

billingState

string

Billing state

Example:

"NY"

billingPostalCode

string

Billing postal code

Example:

"10001"

billingCountry

string

Billing country code

Example:

"US"

customer

object

Show child attributes

dueDate

string<date-time> | null

Due date for the payment order. Used for payment reminder notifications.

Example:

"2026-04-15T00:00:00.000Z"

createdAt

string<date-time>

Payment order creation timestamp

Example:

"2024-03-20T10:00:00Z"

updatedAt

string<date-time>

Payment order last update timestamp

Example:

"2024-03-20T10:00:00Z"

paymentMethod

object

Show child attributes

Getting Started

Essentials

Features

Testing

Guides

API Reference

Payment Orchestrator API

Link Product API

Soft delete a payment order

Authorizations

Path Parameters

Body

Response