🤖 Ezzocard AI Agent API

Official documentation for automated virtual prepaid card purchases. This API is designed for AI agents, bots, orchestrators, workflow engines, and developers that need to create orders, monitor payment confirmation, retrieve delivered cards, and optionally register webhooks.

Base URL: https://ezzocard.finance
Format: JSON
Auth: None required
Rate Limit: 10 orders/min
Rate Limit: 60 checks/min

Quick Links

These public resources should all describe the same API.

OpenAPI JSON OpenAPI YAML AI Plugin Manifest AI Agent Landing Page
Important: This API is not limited to one agent framework. Any system that can make HTTP requests and consume JSON/OpenAPI can integrate with it. OpenClaw-specific webhook support is included, but the order flow itself is generic.

Supported Card Types

Gold cards are two different products: use gold_visa or gold_mastercard. Do not send just gold.

Supported Crypto Values

Use these exact values in the crypto field when creating an order:

[
  "BTC",
  "ETH",
  "USDT.ERC20",
  "USDT.TRC20",
  "USDT.BEP20",
  "USDT.SOL",
  "DOGE",
  "LTC",
  "TRX",
  "SOL",
  "BNB"
]
Important: send the exact crypto key expected by the API when creating the order. The response may later show a display symbol such as BTC or ETH for payment instructions.

1. Create Order

POST /ai-agent/process.php

Creates a new virtual prepaid card order and returns payment instructions. The server generates a unique secret. You must save it immediately. The secret is the main key used later for status checks and webhook registration.

Request Body

{
  "card_type": "gold_visa",
  "amount": 250,
  "currency": "USD",
  "crypto": "BTC",
  "email": "client@example.com"
}
Required fields: card_type, amount, crypto
Optional fields: currency (default USD), email

Success Response

Important: save the secret immediately. It is the key used to monitor order status, retrieve delivery status, and register webhooks. 
{
  "success": true,
  "order_id": "AI-GOLD_VISA-1773842620",
  "secret": "07df4a3f136171ff",
  "card_type": "gold_visa",
  "amount": 250,
  "currency": "USD",
  "payment_url": "https://ezzocard.finance/ai-agent/order-ai.php?secret=07df4a3f136171ff",
  "status_check_url": "https://ezzocard.finance/api/ai-check.php?secret=07df4a3f136171ff",
  "amount_crypto": "0.00367512",
  "crypto": "BTC",
  "address": "bc1qnuwcxx75f4r4f6xankfkgae2megjj37zg7xuz8",
  "expires_in": 1800,
  "message": "Order created successfully. Save the secret and send the exact crypto amount to the provided address."
}

Error Response Example

{
  "success": false,
  "error": "Invalid card type or amount",
  "code": "INVALID_PARAMETERS"
}

2. Check Order Status

GET /api/ai-check.php?secret={secret}

Poll this endpoint using the secret returned from order creation. It checks blockchain payment status and returns delivered card data when available.

Do not recalculate payment values: always use the exact amount_crypto and destination address returned by the create order response.

Pending Response

{
  "order_id": "AI-GOLD_VISA-1773842620",
  "secret": "07df4a3f136171ff",
  "status": "awaiting_payment",
  "time_remaining_seconds": 1425,
  "time_elapsed_seconds": 375,
  "payment_detected": false,
  "next_step": "continue_waiting",
  "check_again_in_seconds": 30,
  "payment_instructions": {
    "address": "bc1qnuwcxx75f4r4f6xankfkgae2megjj37zg7xuz8",
    "amount": "0.00367512",
    "currency": "BTC",
    "amount_formatted": "0.00367512 BTC"
  }
}

Confirmed Response

{
  "order_id": "AI-GOLD_VISA-1773842620",
  "secret": "07df4a3f136171ff",
  "status": "confirmed",
  "time_remaining_seconds": 1180,
  "payment_detected": true,
  "delivery_status": "completed",
  "next_step": "cards_ready",
  "tx_hash": "3c7b48242ae74f8f8480b65010fcfe836ba3490aac780b2e99671a7f938dc04b",
  "confirmations": 3,
  "explorer_url": "https://www.blockchain.com/explorer/transactions/btc/3c7b48242ae74f8f8480b65010fcfe836ba3490aac780b2e99671a7f938dc04b",
  "cards": [
    {
      "display_name": "$250 Gold VISA",
      "number": "4246051668636185",
      "expiry": "10/28",
      "cvv": "607",
      "system": "VISA",
      "card_type": "gold_visa"
    }
  ]
}

