Testing Guide - Cheqpay

Sandbox Environment

Test your integration thoroughly in our sandbox environment before going live. No real money, no risk. Our sandbox works exactly like production - same API, same behavior:

https://api.cheqpay.dev/pos

Sandbox Features

No Real Money

Process test payments without financial risk

Test Cards

Use pre-defined test card numbers for success, decline, and 3DS scenarios

Full Feature Parity

All production features available in sandbox

Faster Processing

Instant processing for rapid testing

Offline payment methods (SPEI, PayCash, and CIE Cash Net) use separate sandbox flows — they do not use test card numbers. See the guides below:

Payment method	Sandbox testing	Feature guide
SPEI	Mock transfers can auto-complete; use webhook simulators for STP/OPM	SPEI Transfers
PayCash	Does not auto-complete; use the PayCash simulator	PayCash Payments
CIE Cash Net	Does not auto-complete; use the CIE Cash Net simulator	CIE Cash Net Payments

Test Cards

Use these cards to test different scenarios:

Successful Payments

Card Number	Brand	Behavior
`4000000000002503`	Visa	Successful payment
`5200000000002151`	Mastercard	Successful payment

For 3D Secure (3DS) testing, see the complete 3DS testing guide which includes specific test cards and amount thresholds for different 3DS scenarios.

Failed Payments

In sandbox, declines are triggered by the transaction amount, not the card number. You can use any of the test card numbers listed under “Successful Payments” (or a generic test card) — what determines the response is the amount you submit.

How it works

The amount must end in two specific digits that map to a known decline reason. Use a base amount of 9000.xx where xx is the response code you want to trigger. The same trigger amounts apply to all supported currencies (MXN, USD) in sandbox.

Amounts in the API are submitted as integers in the smallest currency unit (cents).
Example (MXN): to trigger “Expired card” (code 33), submit amount: 900033 with currency: "MXN" (= 9000.33 MXN).
Example (USD): to trigger “No sufficient funds” (code 51), submit amount: 900051 with currency: "USD" (= 9000.51 USD).

This amount-based trigger mechanism is only available in sandbox. In production, the same amounts are processed normally and will not generate synthetic declines.

Any other amount that does not match an entry below will be approved. To test a successful payment, use any amount that does not end in one of the listed two-digit codes.

Decline trigger amounts

Amount (MXN)	API value (cents)	Decline reason
9000.01	`900001`	Refer to card issuer
9000.02	`900002`	Refer to special conditions for card issuer
9000.03	`900003`	Invalid merchant
9000.04	`900004`	Pick-up card
9000.05	`900005`	Do not honor
9000.06	`900006`	Error
9000.07	`900007`	Pick-up card, special condition
9000.09	`900009`	Request in progress (duplicate)
9000.12	`900012`	Invalid transaction
9000.13	`900013`	Invalid amount
9000.14	`900014`	Invalid card number (no such number)
9000.15	`900015`	No such issuer
9000.17	`900017`	Customer cancellation
9000.22	`900022`	Suspected malfunction
9000.30	`900030`	Format error
9000.31	`900031`	Bank not supported by switch
9000.33	`900033`	Expired card
9000.34	`900034`	Suspected fraud
9000.35	`900035`	Card acceptor contact acquirer
9000.36	`900036`	Restricted card
9000.37	`900037`	Card acceptor call acquirer security
9000.38	`900038`	Allowable PIN tries exceeded
9000.39	`900039`	No credit account
9000.40	`900040`	Command rejected
9000.41	`900041`	Lost card
9000.43	`900043`	Stolen card, pick-up
9000.51	`900051`	No sufficient funds
9000.54	`900054`	Expired card
9000.55	`900055`	Incorrect personal identification number
9000.56	`900056`	No card record
9000.57	`900057`	Transaction not permitted to cardholder
9000.58	`900058`	Transaction not permitted to terminal
9000.61	`900061`	Exceeds withdrawal amount limit
9000.62	`900062`	Restricted card
9000.65	`900065`	Exceeds withdrawal frequency limit
9000.68	`900068`	Response received too late

Test Card Details

For all test cards:

Expiry Date: Any future date (e.g., 12/2025)
CVC: Any 3 digits (e.g., 123)
Billing Address: Any valid address

Test cards work only in sandbox. They will be rejected in production.

