API Documentation — MyCardLiaison

API v3.0 · REST · JSON

Introduction

The MyCardLiaison API is a RESTful JSON API for checking gift card balances, detecting fraud, and managing white-label portals. All requests are made over HTTPS to https://api.mycardliaison.com/v3.

Base URL

https://api.mycardliaison.com/v3

// All responses are JSON with Content-Type: application/json
// All requests must include the X-API-Key header

Authentication

Authenticate by passing your API key in the X-API-Key request header. Keys are scoped to your account and can be rotated from the dashboard at any time.

Authentication header

X-API-Key: mcl_live_sk_your_key_here

// For sandbox (testing), use your test key:
X-API-Key: mcl_test_sk_your_test_key

Check Card Balance

POST/cards/check

Check the live balance, status, and fraud score of a single gift card. This is the core endpoint for most integrations.

Request Parameters

Parameter	Type	Required	Description
card_number	string	required	The full gift card number
pin	string	optional	Card PIN (required for some networks)
network	string	required	Network ID from GET /networks
currency	string	optional	ISO 4217 code. Defaults to USD
idempotency_key	string	optional	Unique key for safe retries

Code Examples

balance_check.js

import { CardLiaison } from '@mycardliaison/sdk';
const client = new CardLiaison({ apiKey: process.env.MCL_API_KEY });

const result = await client.cards.check({
  cardNumber: '6006-4913-0000-0011',
  pin: '1234',
  network: 'visa_gift'
});

console.log(result.balance);    // 47.50
console.log(result.status);     // "active"
console.log(result.fraudScore); // 0.02

Response Schema

200 OK

{
  "id":           "chk_9f4a3b2c1d",
  "status":        "active",          // active | inactive | expired | invalid
  "balance":       47.50,
  "currency":      "USD",
  "expiry":        "2027-03",
  "network":       "visa_gift",
  "fraud_score":   0.02,             // 0.00 (clean) → 1.00 (high risk)
  "ai_verified":   true,
  "checked_at":    "2026-03-26T10:22:01Z",
  "latency_ms":    71
}

Error Handling

All errors return a consistent JSON body with a machine-readable code and a human-readable message.

Error response

{
  "error": {
    "code":    "card_invalid",
    "message": "The card number provided is not valid for this network.",
    "status":  422
  }
}

Code	HTTP	Description
auth_invalid	401	API key missing or invalid
quota_exceeded	429	Monthly check quota reached
card_invalid	422	Card number format invalid for network
network_unavailable	503	Card network temporarily unreachable
rate_limited	429	Too many requests — back off and retry

Webhooks

Register a HTTPS endpoint to receive real-time event notifications. Configure webhooks from your dashboard or via the Webhooks API.

Webhook verification

// Verify the signature on every incoming webhook
const event = client.webhooks.construct(
  request.rawBody,
  request.headers['mcl-signature'],
  process.env.MCL_WEBHOOK_SECRET
);

switch (event.type) {
  case 'fraud.detected':
    await flagCard(event.data.card_id); break;
  case 'check.completed':
    await saveResult(event.data); break;
}