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.

A payment in Borga represents a single charge attempt against a customer. You create a payment by providing an amount and currency — Borga handles the rest, moving the charge through a predictable lifecycle and producing a legally compliant invoice automatically. Whether you accept cards, Apple Pay, Google Pay, or bank invoices (krafa), all payment types flow through the same object model.

​
The payment object

When you create or retrieve a payment, the response includes the following key fields:
FieldTypeDescription
idstringUnique identifier for the payment, e.g. pay_01HXYZ…
amountnumberCharge amount in the smallest currency unit (ISK, integer)
currencystringISO 4217 currency code, e.g. ISK
statusstringCurrent lifecycle status (see below)
customerstringID of the customer being charged, if provided
descriptionstringHuman-readable description shown on the invoice
external_referencestringYour own order or reference ID for reconciliation
metadataobjectUp to 50 key-value pairs for your own structured data
Use external_reference to store your internal order ID. It is indexed, making it easy to look up a Borga payment from your own system.

​
Payment lifecycle

Every payment moves through a fixed sequence of statuses. Understand which status you are in before taking further action.
StatusMeaning
createdThe payment record exists but no charge attempt has started.
processingThe charge is in flight — do not retry or cancel at this point.
succeededThe charge completed. An invoice has been issued.
failedThe charge was declined or encountered an error. Safe to retry.
refundedThe full amount was refunded.
partially_refundedOne or more partial refunds have been issued against this payment.
Never update your order status based solely on a succeeded response from a direct API call. Use webhooks to receive status updates asynchronously and avoid race conditions.

​
Payment methods supported

Borga supports the following payment methods. All methods settle in ISK.

Cards

Visa and Mastercard. Supports 3D Secure where the card issuer requires it.

Apple Pay

Available in Safari on Apple devices. Enabled automatically in payment sessions.

Google Pay

Available in Chrome and on Android devices. Enabled automatically in payment sessions.

Bank invoice (krafa)

ISK-only. Borga sends a krafa directly to the customer’s netbanki. The customer approves payment from their online bank.
Bank invoice (krafa) is only available for ISK payments. It cannot be used for foreign-currency transactions.

​
Payment sessions

For most checkout flows you should create a payment session rather than a raw payment. A session hosts the payment form, handles 3D Secure redirects, and manages the checkout UI for you. You create a session with POST /v1/payment_sessions. The two session modes are:
Borga renders the full checkout page at a Borga-hosted URL. Redirect your customer to that URL, and Borga redirects them back to your return_url or cancel_url when the session ends.Best for: teams that want a complete checkout UI with minimal integration effort.
{
  "mode": "hosted",
  "amount": 12900,
  "currency": "ISK",
  "return_url": "https://yoursite.is/order/complete",
  "cancel_url": "https://yoursite.is/cart"
}

​
Session fields reference

FieldRequiredDescription
paymentNoAttach to an existing payment ID instead of creating a new one.
amountNoOverride amount when not using an existing payment.
currencyNoDefaults to ISK.
customer_emailNoPre-fill the email field in the checkout form.
external_referenceNoYour own reference ID, carried through to the payment.
metadataNoKey-value pairs passed to the resulting payment.
localeNoLocale for the checkout UI, e.g. is or en.
FieldRequiredDescription
return_urlYesURL Borga redirects to after a successful or completed session.
cancel_urlNoURL Borga redirects to if the customer cancels.
modeNo"hosted" (default) or "embedded".
originNoRequired for embedded mode — your site’s origin for iframe security.
enabled_methodsNoRestrict which payment methods appear, e.g. ["card", "krafa"].
save_payment_methodNoIf true, the card used is saved to the customer for future charges.
customerNoCustomer ID to associate the session and any saved method with.

​
Refunds

Issue a full or partial refund against a succeeded payment with POST /v1/refunds. 
curl --request POST \
  --url https://api.borga.is/v1/refunds \
  --header "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  --header "X-Merchant-Id: mer_YOUR_MERCHANT_ID" \
  --header "Content-Type: application/json" \
  --data '{
    "payment": "pay_01HXYZ",
    "reason": "customer_request"
  }'
The amount field is optional. Omit it to refund the full remaining amount. The reason field is a free-form string — use it for internal notes or to pass a reason code to your accounting integration. When a refund is issued, Borga automatically generates a credit note linked to the original invoice. See Invoicing for details.

​
Saved payment methods

When you set save_payment_method: true on a payment session and provide a customer ID, Borga saves the card used to that customer record for future charges. You can then:
  • List saved methods with GET /v1/payment_methods?customer=cus_…
  • Retrieve a specific method with GET /v1/payment_methods/{id}
  • Set a method as the customer’s default with POST /v1/payment_methods/{id}/set_default
  • Remove a method with DELETE /v1/payment_methods/{id}
The default payment method is used automatically when charging the customer via a subscription with collection_method: charge_automatically.