Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.borga.is/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through everything you need to go from zero to a working test payment. By the end you will have a merchant account, a test secret key, and a confirmed API response from Borga.
Borga amounts are expressed in whole Icelandic króna (ISK). Unlike many currencies, ISK has no subunit — there are no aurar in modern circulation. Pass 1000 to charge 1,000 kr, not 0.01 kr.
1

Create your merchant account

Go to dashboard.borga.is and sign up. During onboarding you will need:
  • Your company kennitala (Icelandic company registration number)
  • A valid business email address
  • Acceptance of Borga’s terms of service
Once onboarding is complete your merchant account is created and you can access the dashboard.
2

Get your API keys

In the dashboard, navigate to Settings → API Keys and create a new key pair:
  • Secret key (sk_test_…) — used for server-side API calls. Keep this private.
  • Publishable key (pk_test_…) — optionally used for browser-side embedded checkout flows.
You will also need your Merchant ID (mer_…), visible on the API Keys page. Include it as the X-Merchant-Id header on every request.
Never share your secret key or commit it to source control. Treat it like a password.
3

Create a test payment

Send a POST request to /v1/payments with your secret key and merchant ID. The request body requires an amount (in whole ISK), a currency, and a description.
curl --request POST \
  --url https://api.borga.is/v1/payments \
  --header "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  --header "X-Merchant-Id: mer_YOUR_MERCHANT_ID" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 1000,
    "currency": "ISK",
    "description": "Test payment"
  }'
A successful response returns a payment object:
{
  "id": "pay_01HXYZ1234ABCDEF",
  "status": "pending",
  "amount": 1000,
  "currency": "ISK",
  "description": "Test payment",
  "created_at": "2026-04-29T10:00:00Z"
}
Save the id — you will use it to retrieve the payment in the next step.
4

Retrieve the payment

Fetch the payment you just created to confirm the details and current status:
curl
curl --request GET \
  --url https://api.borga.is/v1/payments/pay_01HXYZ1234ABCDEF \
  --header "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  --header "X-Merchant-Id: mer_YOUR_MERCHANT_ID"
The response mirrors the payment object from the previous step. Check the status field — a payment that has not yet been completed will show pending.
5

Go live

When you are ready to accept real ISK payments:
  1. Apply for live mode from the dashboard under Settings → Go Live.
  2. Complete any additional compliance steps Borga requires.
  3. Generate a live secret key (sk_live_…) and update your server environment variables.
Live keys process real charges immediately, so verify your integration thoroughly in test mode first.

​
Next steps

Authentication

Learn about key types, the Merchant ID header, idempotency, and how to handle auth errors.

Accept a payment

Full guide to handling the complete payment lifecycle, including confirmation and refunds.

Hosted checkout

Use payment sessions to redirect customers to a Borga-hosted checkout page.

API reference

Full reference for every endpoint available in the Borga API.