Get Order Details API

Retrieve detailed information for a specific order, including decrypted voucher codes when the order has been delivered.

Endpoint

GET /api/v1/orders/{id}

Authentication: API Key + Secret required

Request Headers

X-API-Key: sk_live_abc123def456
X-API-Secret: your-secret-here

Path Parameters

Response

Success Response

Status Code: 200 OK

Response Body:

{
  "id": 12345,
  "reference_code": "ORD-ABC123",
  "transaction_id": 789,
  "amount": "25.00",
  "product_id": 1001,
  "denomination": "25.00",
  "quantity": 1,
  "discount": "0.00",
  "vouchers": [
    {
      "claim_url": "https://redeem.example.com/abc123xyz",
      "card_number": "1234567890123456",
      "voucher_reference_number": "REF-VOUCHER-123",
      "pin_code": "1234",
      "expires_at": "2025-12-31T23:59:59Z"
    }
  ],
  "status": "delivered",
  "placed_at": "2024-01-15T10:30:00Z"
}

Response Fields

Order Fields

Voucher Fields

The fields present depend on the product's delivery_type (see Delivery Type Values).

Voucher Availability by Status

Orders progress through different statuses, with voucher data becoming available based on the current status:

Status Flow:

Order Creation → PENDING → PROCESSING → DELIVERED
                    ↓
                 FAILED (if processing fails)

Important: Voucher codes are only decrypted and returned when the order status is DELIVERED or PARTIALLY_DELIVERED. For other statuses, the vouchers array will be empty.

Security Features

Encryption

All sensitive voucher data is encrypted at rest:

• Voucher codes are stored using AES-256 encryption
• Decryption only occurs when order status is DELIVERED
• PIN codes and reference numbers are separately encrypted

Examples

# Get order details
curl -X GET "{{host}}/api/v1/orders/12345" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

# Get order and extract vouchers (using jq)
curl -X GET "{{host}}/api/v1/orders/12345" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here" \
  | jq '.vouchers'

# Check order status
curl -X GET "{{host}}/api/v1/orders/12345" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here" \
  | jq '.status'

# Get voucher codes securely
curl -s -X GET "{{host}}/api/v1/orders/12345" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here" \
  | jq -r '.vouchers[] | "Card: \(.card_number) PIN: \(.pin_code)"'

Error Responses

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or expired access token"
}

404 Not Found

{
  "error": "not_found",
  "message": "No Matching Result Found!"
}

500 Internal Server Error

{
  "error": "internal_error",
  "message": "Failed to retrieve order"
}

Best Practices

Security

1. Never Log Voucher Codes - Avoid logging sensitive voucher data
2. Secure Display - Hide voucher codes by default, reveal on click
3. Copy Protection - Implement copy-to-clipboard functionality
4. Session Timeout - Auto-logout after viewing vouchers
5. Audit Trail - Log voucher access for security monitoring

Performance

1. Poll Efficiently - Use exponential backoff when checking status
2. Cache Static Data - Cache delivered orders client-side
3. Lazy Load Vouchers - Load vouchers only when needed
4. Minimize API Calls - Batch status checks where possible

User Experience

1. Status Indicators - Show clear order status with icons
2. Progress Updates - Display processing progress if available
3. Copy Functionality - Make voucher codes easy to copy
4. Expiration Warnings - Highlight approaching expiration dates
5. Redemption Links - Provide direct redemption URLs

Rate Limits

• Standard Rate: 200 requests per minute
• Burst Limit: 20 requests per 10 seconds
• Per-Order Limit: 60 requests per order per hour

Rate limiting prevents:

• Voucher harvesting attempts
• Excessive status polling
• Automated scraping

Monitoring Best Practices

Status Polling Strategy

Timeout Recommendations

• Fast Products: 2-5 minutes
• Standard Products: 5-10 minutes
• Slow Products: 10-30 minutes

Next Steps

• List All Orders - View order history
• Create New Order - Submit orders
• Product Catalog - Browse available products
• Authentication - Secure API access