Card Payments

Accept Card Payments

Accept card payments in a single API request. Process credit and debit cards from Visa, Mastercard, and American Express through a unified checkout experience.

PCI Compliance RequiredIf you integrate directly with the Payments API and handle raw card data (card number, CVV, expiry), your business must be PCI DSS compliant. This involves annual security audits, network scans, and strict security controls.Not PCI compliant? Use our hosted payment page or JavaScript SDK instead - these solutions keep card data off your servers and remove PCI compliance requirements from your business.Contact support@cheqpay.mx to learn about hosted payment options.

Create a Card Payment

POST /checkout/pay
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_MERCHANT_ID
Content-Type: application/json

Complete Request 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"
    }
  }
}

Successful 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"
    }
  }
}

What Happens During Payment

Customer Created or Updated

Cheqpay creates a new customer record or updates an existing one based on the externalId.

Card Tokenized

The card is securely tokenized. Sensitive data never touches your servers.

Authorization

The payment is authorized by the card network (Visa, Mastercard, Amex).

Funds Captured

Funds are captured immediately upon successful authorization.

Status Updated

Payment status updates to COMPLETED and you can fulfill the order.

Customer Notified

Customer receives a confirmation email (if notifications are enabled).

The entire process typically takes 2-5 seconds for successful payments.

Card Surcharge

Merchants enrolled in the surcharge program can pass the card processing fee on to the cardholder. When active, the payment order’s total is increased by the surcharge and satisfies:

amount = subtotalAmount + surchargeAmount

How it works:

The surcharge is configured at the merchant level in Cheqpay Suite: a percentage rate applied over the order subtotal, with an optional per-transaction cap. The program must be enabled for your account by Cheqpay and switched on by you.
It applies to card payments only — SPEI and cash methods are never surcharged; if the customer pays an order with a non-card method, the order is charged at the subtotal with no surcharge.
By default it applies to credit cards and American Express only (debit cards are not surcharged). An “all cards” mode is available on request.
Because the card type is only known when the customer presents the card, the surcharge is computed per charge attempt, and the order amount is re-derived at that point.
The applied values are returned on the payment order object as surchargeAmount and surchargeRate (the rate is a snapshot of your configuration at charge time), and a payer-facing line-item label can be configured.

If your integration validates order totals, always compare against subtotalAmount for your merchandise total and treat amount as subtotalAmount + surchargeAmount — a card charge may legitimately exceed the subtotal you requested.

Required Fields

Payment Information

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)
`description`	string	No	Payment description

Customer Information

Field	Type	Required	Description
`customer.firstName`	string	Yes	Customer’s first name
`customer.lastName`	string	Yes	Customer’s last name
`customer.email`	string	Yes	Customer’s email address
`customer.phoneNumber`	string	No	Phone with country code
`customer.externalId`	string	No	Your customer ID

Card Details

Field	Type	Required	Description
`paymentMethod.type`	string	Yes	Must be “card”
`paymentMethod.cardDetails.number`	string	Yes	Card number (13-19 digits)
`paymentMethod.cardDetails.expiryMonth`	string	Yes	Expiry month (01-12)
`paymentMethod.cardDetails.expiryYear`	string	Yes	Expiry year (2-digit YY format, e.g., “25” for 2025)
`paymentMethod.cardDetails.cvc`	string	Yes	Card security code

Billing Address (Required)

Billing address is required for all card payments:

{
  "billingAddress": {
    "address": "Av. Reforma 123",
    "city": "Mexico City",
    "state": "CDMX",
    "postalCode": "01000",
    "country": "MX"
  }
}

Billing address is required when processing card payments. Including complete billing information also helps improve approval rates by 3-5%.

Save Cards for Future Use

Enable one-click checkout by saving the card:

{
  "paymentMethod": {
    "type": "card",
    "cardDetails": {
      "number": "4000000000002503",
      "expiryMonth": "12",
      "expiryYear": "25",
      "cvc": "123"
    },
    "persist": true
  }
}

The response includes a paymentMethodId you can use for future charges:

{
  "paymentMethod": {
    "id": "pm_abc123",
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "1111"
    }
  }
}

Learn More About Saved Cards

View complete payment methods documentation

