Testing#

Test mode is a key mode, not a separate environment. A povito_ck_test_… key against the normal API host creates objects with livemode: false that never touch money and never share a row with live objects. Everything in the Checkout guides works identically in both modes. Test keys are accepted on the Live host as well as the Sandbox host — see Keys and environments.

Test keys#

Key	Where	Unlocks
`povito_ck_test_<key_id>_<secret>`	your server	the merchant API, in test mode
`povito_pk_test_<key_id>_<secret>`	browser or app	`/v1/public/*` for your test sessions — only needed for the Phase 2 drop-in

Keys are shown once when issued and stored hashed. A test key cannot read a live object (404, never a hint that it exists) and cannot register a live webhook endpoint (403 mode_mismatch). Scopes are the same set as live: sessions:write, sessions:read, refunds:write, refunds:read, webhooks:manage, events:read, customers:read.

The `test` gateway#

In test mode your merchant can enable a method called test: a simulated vendor with a page of buttons instead of a bank. Check GET /v1/payment_methods for "code": "test", "enabled": true; if it is not there, ask Povito to switch it on for your test merchant. It presents IQD and USD, supports partial refunds, and is refused outright in live mode.

Create a session that offers itjson

{ "…": "…", "payment_method_types": ["test"] }

Omitting payment_method_types on a test merchant does not include test — it must be asked for explicitly, so a test key with your real methods enabled behaves like production.

The buttons#

After phone verification the page redirects to checkout.povito.com/t/{attempt_id} — the simulated vendor — showing the amount and four buttons:

Button	What the "vendor" answers	Result
Succeed	captured, exactly the presented amount	attempt `succeeded`, session `completed`, `payment_status: paid`, `checkout.session.completed` fires
Fail	declined (`simulated_decline`)	attempt `failed`, session back to `open`, `payment.attempt.failed` fires; the shopper can pick another method
Cancel	cancelled by the shopper	attempt `canceled`, session back to `open`
Take 90 s	no answer yet	the page returns and polls; the attempt resolves by the amount rule below — pick a `…003` amount to actually watch it stay pending

Each button sends the shopper back to checkout.povito.com/r/{attempt_id} — the same return path a real vendor uses — where the page asks the API to verify, exactly as in live mode. Automation can press the buttons through the public API with a publishable key:

Press "Succeed" from a scriptbash

curl -X POST https://api.checkout.povito.com/v1/public/test-gateway/pa_test_3M8XQ2K7A9BC4DEFGH1J/decide \
  -H "Authorization: Bearer $POVITO_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "decision": "succeeded" }'

Response 200json

{ "attempt_id": "pa_test_3M8XQ2K7A9BC4DEFGH1J", "status": "succeeded", "return_url": "https://checkout.povito.com/r/pa_test_3M8XQ2K7A9BC4DEFGH1J" }

decision is succeeded, failed, canceled or slow. The call is 403 for any attempt that is not a test-gateway attempt.

Amount-driven outcomes#

For unattended tests the last three digits of the presented amount decide, unless a button was pressed:

Amount ends in	Outcome
`…001` (e.g. `45001`)	declined immediately — `payment.attempt.failed`, reason `simulated_decline`
`…002` (e.g. `45002`)	stays pending; the reconcile job keeps re-checking on a backoff and the attempt expires after 24 hours with reason `timeout`
`…003` (e.g. `45003`)	pending for 30 seconds, then succeeds — exercises the "shopper left the vendor page, webhook arrives later" path
anything else	succeeds

The line_items must still reconcile, so bump a charge line by the same amount.

The test phone and OTP#

In test mode the phone +9647500000000 always receives the code 000000, and no SMS is sent. Any other number goes through the real OTP provider (with the same 5-per-10-minutes limit), so use the test phone in automation. The page shows a hint with the code when a session is in test mode.

A verified phone yields a session-scoped customer_token; the hosted page keeps it in an HTTP-only cookie, a script passes it as X-Povito-Customer-Token on the public API.

Vendor sandboxes#

Beyond the simulated gateway, Povito ops can attach real vendor sandboxes — ZainCash UAT, FIB staging, Stripe test — to your test merchant so zaincash, fib or card sessions in test mode go to the vendor's own test environment. Ask for it when you are ready for integration verification; each vendor's sandbox has its own test accounts and cards, which Povito support will share.

Webhooks in test mode#

Register an endpoint with "mode": "test" using your test key; test events go only to test endpoints. The test tool sends a synthetic event of any type:

bash

curl -X POST https://api.checkout.povito.com/v1/webhook_endpoints/we_2K7A9BC4DEFGH1J3M8XQ/test \
  -H "Authorization: Bearer $POVITO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "refund.succeeded" }'

For local development your endpoint must be reachable from Povito over HTTPS — use a tunnel. Private-network and localhost targets are refused at registration.

A full run, end to end#

This is the sequence Povito's own end-to-end test performs against the API — every call on this site, in order. $SK is a test secret key, $PK a test publishable key.