Card Payments

Accept Card Payments

Accept card payments in a single API request. Process credit and debit cards from Visa, Mastercard, and American Express. Each payment creates a payment order that you can track and manage.

Create a Card Payment

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

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

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": "[email protected]"
  },
  "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.

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 faster payments for returning customers 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 (3DS). The flow can be frictionless (no customer action) or require a challenge. Cheqpay guides you through three steps.

Step 1 — Collect Device Data (Invisible Iframe)

When 3DS is needed, the payment order returns PAYER_AUTHENTICATION_DEVICE_DATA_REQUIRED with a device collection URL and JWT:

{
  "paymentOrder": {
    "id": "ord_abc123",
    "status": "PAYER_AUTHENTICATION_DEVICE_DATA_REQUIRED"
  },
  "payerAuthentication": {
    "url": "https://...",
    "jwt": "eyJhbGc..."
  }
}

Render the URL in an invisible iframe and auto-submit the JWT.

<iframe id="pa-iframe" width="0" height="0" style="display:none"></iframe>
<form id="pa-form" method="POST" target="pa-iframe">
  <input type="hidden" name="JWT" value="{jwt-from-response}" />
  <noscript><input type="submit" value="Continue" /></noscript>
  
</form>
<script>
  document.getElementById('pa-form').action = '{url-from-response}';
  document.getElementById('pa-form').submit();
</script>

Step 2 — Check Enrollment

After device collection completes, call the enrollment check endpoint:

POST /v2/payment-orders/:id/payer-authentication

Possible outcomes:

COMPLETED — Frictionless approval (no challenge). You are done.
FAILED — Declined. Show an error to the customer.
PAYER_AUTHENTICATION_CHALLENGE_REQUIRED — Show the 3DS challenge using the provided stepUpUrl and jwt.

Example response when a challenge is required:

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

Display the challenge in an iframe and submit the JWT:

<iframe id="3ds-iframe" width="400" height="600"></iframe>
<form id="3ds-form" method="POST" target="3ds-iframe">
  <input type="hidden" name="JWT" value="{jwt-from-response}" />
  
</form>
<script>
  document.getElementById('3ds-form').action = '{stepUpUrl}';
  document.getElementById('3ds-form').submit();
</script>

Step 3 — Validate Challenge Result

When the bank finishes the challenge, you will receive a result identifier (from the iframe integration). Use it to validate and complete the payment:

POST /v2/payment-orders/:id/payer-authentication/validate

Possible outcomes:

COMPLETED — Payment successful ✓
FAILED — Declined

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

Manage Customers

Track customer information and history

Getting Started

Essentials

Features

Guides

API Reference

OpenAPI Reference

Link Product API

Accept Card Payments

Create a Card Payment

Complete Request Example

Successful Response

What Happens During Payment

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)

Step 1 — Collect Device Data (Invisible Iframe)

Step 2 — Check Enrollment

Step 3 — Validate Challenge Result

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

Manage Customers

Getting Started

Essentials

Features

Guides

API Reference

OpenAPI Reference

Link Product API

​Accept Card Payments

​Create a Card Payment

​Complete Request Example

​Successful Response

​What Happens During Payment

​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)

​Step 1 — Collect Device Data (Invisible Iframe)

​Step 2 — Check Enrollment

​Step 3 — Validate Challenge Result

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

Manage Customers

Accept Card Payments

Create a Card Payment

Complete Request Example

Successful Response

What Happens During Payment

Required Fields

Payment Information

Customer Information

Card Details

Billing Address (Required)

Save Cards for Future Use

Charge a Saved Card

Handle Authentication (3D Secure)

Step 1 — Collect Device Data (Invisible Iframe)

Step 2 — Check Enrollment

Step 3 — Validate Challenge Result

Improve Approval Rates

Include Device Information

Best Practices

Error Handling

Testing

Next Steps