Expired Response

{
  "order_id": "AI-GOLD_VISA-1773842620",
  "secret": "07df4a3f136171ff",
  "status": "expired",
  "time_remaining_seconds": 0,
  "payment_detected": false,
  "error": "Payment window expired (30 minutes)",
  "next_step": "order_failed"
}

3. Register Webhook

POST /api/openclaw-webhook.php

Registers a webhook URL for an order using the secret returned by the order creation endpoint. This is useful for agents that prefer push notifications instead of polling.

Request Body

{
  "secret": "07df4a3f136171ff",
  "webhook_url": "https://example-agent.com/webhooks/ezzocard",
  "events": [
    "payment.confirmed",
    "cards.delivered"
  ]
}
Required fields: secret, webhook_url
Optional field: events
Supported events: payment.confirmed, cards.delivered, order.expired

Success Response

{
  "success": true,
  "webhook_id": "wh_9fbc0f14a1b2",
  "secret": "07df4a3f136171ff",
  "signing_secret": "9d8f6d0b5ea3f71a9a5e5d8c9b2a7f11",
  "events": [
    "payment.confirmed",
    "cards.delivered"
  ],
  "message": "Webhook registered successfully"
}
Webhook headers sent by Ezzocard:
X-OpenClaw-Signature — HMAC SHA-256 signature
X-Event-Type — event name such as payment.confirmed, cards.delivered, or order.expired
Important: the response field secret is the order secret you registered, while signing_secret is the secret used to verify webhook signatures.

Example: Complete AI Agent Flow

The following example shows the full end-to-end integration flow for an AI agent: create an order, save the returned secret, optionally register a webhook, then poll for status until the cards are delivered. 

{
  "step_1_create_order_request": {
    "method": "POST",
    "url": "https://ezzocard.finance/ai-agent/process.php",
    "body": {
      "card_type": "gold_visa",
      "amount": 250,
      "currency": "USD",
      "crypto": "BTC",
      "email": "user@example.com"
    }
  },
  "step_1_create_order_response": {
    "success": true,
    "order_id": "AI-GOLD_VISA-1773842620",
    "secret": "07df4a3f136171ff",
    "card_type": "gold_visa",
    "amount": 250,
    "currency": "USD",
    "payment_url": "https://ezzocard.finance/ai-agent/order-ai.php?secret=07df4a3f136171ff",
    "status_check_url": "https://ezzocard.finance/api/ai-check.php?secret=07df4a3f136171ff",
    "amount_crypto": "0.00367512",
    "crypto": "BTC",
    "address": "bc1qnuwcxx75f4r4f6xankfkgae2megjj37zg7xuz8",
    "expires_in": 1800,
    "message": "Order created successfully. Save the secret and send the exact crypto amount to the provided address."
  },
  "step_2_register_webhook_request": {
    "method": "POST",
    "url": "https://ezzocard.finance/api/openclaw-webhook.php",
    "body": {
      "secret": "07df4a3f136171ff",
      "webhook_url": "https://example-agent.com/webhooks/ezzocard",
      "events": [
        "payment.confirmed",
        "cards.delivered"
      ]
    }
  },
  "step_2_register_webhook_response": {
    "success": true,
    "webhook_id": "wh_9fbc0f14a1b2",
    "secret": "07df4a3f136171ff",
    "signing_secret": "9d8f6d0b5ea3f71a9a5e5d8c9b2a7f11",
    "events": [
      "payment.confirmed",
      "cards.delivered"
    ],
    "message": "Webhook registered successfully"
  },
  "step_3_check_status_request": {
    "method": "GET",
    "url": "https://ezzocard.finance/api/ai-check.php?secret=07df4a3f136171ff"
  },
  "step_3_check_status_response_pending": {
    "order_id": "AI-GOLD_VISA-1773842620",
    "secret": "07df4a3f136171ff",
    "status": "awaiting_payment",
    "time_remaining_seconds": 1425,
    "time_elapsed_seconds": 375,
    "payment_detected": false,
    "next_step": "continue_waiting",
    "check_again_in_seconds": 30,
    "payment_instructions": {
      "address": "bc1qnuwcxx75f4r4f6xankfkgae2megjj37zg7xuz8",
      "amount": "0.00367512",
      "currency": "BTC",
      "amount_formatted": "0.00367512 BTC"
    }
  },
  "step_4_check_status_response_confirmed": {
    "order_id": "AI-GOLD_VISA-1773842620",
    "secret": "07df4a3f136171ff",
    "status": "confirmed",
    "time_remaining_seconds": 1180,
    "payment_detected": true,
    "delivery_status": "completed",
    "next_step": "cards_ready",
    "tx_hash": "3c7b48242ae74f8f8480b65010fcfe836ba3490aac780b2e99671a7f938dc04b",
    "confirmations": 3,
    "explorer_url": "https://www.blockchain.com/explorer/transactions/btc/3c7b48242ae74f8f8480b65010fcfe836ba3490aac780b2e99671a7f938dc04b",
    "cards": [
      {
        "display_name": "$250 Gold VISA",
        "number": "4246051668636185",
        "expiry": "10/28",
        "cvv": "607",
        "system": "VISA",
        "card_type": "gold_visa"
      }
    ]
  }
}
Important: the AI agent should always store the returned secret immediately after order creation. That same secret is then used for:
  • status checks via /api/ai-check.php?secret=...
  • webhook registration via /api/openclaw-webhook.php
