Topping up & payments

Top up

Usage → Top up: choose an amount and a gateway, and you are redirected to the gateway's page. On return, Errora verifies the payment with the gateway and only then credits the wallet.

GET  /api/v1/payment-gateways                          # gateways available to you
POST /api/v1/organizations/{org_id}/wallet/top-up      # {"amount": 500000, "gateway": "zarinpal"}
GET  /api/v1/organizations/{org_id}/payments
GET  /payments/callback/{token}                        # the gateway returns the user here

Only the verify step moves money. A callback alone never credits a wallet — that is what keeps a forged return URL from minting credit.

Gateways

Gateway	Use
ZarinPal	Production payments
Test gateway	Local/staging — renders a confirm/reject page and returns through the same callback

Only the gateways this Errora instance has configured are offered at checkout.

Payment states

State	Meaning
pending	Started, user is at the gateway
paid	Verified and credited
failed	The gateway rejected it, or verification failed
canceled	The user came back without paying

The payments table lists every attempt with its reference and receipt, next to the wallet ledger.

Permissions

Topping up and viewing payments requires the org:billing capability — the billing role exists so finance can do this without engineering access.

Troubleshooting

Symptom	Cause / fix
No gateways offered	No payment gateway is available right now — contact support
Paid but balance unchanged	Verification failed — check the payment row's status; the money is with the gateway, not lost
Callback returns an error	The callback token expired or was already used; start a new top-up
Test gateway not offered	It only exists on local and staging environments, never in production