Backend

Go SDK

Idiomatic Go client with context propagation and structured errors.

Updated Jul 15, 2026SDK v1.0.0API 2026-07-01 Edit on GitHub Report an issue

Idiomatic Go client with context propagation and structured errors. This page follows the same layout as every other Korven One SDK reference — install, authenticate, ship your first request, then wire webhooks and production-grade retries.

Overview

Go is a first-party integration for the Korven One platform. It ships with typed models, a signed-webhook verifier and idempotent request helpers so you can build reliable payment, wallet and remittance flows.

Installation

API v1

go get github.com/korvenone/go

Requirements

Go 1.22+
A Korven One account with sandbox and (optionally) live API keys
An HTTPS-reachable webhook endpoint for asynchronous events

Authentication

Every request is authenticated with a bearer token. Use sk_test_... in sandbox and sk_live_... once your merchant account is activated. Never ship secret keys to the browser — use publishable keys (pk_*) for client-side flows.

API v1

export KORVEN_SECRET_KEY=sk_test_...

Quickstart

Create your first payment in under a minute. The snippet below uses the sandbox environment and an idempotency key so retries are safe.

SDK v1.0.0

client := korven.NewClient(os.Getenv("KORVEN_SECRET_KEY"))

payment, err := client.Payments.Create(ctx, &korven.PaymentCreateParams{
  Amount:   250000,
  Currency: "HTG",
  Customer: "cus_9a2b",
}, korven.WithIdempotencyKey(uuid.NewString()))

Example response

{
  "id": "pay_01HT3M9QK7ZS9V0AB1CDEFGH",
  "object": "payment",
  "amount": 250000,
  "currency": "HTG",
  "status": "succeeded",
  "customer": "cus_9a2b",
  "receipt_number": "RCP-2026-0000142",
  "livemode": false,
  "created": 1794902400
}

Errors & retries

The Korven One API uses deterministic error codes. Any 5xx response or network failure is safe to retry with the same Idempotency-Key — the API will replay the original result instead of creating a duplicate.

Recommended strategy

Exponential backoff: 250ms, 500ms, 1s, 2s, 4s (max 5 attempts).
Always include an Idempotency-Key on writes.
Surface 4xx validation errors to the user immediately.

Rate limits

Default limits: 100 read requests / second and 25 write requests / second per API key. Response headers X-RateLimit-Remaining and X-RateLimit-Reset expose the current window; a 429 response includes a Retry-After header.

Webhooks

Subscribe to events like payment.succeeded, payment.failed and settlement.paid. Every delivery is signed with HMAC-SHA256 — verify the Korven-Signature header before trusting the payload.

Examples

Hosted checkout for one-off payments
Recurring subscriptions with proration
Marketplace split payments and payouts
Cross-border remittances with locked FX quotes