​
Overview

This guide walks through the complete lifecycle of purchasing discounted gift cards via the CardCash API, from authentication through accessing card credentials.

​
Flow Diagram

​
Step-by-Step

​
1. Authenticate

// Create session
const session = await fetch(`${BASE_URL}/session`, {
  method: 'POST',
  headers: { 'x-cc-app': APP_ID, 'Content-Type': 'application/json' }
});
let token = session.data.access_token;

// Login customer
const login = await fetch(`${BASE_URL}/customers/login`, {
  method: 'POST',
  headers: {
    'x-cc-app': APP_ID,
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ customer: { email, password } })
});
// Always capture refreshed token
token = login.headers['authorization'] || token;

​
2. Find Cards to Buy

// Get merchants with their discount rates
const merchants = await api.get('/merchants/buy/bulk');

// Pick a merchant and view their inventory
const inventory = await api.get(`/merchants/${merchantId}/inventory/bulk`);

​
3. Purchase Cards

Use condensed checkout to select and purchase cards in a single call: 
const order = await api.post('/orders?checkout=condensed', {
  cards: [
    { merchantId: 123, faceValue: 50, percentOff: 8.5, type: 'ecode', quantity: 4 }
  ],
  payment: {
    method: 'ACH',
    details: { id: 789 }  // saved payment method ID
  },
  shippingDetails: {
    firstname: 'John', lastname: 'Doe',
    street: '123 Main St', city: 'New York', state: 'NY', postcode: '10001'
  },
  billingDetails: {
    firstname: 'John', lastname: 'Doe',
    street: '123 Main St', city: 'New York', state: 'NY', postcode: '10001'
  }
});

const orderId = order.data.buyOrder.orderId;
If some cards are unavailable, the entire order fails with an error message. Check inventory freshness and retry with available cards.

​
4. Wait for Fulfillment

E-code cards are typically fulfilled within minutes. Physical cards may take longer. 
// Poll for order status
const status = await api.get(`/orders/status/${orderId}`);
if (status.data.order.statusText === 'Digitally Delivered') {
  // Cards are ready in wallet
}

​
5. Access Card Credentials

// List wallet cards
const wallet = await api.get('/wallets');

// Get card number and PIN for each card
for (const card of wallet.data.cards) {
  const secureData = await api.get(`/wallets/${card.id}/secure-data`);
  console.log(`${card.merchant.name}: ${secureData.data.number} / PIN: ${secureData.data.pin}`);
}
Cards purchased within the last 24 hours are always accessible without verification.

​
Best Practices

​
Token Management

The API refreshes your token when it’s near expiration. Check every response for an updated token: 
api.interceptors.response.use(response => {
  const newToken = response.headers['authorization'];
  if (newToken) {
    // Token was refreshed — store the new one
    api.defaults.headers['Authorization'] = `Bearer ${newToken}`;
  }
  return response;
});
Most responses won’t include a new token — only those where the server detects your token is within ~5 minutes of expiry. But you should always check.

​
Handling Inventory Availability

Inventory is live and competitive. Between viewing inventory and placing an order, cards may be purchased by others. Refresh inventory close to when you intend to purchase, and if the order fails with “Not all requested cards were added to the cart”, re-check inventory and retry.

​
Retrieve Cards Promptly

Card secure data (number, PIN, barcode) is accessible for 24 hours after purchase. Build your integration to retrieve card data as soon as the order is fulfilled. A small number of new cards may be delivered as redemption URLs instead of a traditional card number and PIN. Contact your account manager for details on which merchants use this format.

​
Accessing Cards by Order

To retrieve card data for a specific order:
  1. Use GET /v3/orders/:uuid to get the order details — each card has an id field
  2. Use GET /v3/wallets/:cardId/secure-data to get the number and PIN for each card
// Get order details
const order = await api.get(`/orders/${orderUUID}`);

// Get secure data for each card in the order
for (const card of order.data.buyOrder.cards) {
  const secureData = await api.get(`/wallets/${card.id}/secure-data`);
  console.log(`${card.merchantName}: ${secureData.data.number} / PIN: ${secureData.data.pin}`);
}
Alternatively, use GET /v3/wallets and filter by order ID client-side: 
const wallet = await api.get('/wallets');
const orderCards = wallet.data.cards.filter(card => card.order.id === targetOrderUUID);