Initialize payment

Initialize a payment transaction with HMAC signature verification and idempotency protection.

🔐 HMAC Signing (REQUIRED)

All payment initialization requests MUST include HMAC-SHA256 signature:

1. Generate Timestamp: Get current Unix timestamp in seconds
2. Create Payload: Concatenate timestamp + "." + JSON_body
3. Sign Payload: HMAC-SHA256(hmac_secret, payload) → base64 encode
4. Include Headers:
   • X-Timestamp: Unix timestamp (must be within 5 minutes)
   • X-Signature: Base64-encoded HMAC signature
   • Idempotency-Key: Unique key to prevent duplicate payments

🔄 Idempotency Protection (REQUIRED)

Include Idempotency-Key header to prevent duplicate payment initialization. If the same key is used, the original payment initialization is returned.

• Recommended format: payment-{timestamp}-{random}
• Must be unique per payment attempt
• Prevents duplicate charges on network retries
• Returns existing payment if key already used

🛡️ Amount validation (anti-tampering)

When you pass an order_id, the server validates amount against that order’s authoritative total — a amount that doesn’t match the order total is rejected with 400 amount_mismatch. The order total was itself validated against the catalog + the shopper’s real promotions/gift card at order creation (see the order endpoint’s server-side price validation), so you cannot charge less than the order is worth. Pass the order’s real total_amount; don’t compute or alter it client-side.

Provider-Specific Flows:

Stripe (redirect):

1. Initialize payment with amount, currency, email
2. Redirect customer to checkout_url
3. Customer completes payment on Stripe
4. Stripe redirects to success/cancel URL
5. Verify payment status with /v1/payments/verify

PayPal (popup):

1. Initialize payment with amount and currency
2. Use the returned client_id and paypal_order_id to render the PayPal Buttons popup in your frontend
3. Customer approves the payment in the PayPal window
4. Verify payment status with /v1/payments/verify — this captures the approved order

Paystack (popup):

1. Initialize payment with amount, currency, email
2. Use returned public_key and reference to open Paystack popup
3. Customer completes payment in popup
4. Verify payment status with /v1/payments/verify

M-Pesa (STK Push):

1. Initialize payment with amount and phone (254XXXXXXXXX format)
2. Customer receives STK Push prompt on their phone
3. Customer enters M-Pesa PIN
4. Verify payment status with /v1/payments/verify

Security Notes:

• HMAC secret is displayed in the Integrations page (Developer section)
• Never expose HMAC secret in client-side code
• Regenerate secret immediately if compromised
• Requests with invalid/missing signatures return 401 Unauthorized
• Timestamps older than 5 minutes are rejected (prevents replay attacks)

Rate Limiting:

• Additional 100 requests/hour limit for payment initialization
• Separate from global API rate limits

Key Type Support:

• ✅ Secret keys (full access)
• ❌ Publishable keys (forbidden - returns 403)