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_7Fq2XmR9vTb4NcZ1yWd6Ke
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_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -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_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -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_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -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_7Fq2XmR9vTb4NcZ1yWd6Ke" \
  -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

Order lookups have no dedicated allowance. They draw on the general client-API budget of 1,000 requests per hour per API key, shared with every other /api/v1/* endpoint. See Rate Limits.

That shared budget is the reason to back off when polling: an order polled every second burns your entire hourly allowance in under 17 minutes, and starves every other call your integration needs to make. Poll no faster than every 10 s, and prefer 60 s for DELAYED orders — see Delivery Semantics.

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