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

# Quickstart

> Process your first payment in less than 5 minutes

## Your First Payment

Get started with Cheqpay by processing your first test payment. This guide will walk you through a simple card payment.

<Warning>
  **PCI Compliance Requirement**

  This quickstart demonstrates direct API integration where you handle raw card data. If you choose this approach for production, your business must be PCI DSS compliant.

  **Not PCI compliant?** Contact [support@cheqpay.mx](mailto:support@cheqpay.mx) to learn about our hosted payment page and JavaScript SDK options that eliminate PCI compliance requirements for your business.
</Warning>

<Steps>
  <Step title="Get Your API Key">
    Sign up for a Cheqpay account and copy your sandbox API key from the dashboard.

    ```bash theme={null}
    export CHEQPAY_API_KEY="your_sandbox_api_key"
    ```
  </Step>

  <Step title="Make Your First API Call">
    Create a payment with a test card:

    ```bash theme={null}
    curl -X POST https://api.sandbox.cheqpay.mx/pos/v2/payment-orders \
      -H "x-api-key: YOUR_API_KEY" \
      -H "x-merchant-id: YOUR_MERCHANT_ID" \
      -H "Content-Type: application/json" \
      -d '{
        "externalId": "order-123",
        "customer": {
          "firstName": "María",
          "lastName": "González",
          "email": "maria@example.com",
          "phoneNumber": "+31431453454"
        },
        "amount": 10000,
        "currency": "MXN",
        "description": "Product purchase",
        "paymentMethod": {
          "type": "card",
          "options": {
            "card": {
              "number": "4000000000002503",
              "expiryMonth": "12",
              "expiryYear": "2025",
              "cvc": "123"
            }
          }
        }
      }'
    ```

    <Note>
      `x-merchant-id` is optional. Only `x-api-key` is required to authenticate.
    </Note>
  </Step>

  <Step title="Check the Response">
    You'll receive a successful response with the payment details:

    ```json theme={null}
    {
      "id": "291348e9-62f3-48dd-83c1-eef69d71c16a",
      "orderNumber": "C2510301",
      "externalMerchantReference": "ORDER-8-test",
      "amount": 100,
      "currency": "MXN",
      "status": "COMPLETED",
      "description": "Payment with existing customer and new card",
      "createdAt": "2025-10-30T23:02:16.715Z",
      "paymentMethod": {
        "type": "CARD",
        "id": "6b987cae-dd80-47d1-965a-776db006e2a9",
        "cardDetails": {
            "id": "29a2bd07-5dcd-4877-a9e2-4496d06bcfec",
            "bin": "411111",
            "last4": "1111",
            "brand": "VISA",
            "type": "DEBIT",
            "country": "POLAND",
            "issuerBank": "CONOTOXIA SP. Z O.O",
            "expiryMonth": "04",
            "expiryYear": "28"
        }
      },
      "customer": {
        "id": "0e045958-5dea-491e-8b3d-70663b1ee992",
        "firstName": "María",
        "lastName": "González",
        "email": "maria@example.com",
        "phoneNumber": "+31431453454"
      }
    }
    ```
  </Step>
</Steps>

That's it! You've processed your first payment with Cheqpay. 🎉

## Understanding the Request

Let's break down the key fields in the payment request:

### Required Fields

| Field           | Type    | Description                                                 |
| --------------- | ------- | ----------------------------------------------------------- |
| `externalId`    | string  | Your unique order ID (prevents duplicate charges)           |
| `amount`        | integer | Amount in the smallest currency unit (10000 = \$100.00 MXN) |
| `currency`      | string  | ISO currency code (MXN, USD)                                |
| `paymentMethod` | object  | Payment method details                                      |

### Customer Information

```json theme={null}
{
  "customer": {
    "firstName": "María",
    "lastName": "González",
    "email": "maria@example.com",
    "phoneNumber": "+521555123456"
  }
}
```

Customers are automatically created on first payment. Use the the id returned by the first payment to retrieve the existing customer and on subsequent payments.

### Card Details

```json theme={null}
{
  "paymentMethod": {
    "type": "card",
    "options": {
      "card": {
        "number": "4000000000002503",
        "expiryMonth": "12",
        "expiryYear": "2025",
        "cvc": "123"
      }
    }
  }
}
```

<Warning>
  Card data is automatically tokenized for security. Sensitive information never touches your servers.
</Warning>

## What Happens Next?

When you create a payment, Cheqpay:

1. **Creates or updates** the customer record
2. **Tokenizes** the card securely
3. **Authorizes** the payment with the card network
4. **Captures** the funds immediately
5. **Updates** the status to `COMPLETED`
6. **Sends** a confirmation to the customer (if enabled)

The entire process typically takes 2-5 seconds.

## Important Notes

<AccordionGroup>
  <Accordion title="Amounts in Cents" icon="coins">
    Always specify amounts in cents (minor units). For example:

    * 10000 = \$100.00 MXN
    * 150 = \$1.50 MXN
    * 999999 = \$9,999.99 MXN
  </Accordion>

  <Accordion title="External ID for Idempotency" icon="shield-check">
    The `externalId` prevents duplicate charges. If you send the same request twice:

    * Successful payment → Returns existing payment (no duplicate)
    * Failed payment → Creates new payment (allows retry)
  </Accordion>

  <Accordion title="Automatic Tokenization" icon="lock">
    Card numbers are instantly converted to secure tokens. You never need to handle raw card data on your servers.
  </Accordion>
</AccordionGroup>

## Next Steps

Now that you've processed your first payment, explore more features:

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

  <Card title="Handle 3D Secure" icon="shield" href="/features/3d-secure">
    Implement authentication challenges
  </Card>

  <Card title="Manage Customers" icon="users" href="/features/customers">
    Track customer information and history
  </Card>

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

<Card title="View Complete Testing Guide" icon="flask" href="/guides/testing">
  Learn about test cards, scenarios, and going live
</Card>