Security model

Keep keys, checkout, webhooks, and environments separated.

These are the operational security rules merchants need to follow when integrating with Alpha DigiWallet.

Account protection

Enable 2FA before creating production keys, webhooks, payout methods, or live operational workflows.
Use individual user accounts instead of shared logins.
Review team access when staff, contractors, or systems change.
Contact Alpha support from a verified business contact path if an owner/admin loses 2FA access.

API key handling

Store secret keys only on your server or secret manager.
Never embed sk_test, sk_staging, or sk_production keys in browser JavaScript, mobile apps, public repos, screenshots, or support tickets.
Use the minimum scopes needed for your integration.
Rotate and revoke keys from the merchant dashboard when staff or systems change.
Keep test and live keys in separate configuration paths.

Hosted checkout boundary

Send buyers to the Alpha checkout URL returned by the payment API. Your integration should not collect or submit card numbers, CVCs, PINs, or other payment credentials for Alpha payments.

Important

If your shop is asking buyers for card details for an Alpha payment, stop that flow and use the returned checkout_url instead.

Webhook safety

Verify signatures on the raw body before parsing or trusting the event.
For encrypted webhooks, verify the signature over the encrypted body before decrypting.
Store generated webhook decryption private keys once in your own secret manager; Alpha stores only the public key.
Treat event delivery as at-least-once. Process idempotently by event_id.
Do not log webhook signing secrets or full authorization headers.
Respond with 2xx only after durable processing.
Keep production webhook endpoints separate from staging endpoints.

Common integration mistakes

Mistake	Why it matters	Correct approach
Using a key from the wrong environment	Can contaminate environments and break reconciliation.	Create keys from the matching Alpha dashboard and keep each environment in a separate secret path.
Fulfilling from redirect URL only	Redirects can be abandoned, replayed, or arrive before final webhook.	Fulfil from payment.completed webhook or server-side payment read.
Ignoring idempotency	Retries can create duplicate checkout sessions.	Send the required Idempotency-Key for payment creation.
Assuming completed equals settled	A completed payment may not be payoutable yet.	Use settlement and ledger balances for finance operations.