5 steps

Quickstart

Create your first payment in under 10 minutes. This walk-through uses the sandbox environment and does not require any legal approvals.

Updated Jul 15, 2026API 2026-07-01 Edit on GitHub Report an issue

Sandbox first

Sandbox is fully isolated: no real money moves, no KYC required, and you can wipe your data at any time.

Prerequisites

Node 18+ or Python 3.10+ (or use cURL)
A publicly reachable HTTPS URL for webhooks — use ngrok or the Korven CLI in development
A Korven One account (free)

1. Create an account

2. Generate a sandbox key

Go to Developers → API Keys, click Create key, choose Sandbox, and copy the secret. The full value is shown only once.

Never commit keys

Store secrets in environment variables or your secrets manager. Any key committed to a public repo is auto-revoked.

3. Make your first request

API v1

curl -X POST https://api.korvenone.com/v1/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 4f3c0e2a-2b6f-4c" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "currency": "HTG",
    "customer": "cus_9a2b",
    "description": "Order #1042",
    "capture_method": "automatic"
  }'

4. Receive a webhook

Add an endpoint in Developers → Webhooks. Korven will POST a signed payment.succeeded event within seconds of every successful capture.

{
  "id": "evt_01HT3MK…",
  "type": "payment.succeeded",
  "created": 1794902401,
  "livemode": false,
  "data": { "object": { "id": "pay_01HT3M9…", "amount": 250000, "currency": "HTG", "status": "succeeded" } }
}

5. Go live

Complete the 9-step activation from your dashboard. Live keys unlock automatically after approval.

Introduction

Authentication