Version: 2019-05-29 (Current)

Cards API

Overview

The Cards API allows you to manage credit and debit cards that are saved to customer profiles. Cards must be attached to a customer to be stored for future use.

Cards Are Customer Resources

Cards in the Omise API are always associated with customers. To manage cards, use the Customer Cards endpoints.

Available Endpoints

All card operations are under the Customers API:

List Cards - GET /customers/:id/cards
Retrieve Card - GET /customers/:id/cards/:card_id
Update Card - PATCH /customers/:id/cards/:card_id
Delete Card - DELETE /customers/:id/cards/:card_id

What You Can Do

Save Cards - Attach tokenized cards to customers
List Customer Cards - View all cards for a customer
Update Card Details - Modify card metadata (name, expiration, billing address)
Set Default Card - Choose which card to use for charges
Delete Cards - Remove cards from customer profiles
Manage Multiple Cards - Store multiple payment methods per customer

How Cards Work

1. Tokenize Card Data

First, create a token using your public key (client-side):

// Client-side with Omise.js
Omise.setPublicKey('pkey_test_...');
Omise.createToken('card', {
  name: 'JOHN DOE',
  number: '4242424242424242',
  expiration_month: 12,
  expiration_year: 2025,
  security_code: '123'
}, (status, response) => {
  if (status === 200) {
    // Send token to server
    sendTokenToServer(response.id);
  }
});

2. Attach Card to Customer

Then attach the token to a customer (server-side):

// Server-side
const customer = await omise.customers.update('cust_test_...', {
  card: 'tokn_test_...'
});

console.log('Card added:', customer.cards.data[0].id);

3. Use Saved Card

Charge the customer's default card:

const charge = await omise.charges.create({
  amount: 100000,
  currency: 'thb',
  customer: 'cust_test_...'
});

Or specify a specific card:

const charge = await omise.charges.create({
  amount: 100000,
  currency: 'thb',
  customer: 'cust_test_...',
  card: 'card_test_...'
});

Card Object Structure

{
  "object": "card",
  "id": "card_test_5xuy4w91xqz7d1w9u0t",
  "livemode": false,
  "location": "/customers/cust_test_.../cards/card_test_...",
  "country": "th",
  "city": "Bangkok",
  "postal_code": "10320",
  "financing": "",
  "bank": "Bank of Ayudhya",
  "brand": "Visa",
  "fingerprint": "XK2FJbz+kQFvd/kLLRm1BVXR1kbwJpQp+lkFZyqP0u8=",
  "last_digits": "4242",
  "name": "JOHN DOE",
  "expiration_month": 12,
  "expiration_year": 2025,
  "security_code_check": true,
  "created_at": "2025-02-07T00:00:00Z"
}

Security & PCI Compliance

✅ Secure Practices

Never send raw card data to your server
Always tokenize using Omise.js (public key)
Store only tokens or card IDs
Never log card numbers or CVV codes
Use HTTPS for all API requests
Validate on client before tokenization

Card Data Storage

When you save a card to a customer:

✅ Omise stores the encrypted card data
✅ You receive a card ID (card_test_...)
✅ You can view last 4 digits, brand, expiration
❌ You never receive the full card number
❌ CVV is never stored (always required for charges)

Use Cases

Subscriptions & Recurring Billing

Save customer cards for recurring charges:

// Save card
const customer = await omise.customers.create({
  email: 'subscriber@example.com',
  card: 'tokn_test_...'
});

// Charge monthly
async function chargeMonthly() {
  const charge = await omise.charges.create({
    amount: 99900, // $999 subscription
    currency: 'thb',
    customer: customer.id,
    description: 'Monthly subscription'
  });
}

One-Click Checkout

Allow customers to pay without re-entering card details:

// Customer selects saved card at checkout
const cards = await omise.customers.listCards('cust_test_...');

// Display cards to customer
cards.data.forEach(card => {
  console.log(`${card.brand} ending in ${card.last_digits}`);
});

// Charge selected card
const charge = await omise.charges.create({
  amount: 150000,
  currency: 'thb',
  customer: 'cust_test_...',
  card: selectedCardId
});

Update Expired Cards

Update card expiration dates:

const updatedCard = await omise.customers.updateCard(
  'cust_test_...',
  'card_test_...',
  {
    expiration_month: 12,
    expiration_year: 2026,
    name: 'JOHN DOE'
  }
);

Best Practices

✅ Do This

Tokenize client-side using Omise.js
Set default cards for easier charging
Update expiration dates proactively
Delete old cards to keep profiles clean
Verify cards with small authorization charges
Handle card updates gracefully in your UI

❌ Don't Do This

Never send raw card data to your server
Don't store CVV codes (illegal and unnecessary)
Don't charge deleted cards (check card exists first)
Don't ignore expiration dates (validate before charging)
Don't share cards between customers

Customers API - Manage customer profiles
Tokens API - Tokenize card data
Charges API - Create charges with saved cards
List Cards - View customer cards

Overview​

Available Endpoints​

What You Can Do​

How Cards Work​

1. Tokenize Card Data​

2. Attach Card to Customer​

3. Use Saved Card​

Card Object Structure​

Security & PCI Compliance​

✅ Secure Practices​

Card Data Storage​

Use Cases​

Subscriptions & Recurring Billing​

One-Click Checkout​

Update Expired Cards​

Best Practices​

✅ Do This​

❌ Don't Do This​

Related Resources​

See Also​