> ## 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.

# Get started with Borga

> Create your merchant account, get your test API keys, and make your first payment request against the Borga API — all in a few minutes.

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.

<Note>
  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.
</Note>

<Steps>
  <Step title="Create your merchant account">
    Go to [dashboard.borga.is](https://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.
  </Step>

  <Step title="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.

    <Warning>
      Never share your secret key or commit it to source control. Treat it like a password.
    </Warning>
  </Step>

  <Step title="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`.

    <CodeGroup>
      ```bash curl theme={null}
      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"
        }'
      ```

      ```javascript Node.js theme={null}
      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);
      ```
    </CodeGroup>

    A successful response returns a payment object:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="Retrieve the payment">
    Fetch the payment you just created to confirm the details and current status:

    ```bash curl theme={null}
    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`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Learn about key types, the Merchant ID header, idempotency, and how to handle auth errors.
  </Card>

  <Card title="Accept a payment" icon="credit-card" href="/guides/accept-payment">
    Full guide to handling the complete payment lifecycle, including confirmation and refunds.
  </Card>

  <Card title="Hosted checkout" icon="window-maximize" href="/guides/hosted-checkout">
    Use payment sessions to redirect customers to a Borga-hosted checkout page.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/overview">
    Full reference for every endpoint available in the Borga API.
  </Card>
</CardGroup>