Get started with Borga

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.

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.

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.

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"
  }'

const response = await fetch('https://api.borga.is/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_YOUR_SECRET_KEY',
    'X-Merchant-Id': 'mer_YOUR_MERCHANT_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 1000,
    currency: 'ISK',
    description: 'Test payment',
  }),
});

const payment = await response.json();
console.log(payment.id);

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.

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.

Go live

When you are ready to accept real ISK payments:

Apply for live mode from the dashboard under Settings → Go Live.
Complete any additional compliance steps Borga requires.
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.

Get Started

Core Concepts

Guides

Get started with Borga

Next steps

Authentication

Accept a payment

Hosted checkout

API reference

​Next steps

Authentication

Accept a payment

Hosted checkout

API reference

Next steps