Consistency between runs: because the response is determined by the amount, you must keep the amount fixed across executions of the same scenario. Changing the amount will change the response — even if the card stays the same.

Test 3D Secure

Test the complete 3DS authentication flow using specific test cards and amount thresholds.

Trigger 3DS Challenge

Use amounts >= 100,000 cents (1,000 MXN) with the 3DS test card:

curl -X POST https://api.cheqpay.dev/pos/payment-orders \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "test-3ds-001",
    "amount": 100000,
    "currency": "MXN",
    "paymentMethod": {
      "type": "card",
      "cardDetails": {
        "number": "4000000000002503",
        "expiryMonth": "12",
        "expiryYear": "25",
        "cvc": "123"
      }
    }
  }'

3DS Test Cards:

4000000000002503 with amount >= 100,000 cents triggers full 3DS challenge
4000000000002701 with amount >= 100,000 cents triggers frictionless 3DS
4000000000002701 with amount < 100,000 cents skips 3DS entirely

See the complete 3DS testing guide for all scenarios.

Complete Authentication

When prompted for a verification code in sandbox, use:

This simulates successful customer authentication.

Complete 3DS Guide

Learn how to implement 3D Secure authentication

Test Refunds

Refunds process instantly in sandbox (instead of 5-10 days in production):

# Create a successful payment
PAYMENT_ID=$(curl -X POST https://api.cheqpay.dev/pos/payment-orders \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -d '{"externalId": "test-001", "amount": 10000, ...}' \
  | jq -r '.paymentOrder.id')

# Issue a refund
curl -X POST https://api.cheqpay.dev/pos/payment-orders/$PAYMENT_ID/refund \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -d '{"reason": "Test refund"}'

Common Test Scenarios

Scenario 1: Successful Card Payment

curl -X POST https://api.cheqpay.dev/pos/payment-orders \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "test-001",
    "customer": {
      "firstName": "Test",
      "lastName": "User",
      "email": "test@example.com"
    },
    "amount": 10000,
    "currency": "MXN",
    "paymentMethod": {
      "type": "card",
      "cardDetails": {
        "number": "4000000000002503",
        "expiryMonth": "12",
        "expiryYear": "25",
        "cvc": "123"
      }
    }
  }'

Expected: Status COMPLETED, payment successful.

Scenario 2: Declined Payment

Trigger a decline by submitting one of the amounts listed in the Failed Payments table. Any test card works — the amount is what determines the response. The example below triggers Expired card (code 33) by submitting amount: 900033 (= 9000.33 MXN):

curl -X POST https://api.cheqpay.dev/pos/payment-orders \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "test-002",
    "amount": 900033,
    "currency": "MXN",
    "paymentMethod": {
      "type": "card",
      "cardDetails": {
        "number": "4000000000002503",
        "expiryMonth": "12",
        "expiryYear": "25",
        "cvc": "123"
      }
    }
  }'

Expected: Status FAILED with Expired card reason. To test a different decline reason, change the last two digits of the amount field to match the desired code from the table.

Same scenario in USD

The same trigger amounts work for any supported currency. The example below triggers No sufficient funds (code 51) in USD by submitting amount: 900051 with currency: "USD":

curl -X POST https://api.cheqpay.dev/pos/payment-orders \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "test-002-usd",
    "amount": 900051,
    "currency": "USD",
    "paymentMethod": {
      "type": "card",
      "cardDetails": {
        "number": "4000000000002503",
        "expiryMonth": "12",
        "expiryYear": "25",
        "cvc": "123"
      }
    }
  }'

Expected: Status FAILED with No sufficient funds reason.

Scenario 3: 3DS Authentication Flow

Create payment with 3DS card
Receive PAYER_AUTHENTICATION_CHALLENGE_REQUIRED status
Display authentication challenge
Customer enters code 123456
Validate authentication
Payment completes

Scenario 4: Save & Reuse Card

# 1. Save card during payment
curl -X POST https://api.cheqpay.dev/pos/payment-orders \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -d '{
    "externalId": "test-003",
    "amount": 10000,
    "currency": "MXN",
    "paymentMethod": {
      "type": "card",
      "cardDetails": {
        "number": "4000000000002503",
        "expiryMonth": "12",
        "expiryYear": "25",
        "cvc": "123"
      },
      "persist": true
    }
  }'

