Credential Management

• Never commit sk_live_ or webhook secrets to git
• Use environment variables or secret managers in CI/CD
• Rotate keys after incidents or team changes
• Issue separate apps for staging and production when possible

Mobile Integration

• Initialize SDK once at app startup
• Register both debug and release SHA256 during development
• Use sk_test_ / pk_test_ for development; call the gateway number from the user's phone
• Verify receipt JWT server-side once; treat SH_014 as replay
• Send Idempotency-Key header on POST /v1/verifications for safe retries
• Show clear UX: user must call from the same phone number entered
• Handle gateway_unavailable with retry messaging

Server Integration

• Prefer webhooks over aggressive polling for completion
• Verify webhook signatures with timing-safe comparison
• Return 2xx quickly from webhook handler; process async
• Store session_id mapped to your user record

Billing & Quotas

• Monitor available credits before marketing campaigns
• Handle insufficient_credits gracefully in UI
• Cancel abandoned sessions to release held credits faster
• Review ledger for unexpected CAPTURE/RELEASE patterns

Reliability

• Never hardcode gateway_phone_number — always use API response
• Set webhook URL before going to production
• Test webhook with POST /v1/apps/:id/test-webhook
• Log request_id from API errors for debugging

Security

• HTTPS only for webhooks and API calls
• Validate phone numbers client-side for UX, trust API normalization server-side
• Restrict admin portal access to trusted operators
• Review audit log after credential rotations