Payment Sessions API — hosted and embedded checkout

A payment session represents a checkout interaction. Use mode: "hosted" to redirect your customer to a Borga-hosted checkout page, or mode: "embedded" to render checkout directly in your own page using the client_secret. Sessions expire after a short window. Retrieve a session to check its status and whether the underlying payment succeeded.

Create a payment session

POST /v1/payment_sessions Creates a new payment session. The required parameters vary by mode — see the examples below.

Request parameters

string

Checkout mode. Use "hosted" to redirect the customer to a Borga-hosted page, or "embedded" to render checkout within your own page. Defaults to "hosted".

string

ID of an existing payment to attach this session to. If omitted, a new payment is created using the amount and currency fields.

number

Amount for the payment in whole ISK kronur. Required when payment is not provided.

string

Three-letter ISO 4217 currency code. Defaults to ISK.

string

ID of an existing customer to associate with the session.

string

Customer email address. Pre-fills the email field in hosted checkout.

string

URL the customer is redirected to after completing or attempting checkout. Required for mode: "hosted". Borga appends a session_id query parameter so you can retrieve the session on load.

string

URL the customer is redirected to if they cancel checkout. Only used in mode: "hosted".

string

The origin of the page embedding checkout (e.g. https://example.com). Required for mode: "embedded". Borga uses this for postMessage communication.

string[]

Array of payment method types to enable (e.g. ["card", "apple_pay"]). When omitted, all methods available to your merchant account are enabled.

string

BCP 47 language tag controlling the checkout UI language (e.g. "is", "en"). Defaults to the customer’s browser locale.

boolean

When true, prompts the customer to save their payment method for future use.

string

Your own reference string for this session — an order ID, invoice number, or similar.

object

Set of key-value pairs to attach to the session. Values must be strings.

Hosted
Embedded

curl --request POST \
  --url https://api.borga.is/v1/payment_sessions \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "mode": "hosted",
    "amount": 9900,
    "currency": "ISK",
    "customer_email": "jondoe@example.com",
    "return_url": "https://example.com/checkout/complete",
    "cancel_url": "https://example.com/checkout/cancel",
    "external_reference": "order_2077"
  }'

{
  "id": "pses_01hxa1r5nvpq8kd2wfm3cjt9yb",
  "mode": "hosted",
  "url": "https://checkout.borga.is/s/pses_01hxa1r5nvpq8kd2wfm3cjt9yb",
  "client_secret": null,
  "status": "open",
  "payment": "pay_01hxa1r5mzgq8kd2wfm3abcxyz",
  "expires_at": "2026-04-29T11:15:00Z"
}

Redirect your customer to the url returned in the response. After checkout, Borga redirects them to your return_url with ?session_id=pses_... appended. Retrieve the session on that page to confirm the outcome.

curl --request POST \
  --url https://api.borga.is/v1/payment_sessions \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "mode": "embedded",
    "amount": 9900,
    "currency": "ISK",
    "origin": "https://example.com",
    "customer_email": "jondoe@example.com",
    "external_reference": "order_2077"
  }'

{
  "id": "pses_01hxa1r5nvpq8kd2wfm3cjt9yb",
  "mode": "embedded",
  "url": null,
  "client_secret": "pses_secret_01hxa1r5nvpq8kd2wfm3cjt9yb_abc123",
  "status": "open",
  "payment": "pay_01hxa1r5mzgq8kd2wfm3abcxyz",
  "expires_at": "2026-04-29T11:15:00Z"
}

Pass the client_secret to your front-end to initialise the Borga.js embedded checkout element. The client_secret is sensitive — do not log it or expose it beyond the client session.

Response fields

string

required

Unique identifier for the session.

string

required

Checkout mode: "hosted" or "embedded".

string

The hosted checkout URL to redirect your customer to. Present when mode is "hosted", null otherwise.

string

Secret used to initialise the embedded checkout element. Present when mode is "embedded", null otherwise.

string

required

Session status. One of open, complete, expired.

string

required

ID of the payment associated with this session.

string

required

ISO 8601 timestamp after which the session can no longer be used to complete checkout.

Retrieve a payment session

GET /v1/payment_sessions/{id} Retrieves an existing payment session. Call this endpoint from your server after the customer returns to your return_url to confirm the payment outcome before fulfilling the order.

Path parameters

string

required

The ID of the payment session to retrieve.

curl --request GET \
  --url https://api.borga.is/v1/payment_sessions/pses_01hxa1r5nvpq8kd2wfm3cjt9yb \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"

Response fields

string

required

Unique session identifier.

string

required

Checkout mode: "hosted" or "embedded".

string

Hosted checkout URL. null for embedded sessions.

string

Embedded checkout secret. null for hosted sessions.

string

required

Session status. One of open, complete, expired.

string

required

ID of the associated payment.

string

required

ISO 8601 expiry timestamp.

{
  "id": "pses_01hxa1r5nvpq8kd2wfm3cjt9yb",
  "mode": "hosted",
  "url": "https://checkout.borga.is/s/pses_01hxa1r5nvpq8kd2wfm3cjt9yb",
  "client_secret": null,
  "status": "complete",
  "payment": "pay_01hxa1r5mzgq8kd2wfm3abcxyz",
  "expires_at": "2026-04-29T11:15:00Z"
}

Always retrieve the session from your server and check that status is "complete" and the associated payment’s status is "succeeded" before fulfilling an order. Do not rely solely on the redirect URL to confirm payment.

Overview

Payments

Subscriptions

Billing

Configuration

Payment Sessions API — hosted and embedded checkout

Create a payment session

Request parameters

Response fields

Retrieve a payment session

Path parameters

Response fields

​Create a payment session

​Request parameters

​Response fields

​Retrieve a payment session

​Path parameters

​Response fields

Create a payment session

Request parameters

Response fields

Retrieve a payment session

Path parameters

Response fields