Customers API

Overview

The Customers API enables you to create and manage customer profiles with saved payment methods. Store credit cards securely, charge repeat customers easily, and manage customer data efficiently.

What are Customers?

Customers are objects that represent your buyers and contain:

• Customer information - Email, name, description
• Saved cards - Securely stored payment methods
• Default card - Primary payment method for charges
• Metadata - Custom data for your records
• Charge history - Track payments per customer

Key Features

Secure Card Storage

• PCI-compliant - Cards stored securely by Omise
• Multiple cards - Save multiple payment methods per customer
• Default card - Set primary payment method
• No sensitive data - Only card tokens stored, not raw card numbers

Easy Repeat Payments

• One-click charging - Charge customer without new tokenization
• Subscriptions - Perfect for recurring billing
• Saved payment methods - Customers don't re-enter card details
• Customer profiles - Track payment history per customer

Flexible Management

• Update customer info - Change email, description, metadata
• Manage cards - Add, update, delete payment methods
• Set default card - Choose which card to charge
• List all customers - Paginate through customer database

How Customers Work

Standard Flow

┌─────────┐         ┌─────────┐         ┌─────────┐
│ Client  │         │ Your    │         │ Omise   │
│ Browser │         │ Server  │         │ API     │
└────┬────┘         └────┬────┘         └────┬────┘
     │                   │                   │
     │ 1. Enter card     │                   │
     ├──────────────────>│                   │
     │                   │                   │
     │ 2. Create token   │                   │
     │   (Omise.js)      │                   │
     ├──────────────────────────────────────>│
     │                   │                   │
     │ 3. Return token   │                   │
     │<──────────────────────────────────────┤
     │                   │                   │
     │ 4. Send token     │                   │
     ├──────────────────>│                   │
     │                   │                   │
     │                   │ 5. Create customer│
     │                   │   (with token)    │
     │                   ├──────────────────>│
     │                   │                   │
     │                   │ 6. Return customer│
     │                   │   (card saved)    │
     │                   │<──────────────────┤
     │                   │                   │
     │ 7. Future charges │                   │
     │   (no new token)  │                   │
     │                   ├──────────────────>│
     │                   │                   │

Implementation Steps

1. First time: Tokenize card → Create customer with token
2. Card saved: Customer profile created with card attached
3. Future payments: Charge customer ID directly (no new token needed)

API Endpoints

Method	Endpoint	Description
POST	/customers	Create a new customer
GET	/customers/:id	Retrieve customer details
PATCH	/customers/:id	Update customer information
DELETE	/customers/:id	Delete a customer
GET	/customers	List all customers
POST	/customers/:id/cards	Add card to customer
GET	/customers/:id/cards/:card_id	Retrieve card details
PATCH	/customers/:id/cards/:card_id	Update card information
DELETE	/customers/:id/cards/:card_id	Delete card from customer

Quick Start

Create Customer with Card

// Client-side: Tokenize card
Omise.setPublicKey('pkey_test_YOUR_PUBLIC_KEY');
Omise.createToken('card', cardData, async (status, response) => {
  if (status === 200) {
    // Server-side: Create customer
    const customer = await omise.customers.create({
      email: 'john@example.com',
      description: 'John Doe',
      card: response.id  // Token from Omise.js
    });

    console.log('Customer created:', customer.id);
    console.log('Card saved:', customer.default_card);
  }
});

Charge Existing Customer

// No token needed - charge customer directly
const charge = await omise.charges.create({
  customer: 'cust_test_5xuy4w91xqz7d1w9u0t',
  amount: 100000,
  currency: 'thb',
  description: 'Order #5678'
});

console.log('Charged customer:', charge.customer);
console.log('Status:', charge.status);

Add Additional Card

// Tokenize new card
Omise.createToken('card', newCardData, async (status, response) => {
  if (status === 200) {
    // Add card to existing customer
    const card = await omise.customers.update('cust_test_5xuy4w91xqz7d1w9u0t', {
      card: response.id
    });

    console.log('Card added:', card.id);
  }
});