# 2. Get paymentMethodId from response
# 3. Use saved card for next payment
curl -X POST https://api.cheqpay.dev/pos/payment-orders \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -d '{
    "externalId": "test-004",
    "amount": 5000,
    "currency": "MXN",
    "paymentMethod": {
      "type": "payment_method_id",
      "paymentMethodId": "pm_xxx",
      "cvc": "123"
    }
  }'

Scenario 5: Idempotency Test

Send the same request twice with same externalId:

# First request
curl -X POST https://api.cheqpay.dev/pos/payment-orders \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -d '{"externalId": "test-005", "amount": 10000, ...}'

# Second request (duplicate)
curl -X POST https://api.cheqpay.dev/pos/payment-orders \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -d '{"externalId": "test-005", "amount": 10000, ...}'

Expected: Both requests return the same payment. No duplicate charge.

Integration Testing Checklist

Test these scenarios before going live:

Card Payment Processing

✅ Successful payment with Visa
✅ Successful payment with Mastercard
✅ Successful payment with Amex
✅ Declined payment handling
✅ Expired card error
✅ Invalid CVC error

3D Secure Authentication

✅ Trigger 3DS challenge
✅ Display authentication iframe
✅ Handle successful authentication
✅ Handle failed authentication
✅ Handle authentication timeout

Saved Payment Methods

✅ Save card during payment
✅ Charge saved card
✅ Handle expired saved card
✅ Update saved card

Refunds

✅ Full refund
✅ Partial refund
✅ Multiple partial refunds
✅ Handle refund errors

Error Handling

✅ Network errors
✅ Validation errors
✅ Declined payments
✅ Rate limiting
✅ Retry logic

Performance Testing

Test your integration under load:

// Example: Load test with 100 concurrent payments
const promises = [];
for (let i = 0; i < 100; i++) {
  promises.push(
    createPayment({
      externalId: `load-test-${i}`,
      amount: 10000,
      currency: 'MXN',
      // ...
    })
  );
}

const results = await Promise.allSettled(promises);
const successful = results.filter(r => r.status === 'fulfilled').length;
const failed = results.filter(r => r.status === 'rejected').length;

console.log(`Successful: ${successful}, Failed: ${failed}`);

Go Live Checklist

Ready to switch to production?

Get Production Credentials

Contact support@cheqpay.com for live API keys.

Update Base URL

Change from sandbox.cheqpay.com to api.cheqpay.com.

Provide your production webhook URL to support.

Secure Your Keys

Use environment variables, never hardcode keys.

Set Up Monitoring

Track payments, errors, and webhook delivery.

Test in Production

Process a small test transaction to verify everything works.

Going Live Guide

Complete production readiness checklist

Need Help?

API Reference

View complete API documentation

Error Handling

Learn how to handle errors

Best Practices

Follow recommended patterns

Contact Support

Get help from our team

​Sandbox Environment

​Sandbox Features

No Real Money

Test Cards

Full Feature Parity

Faster Processing

​Test Cards

​Successful Payments

​Failed Payments

​How it works

​Decline trigger amounts

​Test Card Details

​Test 3D Secure

​Trigger 3DS Challenge

​Complete Authentication

Complete 3DS Guide

​Test Refunds

​Common Test Scenarios

​Scenario 1: Successful Card Payment

​Scenario 2: Declined Payment

​Same scenario in USD

​Scenario 3: 3DS Authentication Flow

​Scenario 4: Save & Reuse Card

​Scenario 5: Idempotency Test

​Integration Testing Checklist

​Performance Testing

​Go Live Checklist

Going Live Guide

​Need Help?

API Reference

Error Handling

Best Practices

Contact Support

Sandbox Environment

Sandbox Features

Test Cards

Successful Payments

Failed Payments

How it works

Decline trigger amounts

Test Card Details

Test 3D Secure

Trigger 3DS Challenge

Complete Authentication

Test Refunds

Common Test Scenarios

Scenario 1: Successful Card Payment

Scenario 2: Declined Payment

Same scenario in USD

Scenario 3: 3DS Authentication Flow

Scenario 4: Save & Reuse Card

Scenario 5: Idempotency Test

Integration Testing Checklist

Performance Testing

Go Live Checklist

Need Help?