Zebec Card API Integration Guide

API Versions Overview

📦 Two API Products Available: The Zebec Partner Service offers two API product tiers - v1 (Standard) and v2 (Premium) - each with different capabilities and access levels.

v1 Standard API

Core card operations available to all partners:

✅ Create card orders
✅ Get card programs by country
✅ Validate recipient addresses
✅ Lookup orders by email, transaction hash, or order ID
✅ Basic order status tracking

Rate Limit: 100 requests/minute (default)

v2 Premium API

Enhanced features with granular access control:

✅ All v1 features included
💎 Real-time balance viewing (requires balanceAccess feature)
💎 Transaction history (requires transactionAccess feature)
💎 Card management operations (requires cardManagement feature)
💎 Advanced reporting (requires advancedReporting feature)
💎 List all client cards

Rate Limit: 500 requests/minute (default)

Security: Card numbers are masked - only last 4 digits returned

⚠️ Important: v2 endpoints require a v2 API key. Attempting to access v2 endpoints with a v1 key will result in a 403 Forbidden error with upgrade information.

Getting Started

You'll receive your API key and secret via email after successful partnership registration. Your API key will be assigned to either v1 or v2 product tier based on your agreement.

Authentication

All API requests must be signed using HMAC-SHA256 authentication.

Required Headers

Header	Description	Example
`x-api-key`	Your unique API key	`ak_1234567890abcdef`
`x-timestamp`	Current Unix timestamp (seconds)	`1704067200`
`x-nonce`	MANDATORY - Unique request identifier	`550e8400-e29b-41d4-a716-446655440000`
`x-signature`	HMAC-SHA256 signature	`a1b2c3d4...`

Signature Generation

Create the signature by following these steps:

Create string to sign: {METHOD}{PATH}{TIMESTAMP}{API_KEY}{BODY}
Generate HMAC-SHA256 using your secret key
Use the hex digest as the signature

📝 Note: The nonce is NOT included in signature calculation (reserved for future replay protection).

Example Signature Generation (JavaScript)

const crypto = require('crypto');

function createHmacSignature(method, path, apiKey, secretKey, body = '') {
  const timestamp = Math.floor(Date.now() / 1000); // Unix timestamp in seconds
  const stringToSign = [
    method.toUpperCase(),
    path,
    timestamp,
    apiKey,
    body ? JSON.stringify(body) : '',
  ].join('');

  const signature = crypto
    .createHmac('sha256', secretKey)
    .update(stringToSign)
    .digest('hex');

  return {
    'x-api-key': apiKey,
    'x-signature': signature,
    'x-timestamp': timestamp.toString(),
    'x-nonce': crypto.randomUUID(),
    'Content-Type': 'application/json'
  };
}

Testing Your Integration

`GET /ping` - Infrastructure Health Check

For load balancers and basic service monitoring. No authentication required.

GET /ping HTTP/1.1
Host: api.zebec.io

Response: "Hello World!"

v1 API Endpoints

1. Get Available Card Programs

GET /orders/programs?country={countryCode}

Query Parameters:

country (required): ISO 3166-1 alpha-3 country code (e.g., "USA", "GBR", "CAN")

Example Response:

[
  {
    "id": "silver-regional-na",
    "type": "REGIONAL",
    "name": "Silver Card - Regional",
    "description": "Regional card for North America",
    "isRegional": true,
    "isInternational": false,
    "availableCurrencies": ["USD", "CAD"],
    "region": "NA",
    "country": "USA"
  }
]

2. Validate Recipient Address

POST /orders/validate-address

Request Body:

{
  "address1": "1600 Pennsylvania Avenue NW",
  "city": "Washington",
  "state": "DC",
  "postalCode": "20500",
  "countryCode": "USA"
}

3. Create Card Order

POST /orders/create

Request Body:

{
  "amount": {
    "amount": 100,
    "currencyCode": "USD"
  },
  "programId": "silver-regional-na",
  "recipient": {
    "participantId": "USER123",
    "firstName": "John",
    "lastName": "Doe",
    "address1": "123 Main St",
    "address2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105",
    "countryCode": "USA",
    "emailAddress": "john.doe@example.com",
    "mobilePhone": "4155551234",
    "language": "en-US"
  },
  "receipt": {
    "deposit": {
      "tokenName": "USDC",
      "tokenAmount": 100000000,
      "txHash": "0xabc123...",
      "buyerAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
    }
  }
}

4. Lookup Orders

GET /orders/lookup?email={email}
GET /orders/lookup?orderId={orderId}
GET /orders/lookup?txHash={txHash}

Provide exactly one query parameter.

v2 Premium API Endpoints

🔒 Authentication: All v2 endpoints require a v2 API key and appropriate feature flags.

1. Get Card Details with Balance

GET /v2/cards/{orderId}

Returns: Complete card information including current balance

Security: Card number is masked - only last 4 digits shown

2. Get Card Balance

GET /v2/cards/{orderId}/balance

Requires: balanceAccess feature flag