API Documentation — CardPing.io

REST API · JSON · v1

Introduction

The CardPing API is a RESTful JSON API for pinging gift card balances, detecting fraud, and managing white-label portals. All requests go to:

Base URL

https://api.cardping.io/v1

// All responses: Content-Type: application/json
// All requests need: X-API-Key header

Authentication

Pass your API key in the X-API-Key request header. Keys are scoped to your account and rotatable any time from the dashboard.

Header

X-API-Key: cp_live_sk_your_key_here

// Sandbox testing:
X-API-Key: cp_test_sk_your_test_key

Ping a Card Balance

POST/cards/ping

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

Request Parameters

Parameter	Type	Required	Description
card_number	string	required	The full gift card number
pin	string	optional	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

ping.js

import { CardPing } from '@cardping/sdk';
const client = new CardPing({ apiKey: process.env.CARDPING_KEY });

const result = await client.ping({
  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

200 OK

{
  "id":           "ping_9f4a3b2c",
  "status":        "active",
  "balance":       47.50,
  "currency":      "USD",
  "expiry":        "2027-03",
  "fraud_score":   0.02,
  "fraud_signals": [],
  "ai_verified":   true,
  "network":       "visa_gift",
  "latency_ms":    68
}

Error Handling

All errors return a consistent JSON envelope with a code and message.

Code	HTTP	Description
auth_invalid	401	API key missing or invalid
quota_exceeded	429	Monthly ping quota reached
card_invalid	422	Card number 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 fraud alerts and check events. Configure webhooks from the dashboard or via the Webhooks API.

webhook_handler.js

const event = client.webhooks.verify(
  req.rawBody,
  req.headers['cp-signature'],
  process.env.CARDPING_WEBHOOK_SECRET
);

switch(event.type) {
  case 'fraud.high_risk':
    await blockCard(event.data.card_id); break;
  case 'ping.completed':
    await saveResult(event.data); break;
}