Using the Swagger UI

Accessing Swagger UI

Development/Sandbox Environment

• URL: https://partner-api.dev.zebec.io/api-docs
• Or locally: http://localhost:8001/api-docs
• Authentication: Required (use HMAC generator tool)

Getting Started

Step 1: Generate Authentication Headers

Before testing any endpoints, you need to generate valid HMAC authentication headers:

1. Go to the HMAC Generator tool
2. Enter your API credentials (API Key and Secret)
3. Select the HTTP method (GET/POST) and endpoint path
4. Add request body if needed (for POST requests)
5. Click "Generate Headers"
6. Copy the generated header values

Step 2: Authorize in Swagger UI

1. Open the Swagger UI
2. Click the "Authorize" button at the top of the page
3. You'll see 4 fields to fill:
   • x-api-key
   • x-timestamp
   • x-nonce
   • x-signature
4. Paste the values from the HMAC generator into each field
5. Click "Authorize"
6. Close the modal

Step 3: Test Endpoints

1. Browse the available endpoints organized by tags:
   • Cards v1 (Standard) - Basic card operations (all API keys)
   • Cards v2 (Premium) - Advanced features (v2 keys only)
   • Admin - Client management (mTLS only)
2. Click on an endpoint to expand it
3. Click "Try it out"
4. Fill in any required parameters or request body
5. Click "Execute"
6. View the response below

Understanding the API Organization

🎁 Cards v1 (Standard)

Core card operations available to all partners:

• GET /orders/programs - Get available card programs by country
• POST /orders/validate-address - Validate recipient address
• POST /orders/create - Create a new card order
• GET /orders/lookup - Lookup orders by email, orderId, or txHash

💎 Cards v2 (Premium)

Advanced features requiring v2 API key:

• GET /v2/cards/{orderId} - Get card details with balance
• GET /v2/cards/{orderId}/balance - Get current balance (requires balanceAccess)
• POST /v2/cards/{orderId}/transactions - Get transaction history (requires transactionAccess)
• GET /v2/cards - List all cards for this client

Testing Tips

1. Start with Health Check

Test the unauthenticated ping endpoint first:

GET /ping

This confirms the API is accessible.

2. Test Authentication

Try a simple authenticated endpoint to verify your HMAC signature:

GET /orders/programs?country=USA

3. Use Sandbox Email Patterns

When testing order creation in development/sandbox, use special email patterns:

• test@example.com → SUCCESS status
• test@example.com.pending → PENDING status
• test@example.com.failed → FAILED status

See the Sandbox Environment Guide for details.

4. Check Response Schemas

Swagger UI shows the expected response schema for each endpoint. Use this to understand the data structure.

5. Save Successful Requests

Swagger UI allows you to download request/response examples. Use this to build your integration code.

Common Issues

401 Unauthorized

• ✅ Regenerate headers with current timestamp
• ✅ Verify API key is correct
• ✅ Check all 4 headers are filled in Authorize modal
• ✅ Ensure nonce header is present

403 Forbidden

• ✅ Check if you're using v1 key for v2 endpoints
• ✅ Verify required feature flags are enabled (e.g., balanceAccess)
• ✅ Confirm API key is active

400 Bad Request

• ✅ Review request body matches the schema
• ✅ Check all required fields are present
• ✅ Validate field formats (emails, UUIDs, country codes)

Additional Resources

• API Integration Guide - Complete integration walkthrough
• API Specification - Detailed endpoint documentation
• HMAC Generator - Generate authentication headers
• Sandbox Guide - Testing without live backend