Complete API Specification

Table of Contents

• Infrastructure
• v1 (Standard) API Endpoints
• v2 (Premium) API Endpoints
• Admin API Endpoints
• Authentication
• Error Codes

Infrastructure Endpoints

GET /ping

Purpose: Health check for load balancers and monitoring

Authentication: None required

Response: "Hello World!"

v1 Standard API Endpoints

GET /orders/programs

Summary: Get available card programs for a country

Query Parameters:

Success Response (200 OK):

[
  {
    "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",
    "programId": "PAY01PP0004"
  }
]

POST /orders/validate-address

Summary: Validate a recipient address before order creation

Request Body:

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

Success Response (200 OK):

{
  "isValid": true,
  "standardized": {
    "address1": "1600 Pennsylvania Ave NW",
    "city": "Washington",
    "state": "DC",
    "zipCode": "20500",
    "country": "USA"
  }
}

Error Response (400 Bad Request):

{
  "isValid": false,
  "errors": [
    "Invalid postal code",
    "City not found in state"
  ]
}

POST /orders/create

Summary: Create a new card order

Request Body Schema:

{
  // Required: Card amount and currency
  amount: {
    amount: number;        // Amount in USD (min: 5, max: 1000)
    currencyCode: string;  // Must be "USD"
  };

  // Required: Card program ID (from /orders/programs)
  programId: string;  // e.g., "silver-regional-na"

  // Required: Recipient information
  recipient: {
    participantId: string;   // Unique identifier (1-20 chars)
    firstName: string;       // 1-50 chars
    lastName: string;        // 1-50 chars
    address1: string;        // 1-50 chars
    address2?: string;       // Optional, 1-50 chars
    city: string;           // 1-35 chars
    state: string;          // 1-50 chars
    postalCode: string;     // 1-20 chars
    countryCode: string;    // ISO 3166-1 alpha-3 (3 chars)
    emailAddress: string;   // Valid email, max 80 chars
    mobilePhone: string;    // Valid phone number
    language: string;       // IETF language tag (default: "en-US")
  };

  // Required: Blockchain transaction receipt
  receipt: {
    deposit: {
      chainId?: number;       // Blockchain network ID
      tokenName: string;      // e.g., "USDC"
      tokenAmount: number;    // Token amount
      txHash: string;         // Transaction hash
      buyerAddress: string;   // Wallet address
      signature?: string;     // Transaction signature
      blockHash?: string;     // Block hash
      userEmail?: string;     // User email (optional)
      paymentId?: string;     // Payment provider ID (optional)
    };
  };
}

Example Request:

{
  "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"
    }
  }
}

Success Response (201 Created):

{
  "id": "uuid-v4-here",
  "orderId": "804cfd34-a685-4baa-8861-15d79e2fe7e5",
  "programId": "silver-regional-na",
  "amount": {
    "amount": 100,
    "currencyCode": "USD"
  },
  "recipient": {
    "firstName": "John",
    "lastName": "Doe",
    "emailAddress": "john.doe@example.com",
    ...
  },
  "status": "PENDING",
  "cardName": "Zebec Virtual Card",
  "signature": "https://etherscan.io/tx/0xabc123...",
  "chainId": 1,
  "chainName": "Ethereum",
  "createdAt": "2026-01-06T10:00:00Z",
  "updatedAt": "2026-01-06T10:00:00Z"
}

GET /orders/lookup

Summary: Lookup orders by email, order ID, or transaction hash

Query Parameters (provide exactly one):

Examples:

GET /orders/lookup?email=john.doe@example.com
GET /orders/lookup?orderId=804cfd34-a685-4baa-8861-15d79e2fe7e5
GET /orders/lookup?txHash=0xabc123...

v2 Premium API Endpoints

GET /v2/cards/{orderId}

Summary: Get complete card details including balance

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

Path Parameters:

Example Response:

{
  "orderId": "804cfd34-a685-4baa-8861-15d79e2fe7e5",
  "cardNumber": "**** **** **** 1234",
  "expiryDate": "12/26",
  "status": "ACTIVE",
  "balance": {
    "available": 95.50,
    "pending": 0,
    "currency": "USD"
  },
  "cardholder": {
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "createdAt": "2026-01-01T00:00:00Z"
}

GET /v2/cards/{orderId}/balance

Summary: Get current card balance

Requires Feature: balanceAccess

POST /v2/cards/{orderId}/transactions

Summary: Get paginated transaction history

Requires Feature: transactionAccess

Query Parameters:

GET /v2/cards

Summary: List all cards for this client

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

Query Parameters: Same as transactions endpoint (page, limit)

Admin API Endpoints

POST /admin/client

Summary: Create a new API client with credentials

GET /admin/clients

Summary: List all API clients

PUT /admin/client/{client_id}

Summary: Update an existing client

PUT /admin/client/{client_id}/rotate

Summary: Rotate API keys for a client

Authentication

See the Authentication section in the Integration Guide for complete details on HMAC-SHA256 signature generation.

Common Error Codes

Next Steps

• Review recipient field requirements
• Check supported countries and regions
• Test in sandbox environment
• Use HMAC generator for debugging