Checkout API#

Povito Checkout is a hosted payment page for merchants in Iraq. Your server creates a checkout session, you send the shopper to the url you get back, the shopper verifies their phone and pays with ZainCash, FIB, a card, or cash on delivery, and Povito tells you the outcome — by webhook and, authoritatively, by GET /checkout/sessions/{id}.

• QuickstartCreate a session, redirect, verify, handle the webhook. Five minutes with curl.
• Hosted checkoutEvery session option: prefill, what to collect, locales, expiry, return URLs, branding.
• Payment methodsRedirect, present, charge and offline flows; cash on delivery; card routing; USD presentment.
• WebhooksSignature verification in Node, PHP, Python and Dart. Retries, redelivery, idempotency.
• TestingTest keys, the simulated gateway, the test phone and OTP, the webhook test tool.
• API referenceGenerated from the OpenAPI contract. Interactive, or static without JavaScript.

The shape of an integration#

1. Create a session from your server with your secret key: POST /v1/checkout/sessions with the amount, the line items, your own reference_id and a success_url. You get an id and a url.
2. Send the shopper to url (https://checkout.povito.com/c/…). Povito handles phone verification, name and address collection, the payment method picker and the vendor hand-off.
3. The shopper comes back to your success_url with session_id and reference_id appended — and nothing else. The URL never carries a status.
4. Verify with GET /v1/checkout/sessions/{id} and fulfil when payment_status is paid (or requires_offline_collection for cash on delivery).
5. Handle checkout.session.completed on your webhook endpoint for the cases where the shopper never comes back. Treat it as a prompt to run step 4.

Three things to know before you start#

Money is integers in minor units, and the Iraqi dinar has none. 45000 is forty-five thousand dinars. USD is cents: 3435 is $34.35. Floats and strings are rejected.

A webhook is a hint; the session is the truth. Povito applies the same rule to the payment vendors it talks to — a vendor callback never marks anything paid until Povito verifies with the vendor's own status API and the captured amount equals the presented amount. Do the same: on a webhook, GET the session, then act.

Two keys, two surfaces. povito_ck_… secret keys live on your server and unlock the merchant API. povito_pk_… publishable keys are safe in a browser or app and unlock only /v1/public/*, which is what the hosted page (and, in Phase 2, the embedded drop-in) uses.

Base URLs#

Test mode is a key mode, not a separate host: a povito_ck_test_… key against the live host creates livemode: false objects that never share a row with live data. How that compares with the Partner API, where the environment decides: Keys and environments.

Status#

Povito Checkout is in Phase 1 of ADR-CHK-001: the merchant API, hosted page, test mode, webhooks and refunds are built and covered by an end-to-end test, and each route is marked done only after it has been exercised live (Povito's completion gate). The embedded drop-in, saved instruments and the customer profile API are Phase 2 and are marked as such throughout these docs. Contract version: see the footer of every page.