Important distinction: order_id is informational and may appear in responses, while secret is the primary client-side tracking key.

Recommended Integration Flow

Step 1

Create the order with POST /ai-agent/process.php.

Step 2

Store the returned secret immediately.

Step 3

Present amount_crypto and address to the user.

Step 4

Poll /api/ai-check.php?secret=... or register a webhook with the same secret.

Step 5

When status becomes confirmed, read cards.

Step 6

Handle expired as a failed order that requires a new order.

Best practices for bots and LLM agents:
  • Always save the secret from the create order response.
  • Always use the returned status_check_url directly.
  • Always use the same order secret when registering webhooks.
  • Always send the exact amount_crypto; do not estimate or round it yourself.
  • Poll every 30 seconds rather than continuously.
  • Treat card data as sensitive output.
  • Use the exact supported crypto keys and card_type values.

Example: Complete AI Agent Flow

The following example shows the full end-to-end integration flow for an AI agent: create an order, save the returned secret, optionally register a webhook, then poll for status until the cards are delivered. 

{
  "step_1_create_order_request": {
    "method": "POST",
    "url": "https://ezzocard.finance/ai-agent/process.php",
    "body": {
      "card_type": "gold_visa",
      "amount": 250,
      "currency": "USD",
      "crypto": "BTC",
      "email": "user@example.com"
    }
  },
  "step_1_create_order_response": {
    "success": true,
    "order_id": "AI-GOLD_VISA-1773842620",
    "secret": "07df4a3f136171ff",
    "card_type": "gold_visa",
    "amount": 250,
    "currency": "USD",
    "payment_url": "https://ezzocard.finance/ai-agent/order-ai.php?secret=07df4a3f136171ff",
    "status_check_url": "https://ezzocard.finance/api/ai-check.php?secret=07df4a3f136171ff",
    "amount_crypto": "0.00367512",
    "crypto": "BTC",
    "address": "bc1qnuwcxx75f4r4f6xankfkgae2megjj37zg7xuz8",
    "expires_in": 1800,
    "message": "Order created successfully. Save the secret and send the exact crypto amount to the provided address."
  },
  "step_2_register_webhook_request": {
    "method": "POST",
    "url": "https://ezzocard.finance/api/openclaw-webhook.php",
    "body": {
      "secret": "07df4a3f136171ff",
      "webhook_url": "https://example-agent.com/webhooks/ezzocard",
      "events": [
        "payment.confirmed",
        "cards.delivered"
      ]
    }
  },
  "step_2_register_webhook_response": {
    "success": true,
    "webhook_id": "wh_9fbc0f14a1b2",
    "secret": "07df4a3f136171ff",
    "signing_secret": "9d8f6d0b5ea3f71a9a5e5d8c9b2a7f11",
    "events": [
      "payment.confirmed",
      "cards.delivered"
    ],
    "message": "Webhook registered successfully"
  },
  "step_3_check_status_request": {
    "method": "GET",
    "url": "https://ezzocard.finance/api/ai-check.php?secret=07df4a3f136171ff"
  },
  "step_3_check_status_response_pending": {
    "order_id": "AI-GOLD_VISA-1773842620",
    "secret": "07df4a3f136171ff",
    "status": "awaiting_payment",
    "time_remaining_seconds": 1425,
    "time_elapsed_seconds": 375,
    "payment_detected": false,
    "next_step": "continue_waiting",
    "check_again_in_seconds": 30,
    "payment_instructions": {
      "address": "bc1qnuwcxx75f4r4f6xankfkgae2megjj37zg7xuz8",
      "amount": "0.00367512",
      "currency": "BTC",
      "amount_formatted": "0.00367512 BTC"
    }
  },
  "step_4_check_status_response_confirmed": {
    "order_id": "AI-GOLD_VISA-1773842620",
    "secret": "07df4a3f136171ff",
    "status": "confirmed",
    "time_remaining_seconds": 1180,
    "payment_detected": true,
    "delivery_status": "completed",
    "next_step": "cards_ready",
    "tx_hash": "3c7b48242ae74f8f8480b65010fcfe836ba3490aac780b2e99671a7f938dc04b",
    "confirmations": 3,
    "explorer_url": "https://www.blockchain.com/explorer/transactions/btc/3c7b48242ae74f8f8480b65010fcfe836ba3490aac780b2e99671a7f938dc04b",
    "cards": [
      {
        "display_name": "$250 Gold VISA",
        "number": "4246051668636185",
        "expiry": "10/28",
        "cvv": "607",
        "system": "VISA",
        "card_type": "gold_visa"
      }
    ]
  }
}
Important: the AI agent should always store the returned secret immediately after order creation. That same secret is then used for:
  • status checks via /api/ai-check.php?secret=...
  • webhook registration via /api/openclaw-webhook.php