Common Use Cases

Subscription Billing

Create customer once, charge monthly automatically:

// One-time setup
const customer = await omise.customers.create({
  email: 'subscriber@example.com',
  card: tokenId
});

// Monthly billing (automated)
setInterval(async () => {
  await omise.charges.create({
    customer: customer.id,
    amount: 99900,  // $9.99/month
    currency: 'usd',
    description: 'Monthly subscription'
  });
}, 30 * 24 * 60 * 60 * 1000);  // 30 days

Save Card for Later

Customer saves card, decides to purchase later:

// Checkout: Save card
const customer = await omise.customers.create({
  email: 'shopper@example.com',
  card: tokenId,
  metadata: { loyalty_id: '12345' }
});

// Later: Quick checkout
const charge = await omise.charges.create({
  customer: customer.id,
  amount: 250000,
  currency: 'thb'
});

Multiple Payment Methods

Customer manages multiple cards:

// Add multiple cards
await omise.customers.update(customerId, { card: token1 });
await omise.customers.update(customerId, { card: token2 });

// List customer's cards
const customer = await omise.customers.retrieve(customerId);
console.log('Cards:', customer.cards.data);

// Charge specific card
await omise.charges.create({
  customer: customerId,
  card: customer.cards.data[1].id,  // Second card
  amount: 100000
});

Customer Lifecycle

States

State	Description	Can Charge?
Active	Customer with valid cards	✅ Yes
No Cards	Customer without payment methods	❌ No
Deleted	Customer deleted	❌ No

Card Management

• Add card: Create token → Update customer with token
• Set default: Update customer with default_card parameter
• Remove card: Delete card from customer
• Update card: Update expiration date, name, etc.

Security Best Practices

✅ Do This

• Use tokens to add cards (never send raw card data)
• Store customer IDs in your database
• Verify customer ownership before allowing charges
• Use metadata for your internal tracking
• Implement authentication to protect customer data
• Handle card errors gracefully (expired, declined)
• Delete old customers when no longer needed

❌ Don't Do This

• Don't send card numbers to your server
• Don't expose customer IDs publicly
• Don't skip authorization (verify user owns customer)
• Don't store sensitive data in metadata
• Don't charge without permission (PCI requirement)
• Don't keep inactive customers indefinitely

Data Privacy

GDPR Compliance

• Delete customers when requested
• Export customer data on request
• Use minimal metadata (only what's necessary)
• Secure customer IDs (don't expose in URLs)

PCI Compliance

• Never store raw card numbers
• Use tokens for all card operations
• Limit access to customer data
• Audit customer data access

Testing

Test Customers

Create test customers with test tokens:

// Test mode customer
const customer = await omise.customers.create({
  email: 'test@example.com',
  card: 'tokn_test_no1t4tnemucod0e51mo'
});

// Customer ID starts with cust_test_
console.log(customer.id);  // cust_test_...

Test Cards

Use test card numbers:

• 4242424242424242 - Visa (successful)
• 4000000000000002 - Visa (declined)
• 5555555555554444 - Mastercard (successful)

Error Handling

Common customer errors:

Error Code	Description	Solution
used_token	Token already used	Create new token
invalid_card	Card is invalid	Validate card details
customer_not_found	Customer ID doesn't exist	Verify customer ID
card_not_found	Card doesn't belong to customer	Check card ID

API Reference

• Create Customer - POST /customers
• Retrieve Customer - GET /customers/:id
• Update Customer - PATCH /customers/:id
• Delete Customer - DELETE /customers/:id
• List Customers - GET /customers

Related Resources

• Create Charge
• Create Token
• Cards API
• Omise.js Guide

Integration Guides

• Subscription Billing
• Saved Payment Methods
• Customer Management

---

Need help? Check our Customer Management Guide or contact support@omise.co