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

# Customers

> Manage your customers effortlessly with Cheqpay

## How Customers Work

Manage your customers effortlessly with Cheqpay. Store customer information, track payment history, and provide a better payment experience for returning customers.

Customers are automatically created when you process a payment. You don't need to create them separately - just include customer information in your payment request.

### What You Can Store

<CardGroup cols={2}>
  <Card title="Contact Information" icon="address-card">
    Full name, email, and phone number
  </Card>

  <Card title="External Reference" icon="link">
    Your own customer reference ID
  </Card>

  <Card title="Notification Preferences" icon="bell">
    Email and SMS notification settings
  </Card>

  <Card title="Payment Methods" icon="credit-card">
    Saved cards for future purchases
  </Card>
</CardGroup>

## Customer Identification

Use the `externalId` field to link Cheqpay customers with your system:

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

### How It Works

<Steps>
  <Step title="First Payment">
    When you process the first payment, a customer record is created in Cheqpay.
  </Step>

  <Step title="Subsequent Payments">
    On future payments with the same `externalId`, we retrieve and update the existing customer.
  </Step>

  <Step title="No Duplicates">
    The same `externalId` ensures no duplicate customer records are created.
  </Step>
</Steps>

<Tip>
  You can safely include customer data with every payment request. Cheqpay handles deduplication automatically.
</Tip>

## Notification Preferences

Control how your customers receive payment confirmations:

```json theme={null}
{
  "notificationOptions": {
    "notifyEmail": true,
    "notifyPhone": false
  }
}
```

### Available Notifications

* **Payment confirmations** - Successful payment receipts
* **Receipt emails** - Detailed transaction receipts
* **Refund notifications** - Refund confirmation emails
* **SPEI transfer instructions** - CLABE and payment details
* **PAYCASH references** - Cash payment reference and status updates
* **CIE Cash Net instructions** - Reference, convenio, CLABE, and status updates

<Note>
  Disable notifications if you prefer to send them from your own system.
</Note>

## Retrieve Customer Information

Access customer details, payment history, and saved payment methods:

```http theme={null}
GET /customers/:id
x-api-key: YOUR_API_KEY
x-merchant-id: YOUR_MERCHANT_ID
```

The response includes everything you need to provide a personalized experience for returning customers:

```json theme={null}
{
  "id": "cus_xyz789",
  "externalId": "user_12345",
  "firstName": "María",
  "lastName": "González",
  "email": "maria@example.com",
  "phoneNumber": "+521555123456",
  "paymentMethods": [
    {
      "id": "pm_abc123",
      "type": "card",
      "card": {
        "brand": "visa",
        "last4": "1111",
        "expiryMonth": "12",
        "expiryYear": "2025"
      }
    }
  ],
  "createdAt": "2025-10-30T10:00:00.000Z"
}
```

## Customer Fields Reference

| Field         | Type   | Required    | Description                                                  |
| ------------- | ------ | ----------- | ------------------------------------------------------------ |
| `id`          | string | Conditional | Required when referencing an existing customer               |
| `externalId`  | string | No          | Your unique customer identifier                              |
| `firstName`   | string | Conditional | Required when creating a new customer (if `id` not provided) |
| `lastName`    | string | No          | Customer's last name                                         |
| `email`       | string | Conditional | Required when creating a new customer (if `id` not provided) |
| `phoneNumber` | string | No          | Phone number with country code                               |

<Note>
  **Conditional Requirements:**

  * When **referencing an existing customer**: Only `customer.id` is required
  * When **creating a new customer**: Both `customer.firstName` and `customer.email` are required (no `id` needed)
  * The `lastName` and `phoneNumber` fields are always optional
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Always Use External IDs" icon="hashtag">
    Link customers to your system by always including your internal customer ID as the `externalId`. This makes it easy to match Cheqpay customers with your database.
  </Accordion>

  <Accordion title="Keep Data Consistent" icon="equals">
    Use the same customer information across all payments. Consistency helps with fraud prevention and approval rates.
  </Accordion>

  <Accordion title="Respect Privacy Preferences" icon="shield-check">
    Honor customer notification preferences. Some customers prefer not to receive emails or SMS notifications.
  </Accordion>

  <Accordion title="Update Information" icon="pen">
    If a customer updates their email or phone number in your system, include the updated information in the next payment request.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Save Payment Methods" icon="credit-card" href="/features/payment-methods">
    Learn how to store cards for returning customers
  </Card>

  <Card title="View Payment Orders" icon="file-invoice" href="/features/payment-orders">
    Track customer payment history and orders
  </Card>
</CardGroup>