Skip to main content

​
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

Contact Information

Full name, email, and phone number

External Reference

Your own customer reference ID

Notification Preferences

Email and SMS notification settings

Payment Methods

Saved cards for future purchases

​
Customer Identification

Use the externalId field to link Cheqpay customers with your system: 
{
  "customer": {
    "externalId": "user_12345",
    "firstName": "María",
    "lastName": "González",
    "email": "[email protected]",
    "phoneNumber": "+521555123456"
  }
}

​
How It Works

1

First Payment

When you process the first payment, a customer record is created in Cheqpay.
2

Subsequent Payments

On future payments with the same externalId, we retrieve and update the existing customer.
3

No Duplicates

The same externalId ensures no duplicate customer records are created.
You can safely include customer data with every payment request. Cheqpay handles deduplication automatically.

​
Notification Preferences

Control how your customers receive payment confirmations: 
{
  "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
Disable notifications if you prefer to send them from your own system.

​
Retrieve Customer Information

Access customer details, payment history, and saved payment methods: 
GET /customers/:id
Authorization: Bearer YOUR_API_KEY
The response includes everything you need to provide a personalized experience for returning customers: 
{
  "id": "cus_xyz789",
  "externalId": "user_12345",
  "firstName": "María",
  "lastName": "González",
  "email": "[email protected]",
  "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

FieldTypeRequiredDescription
idstringConditionalRequired when referencing an existing customer
externalIdstringNoYour unique customer identifier
firstNamestringConditionalRequired when creating a new customer (if id not provided)
lastNamestringNoCustomer’s last name
emailstringConditionalRequired when creating a new customer (if id not provided)
phoneNumberstringNoPhone number with country code
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

​
Best Practices

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.
Use the same customer information across all payments. Consistency helps with fraud prevention and approval rates.
Honor customer notification preferences. Some customers prefer not to receive emails or SMS notifications.
If a customer updates their email or phone number in your system, include the updated information in the next payment request.

​
Next Steps

Save Payment Methods

Learn how to store cards for returning customers

View Payment Orders

Track customer payment history and orders