Integration Guides

Essential guides for building robust, production-ready integrations with the Starship Rewards API.

Critical for Production

Idempotency

Idempotency keys ensure that network retries, user double-clicks, and application crashes don't result in duplicate orders.

Without idempotency:

• Network timeout → User retries → Two orders created
• User double-clicks → Two orders created

With idempotency:

• All retries return the original response safely

curl -X POST "{{host}}/api/v1/orders" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here" \
  -H "Idempotency-Key: ord_abc123_1705689660" \
  -d '{"product_id": 123, "denomination": 100, "quantity": 5}'

Read the full Idempotency Guide →

Webhooks

Receive real-time notifications when orders are completed, failed, or cancelled.

Benefits:

• No polling needed
• Instant voucher delivery
• Reduced API calls

# Register webhook
curl -X POST "{{host}}/client/api/webhooks" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here" \
  -d '{"url": "https://your-server.com/webhooks", "events": ["order.completed"]}'

Read the full Webhooks Guide →

Quick Integration Checklist

Before going to production, ensure you've implemented:

• Idempotency keys on all order/payout requests
• Webhook endpoint for order status updates
• Signature verification for webhooks
• Error handling with exponential backoff
• API credentials stored securely
• Logging of all API requests and responses