> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cheqpay.mx/llms.txt
> Use this file to discover all available pages before exploring further.

# Card Payments

> Accept credit and debit card payments with a simple API

## 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.

<Warning>
  **PCI Compliance Required**

  If 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](mailto:support@cheqpay.mx) to learn about hosted payment options.
</Warning>

## Create a Card Payment

```http theme={null}
POST /checkout/pay
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_MERCHANT_ID
Content-Type: application/json
```

### Complete Request Example

```json theme={null}
{
  "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

```json theme={null}
{
  "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

<Steps>
  <Step title="Customer Created or Updated">
    Cheqpay creates a new customer record or updates an existing one based on the `externalId`.
  </Step>

  <Step title="Card Tokenized">
    The card is securely tokenized. Sensitive data never touches your servers.
  </Step>

  <Step title="Authorization">
    The payment is authorized by the card network (Visa, Mastercard, Amex).
  </Step>

  <Step title="Funds Captured">
    Funds are captured immediately upon successful authorization.
  </Step>

  <Step title="Status Updated">
    Payment status updates to `COMPLETED` and you can fulfill the order.
  </Step>

  <Step title="Customer Notified">
    Customer receives a confirmation email (if notifications are enabled).
  </Step>
</Steps>

<Tip>
  The entire process typically takes 2-5 seconds for successful payments.
</Tip>

## 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.

<Note>
  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.
</Note>

## 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:

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

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

## Save Cards for Future Use

Enable one-click checkout by saving the card:

```json theme={null}
{
  "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:

```json theme={null}
{
  "paymentMethod": {
    "id": "pm_abc123",
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "1111"
    }
  }
}
```

<Card title="Learn More About Saved Cards" icon="floppy-disk" href="/features/payment-methods">
  View complete payment methods documentation
</Card>

## Charge a Saved Card

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

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

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

## Handle Authentication (3D Secure)

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

```json theme={null}
{
  "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.

<Card title="Complete 3D Secure Guide" icon="shield" href="/features/3d-secure">
  Learn how to implement 3D Secure authentication
</Card>

## Improve Approval Rates

### Include Device Information

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

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

### Best Practices

<AccordionGroup>
  <Accordion title="Include Billing Address" icon="map-location">
    Billing address verification helps prevent fraud and improves approval rates by 3-5%.
  </Accordion>

  <Accordion title="Send Device Data" icon="mobile">
    Device information enables better fraud detection and smoother 3D Secure flows.
  </Accordion>

  <Accordion title="Use Consistent Customer Data" icon="user-check">
    Keep customer information consistent across payments for better approval rates.
  </Accordion>

  <Accordion title="Save Payment Methods" icon="floppy-disk">
    Returning customers with saved cards have higher approval rates.
  </Accordion>
</AccordionGroup>

## Error Handling

Handle declined payments gracefully:

```json theme={null}
{
  "error": {
    "code": "DECLINED",
    "message": "Payment declined by issuing bank",
    "declineReason": "insufficient_funds"
  }
}
```

<Card title="Error Handling Guide" icon="triangle-exclamation" href="/guides/error-handling">
  Learn how to handle errors and declined payments
</Card>

## Testing

Use these test cards in sandbox:

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

<Card title="Complete Testing Guide" icon="flask" href="/guides/testing">
  View all test scenarios and cards
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Handle 3D Secure" icon="shield" href="/features/3d-secure">
    Implement card authentication
  </Card>

  <Card title="Save Payment Methods" icon="floppy-disk" href="/features/payment-methods">
    Store cards for returning customers
  </Card>

  <Card title="Process Refunds" icon="rotate-left" href="/features/refunds">
    Issue full or partial refunds
  </Card>

  <Card title="Set Up Webhooks" icon="webhook" href="/features/webhooks">
    Get real-time payment notifications
  </Card>
</CardGroup>