Charge a Saved Card

Use a previously saved card with just the payment method ID:

{
  "externalId": "order-456",
  "amount": 5000,
  "currency": "MXN",
  "paymentMethod": {
    "type": "payment_method_id",
    "paymentMethodId": "pm_abc123",
    "cvc": "123"
  }
}

Always collect the CVC for saved card payments. This improves approval rates and reduces fraud.

Handle Authentication (3D Secure)

Some payments require 3D Secure authentication. When this happens, the status will be PAYER_AUTHENTICATION_CHALLENGE_REQUIRED:

{
  "paymentOrder": {
    "id": "ord_abc123",
    "status": "PAYER_AUTHENTICATION_CHALLENGE_REQUIRED"
  },
  "payerAuthentication": {
    "stepUpUrl": "https://...",
    "jwt": "eyJhbGc..."
  }
}

You’ll need to show an authentication challenge to the customer.

Complete 3D Secure Guide

Learn how to implement 3D Secure authentication

Improve Approval Rates

Include Device Information

Sending device data helps banks assess risk and approve more payments:

{
  "deviceInformation": {
    "ipAddress": "192.168.1.100",
    "userAgent": "Mozilla/5.0...",
    "httpBrowserLanguage": "es-MX",
    "httpBrowserScreenWidth": "1920",
    "httpBrowserScreenHeight": "1080"
  }
}

Best Practices

Include Billing Address

Billing address verification helps prevent fraud and improves approval rates by 3-5%.

Send Device Data

Device information enables better fraud detection and smoother 3D Secure flows.

Use Consistent Customer Data

Keep customer information consistent across payments for better approval rates.

Save Payment Methods

Returning customers with saved cards have higher approval rates.

Error Handling

Handle declined payments gracefully:

{
  "error": {
    "code": "DECLINED",
    "message": "Payment declined by issuing bank",
    "declineReason": "insufficient_funds"
  }
}

Error Handling Guide

Learn how to handle errors and declined payments

Testing

Use these test cards in sandbox:

Card Number	Brand	Result
4000000000002503	Visa	Successful payment
5200000000002151	Mastercard	Successful payment
4000000000000002	Visa	Card declined

Complete Testing Guide

View all test scenarios and cards

Next Steps

Handle 3D Secure

Implement card authentication

Save Payment Methods

Store cards for returning customers

Process Refunds

Issue full or partial refunds

Set Up Webhooks

Get real-time payment notifications

Getting Started

Essentials

Features

Testing

Guides

API Reference

Payment Orchestrator API

Link Product API

Accept Card Payments

Create a Card Payment

Complete Request Example

Successful Response

What Happens During Payment

Card Surcharge

Required Fields

Payment Information

Customer Information

Card Details

Billing Address (Required)

Save Cards for Future Use

Learn More About Saved Cards

Charge a Saved Card

Handle Authentication (3D Secure)

Complete 3D Secure Guide

Improve Approval Rates

Include Device Information

Best Practices

Error Handling

Error Handling Guide

Testing

Complete Testing Guide

Next Steps

Handle 3D Secure

Save Payment Methods

Process Refunds

Set Up Webhooks

​Accept Card Payments

​Create a Card Payment

​Complete Request Example

​Successful Response

​What Happens During Payment

​Card Surcharge

​Required Fields

​Payment Information

​Customer Information

​Card Details

​Billing Address (Required)

​Save Cards for Future Use

Learn More About Saved Cards

​Charge a Saved Card

​Handle Authentication (3D Secure)

Complete 3D Secure Guide

​Improve Approval Rates

​Include Device Information

​Best Practices

​Error Handling

Error Handling Guide

​Testing

Complete Testing Guide

​Next Steps

Handle 3D Secure

Save Payment Methods

Process Refunds

Set Up Webhooks

Accept Card Payments

Create a Card Payment

Complete Request Example

Successful Response

What Happens During Payment

Card Surcharge

Required Fields

Payment Information

Customer Information

Card Details

Billing Address (Required)

Save Cards for Future Use

Charge a Saved Card

Handle Authentication (3D Secure)

Improve Approval Rates

Include Device Information

Best Practices

Error Handling

Testing

Next Steps