Important distinction: order_id is informational and may appear in responses, while secret is the primary client-side tracking key.
Minimal agent logic:
1. Create order
2. Save secret
3. Show payment instructions
4. Poll status or register webhook with the same secret
5. When status = confirmed, read cards

JavaScript Example

class EzzocardAgentClient {
  async createOrder(payload) {
    const res = await fetch('https://ezzocard.finance/ai-agent/process.php', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload)
    });

    return await res.json();
  }

  async checkStatus(secret) {
    const res = await fetch(`https://ezzocard.finance/api/ai-check.php?secret=${encodeURIComponent(secret)}`, {
      method: 'GET'
    });

    return await res.json();
  }

  async registerWebhook(secret, webhookUrl, events = ['payment.confirmed', 'cards.delivered']) {
    const res = await fetch('https://ezzocard.finance/api/openclaw-webhook.php', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        secret,
        webhook_url: webhookUrl,
        events
      })
    });

    return await res.json();
  }

  async waitUntilReady(secret, onReady) {
    const interval = setInterval(async () => {
      try {
        const status = await this.checkStatus(secret);

        if (status.status === 'confirmed' && Array.isArray(status.cards)) {
          clearInterval(interval);
          onReady(status.cards, status);
        }

        if (status.status === 'expired') {
          clearInterval(interval);
          console.log('Order expired');
        }
      } catch (err) {
        console.error('Status check error:', err);
      }
    }, 30000);
  }
}

// Example usage:
const client = new EzzocardAgentClient();

const order = await client.createOrder({
  card_type: 'gold_visa',
  amount: 250,
  currency: 'USD',
  crypto: 'BTC',
  email: 'user@example.com'
});

console.log(order.secret);
console.log(order.status_check_url);

const webhook = await client.registerWebhook(
  order.secret,
  'https://example-agent.com/webhooks/ezzocard',
  ['payment.confirmed', 'cards.delivered']
);

console.log(webhook.signing_secret);

await client.waitUntilReady(order.secret, (cards, fullStatus) => {
  console.log('Cards delivered:', cards);
  console.log('Status payload:', fullStatus);
});

Implementation Notes

← Back to AI Agent Interface