Quickstart

This guide walks through the shortest path to a working payment: a hosted checkout session created from your server, paid with a test card, and confirmed by reading the payment back.

1. Create a merchant

   Sign in at dashboard.borga.is with your electronic ID (Kenni). Create a merchant: choose Company or Individual, enter the legal name and the matching kennitala. Nothing is verified at this point, and test mode is enabled immediately. Verification happens when you go live.

2. Create a test secret key

   Open Developers in the dashboard and create a secret key in test mode. Copy it right away: the full key is shown once and stored hashed after that.

   .env

   BORGA_SECRET_KEY=sk_test_…

   The key identifies your merchant, so no other identifier is needed on requests. Read more in Authentication.

3. Install the SDK (optional)

   Every endpoint is plain HTTPS and JSON, so curl or any HTTP client works. The Node SDK adds types, retries and idempotency keys.

   Terminalbash

   npm install @borga/node

4. Create a payment session

   A payment session is a checkout page for one amount. Create it from your server with the amount, a return_url for after payment and a cancel_url for the back button.

   Node.jscurl

   Node.jsts

   import { Borga } from "@borga/node";
   
   const borga = new Borga({ apiKey: process.env.BORGA_SECRET_KEY! });
   
   const session = await borga.paymentSessions.create({
     amount: 1990, // whole krónur: 1.990 kr.
     currency: "ISK",
     return_url: "https://example.is/order/complete",
     cancel_url: "https://example.is/cart",
     external_reference: "order_1042",
   });
   
   console.log(session.url);
   // https://checkout.borga.is/ps_…

   The response includes the hosted checkout url and the id of the underlying payment:

   Responsejson

   {
     "id": "ps_3kD9mQ2vXb7LpR4tYw8Nz1Ha",
     "payment": "pay_7Hs2Kq9LmW4xZc1Vb8Ny3Rt6",
     "url": "https://checkout.borga.is/ps_3kD9mQ2vXb7LpR4tYw8Nz1Ha",
     "return_url": "https://example.is/order/complete",
     "cancel_url": "https://example.is/cart",
     "expires_at": "2026-09-08T12:00:00.000Z",
     "status": "open",
     "enabled_methods": ["card", "apple_pay", "google_pay"],
     "mode": "hosted",
     "locale": "is",
     "customer_email": null,
     "customer_kennitala": null,
     "created_at": "2026-09-07T12:00:00.000Z",
     "client_secret": null
   }

5. Pay with a test card

   Open session.url in a browser. Test mode runs against the card processor's staging environment, which accepts these cards with any future expiry and CVC 737:

   Card	Number	3-D Secure
   Visa	4111 1111 4555 1142	no
   Visa	4917 6100 0000 0000	yes
   Mastercard	2222 4000 7000 0005	no
   Mastercard	5454 5454 5454 5454	yes

   After paying, Borga shows a confirmation and sends the browser to your return_url with ?session=ps_… appended. See Test mode for wallets and bank invoices.

6. Read the payment back

   Retrieve the payment to confirm its status. In production you would do this from a webhook rather than from the redirect; see Webhooks.

   Node.jscurl

   Node.jsts

   const payment = await borga.payments.retrieve("pay_7Hs2Kq9LmW4xZc1Vb8Ny3Rt6");
   
   console.log(payment.status); // "succeeded"
   console.log(payment.card_brand, payment.card_last4); // "visa" "1142"

   A status of succeeded means the card was charged. created means the payer has not finished yet, and failed means the card was declined.

Next steps