Test mode and live mode

Build against test mode with no real money, then switch to live keys once your account is approved, using the go-live checklist.

Every Teyra Pay account has two separate modes. You choose the mode with the API key you use.

Feature	Test mode	Live mode
Secret key	`sk_test_…`	`sk_live_…`
`livemode` on objects	`false`	`true`
Money moves	No	Yes
Checkout page	The Teyra Pay checkout page with a TEST badge, connected to the card processor's test environment. Pay with test cards.	The same page with real KNET, mada, cards, Apple Pay…
`return_url` and webhook URLs	`https://` or `http://` (for local development and tunnels)	`https://` only
Available	Right after sign-up	After your account is approved
Webhooks	Sent to your test-mode endpoints, with `"livemode": false`	Sent to your live-mode endpoints, with `"livemode": true`

Test and live data never mix. A payment created with a test key can only be read, refunded or listed with a test key.

Going live

Live mode requires an approved account. Until approval, live requests return HTTP status 403:

{
  "error": {
    "code": "merchant_not_active",
    "message": "Live payments are available once your account is activated."
  }
}

In the dashboard, open Onboarding and fill in your business details, contact person and bank account, then upload the required documents (for example civil ID, commercial license and a bank letter, depending on your business type). Submit for review.

Wait for approval

The Teyra Pay team reviews your application. If something is missing, you'll be asked for more information in the dashboard. When the account is approved, its status becomes Active.

Create a live key and switch

Create a key in Live mode under Developers → API keys (you confirm it with your password). Replace sk_test_… with sk_live_… in your production configuration.

Add a live webhook endpoint

Register your production webhook URL with the live key (or in the dashboard in live mode) and store its signing secret. See Webhooks.

Live mode needs HTTPS

In live mode, every URL you give Teyra Pay must start with https://:

return_url when you create a payment;
the url of a webhook endpoint.

An http:// URL is rejected with 422 validation_error:

{
  "error": {
    "code": "validation_error",
    "message": "The return_url must use https:// in live mode.",
    "details": { "fields": { "return_url": "must use https:// in live mode" } }
  }
}

Test mode accepts http:// so you can use localhost or a tunnel while you develop. Payment links have no merchant URL, so they are not affected.

Go-live checklist

Go through this list before you switch your production configuration to sk_live_….

Payments

Your server confirms every payment with GET /v1/payments/:id or a verified webhook, and never trusts the redirect alone (Return URL handling).
The return page checks that amount, currency and reference (or the stored id) match the order before it marks the order paid.
Marking an order paid is idempotent: the return page and the webhook can both arrive, in any order.
A payment.failed or payment.canceled doesn't close the order for good: the customer can still pay at the same checkout_url until expires_at (Payments).
Amounts are sent as integers in minor units with the right exponent, especially for KWD, BHD, OMR and JOD (Money and currencies).
return_url uses https://.

Webhooks

A live webhook endpoint is registered with an https:// URL that is reachable from the internet, and its live signing secret is stored on your server.
Signatures are verified against the raw body, with the 5-minute tolerance, and duplicate events are ignored by Teyra-Event-Id (Verify signatures).
The endpoint answers 2xx within 10 seconds and does slow work in the background.
Someone watches failed deliveries under Developers → Webhooks.

API calls

POST requests send an Idempotency-Key, and retries reuse it (Idempotency).
Errors are handled and logged by error.code (Errors).
429 rate_limited and 5xx responses are retried with backoff, honouring Retry-After (Authentication).
Unknown fields, event types and error codes are ignored rather than treated as failures.

Keys and security

The live secret key is stored only on your server, in a secret store or environment variable, never in a browser, app or repository (Authentication).
Each system (website, ERP, plugin) uses its own key, so you can revoke one without affecting the others.
Your server clock is synced with NTP.
Team members on your Teyra Pay account have the roles they need and no more, with two-factor authentication turned on.

Final check

Every scenario in Testing passes in test mode.
After switching, make one small live payment with a real card, confirm it end to end (return page, webhook, dashboard), then refund it.