Accept payments with
one clean API.

Start with hosted checkout

Use a scoped merchant API key on your backend. Replace the example key with the test key issued by your dashboard. Never place long-lived credentials into client-side JavaScript or public theme files.

curl --request POST 'https://kovirapay.com/api/v1/payments' \
  --header 'Authorization: Bearer YOUR_TEST_MERCHANT_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "order_id":"ORDER-1042",
    "idempotency_key":"shop-order-1042-v1",
    "amount":"49.99",
    "currency":"EUR",
    "checkout_mode":"hosted"
  }'

On success, the response includes a payment_id, checkout_url, invoice amount, currency and test_mode. Redirect the browser to the returned checkout_url. Use a consistent idempotency key when retrying a network request for the same intended purchase.

Step 2 / Check available methods

Call GET /api/v1/methods?amount=49.99&currency=EUR to inspect the merchant's currently configured available methods and providers. Availability depends on the selected amount, provider status and supported currencies. For a specific payment, GET /api/v1/payments/PAYMENT_ID returns the authenticated status for that merchant and key mode.

Step 3 / Verify webhooks

Verify X-Kovira-Event-ID, X-Kovira-Timestamp and X-Kovira-Signature. The expected signature is v1= plus an HMAC-SHA256 over timestamp + "." + event_id + "." + exact_raw_body using your endpoint secret. Check the timestamp, deduplicate the event ID, and match order, amount, currency and environment before fulfillment.

Never mark an order paid just because the customer arrived at a success URL. The provider may still be pending; independent reconciliation is part of the payment flow. In live mode, verify the final payment status and confirmed settlement state using authenticated server-side evidence.

Direct provider checkout

Use checkout_mode: "direct" and an enabled payment_method when creating a session. Start it through POST /api/v1/payments/start with the payment ID and selected method, then redirect the customer to the returned provider URL. An unapproved method or unavailable provider is not silently activated.