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.

Borga has two fully independent environments: test mode and live mode. In test mode, you can create payments, subscriptions, and invoices freely without making real ISK charges or affecting any real customer data. Test mode is the right place to build your integration, run automated tests, and validate your checkout flows before going live.

​
Test API keys

Every Borga account has separate API keys for each environment. Test keys are prefixed sk_test_… (secret) and pk_test_… (publishable). You can find and generate your test keys in the dashboard under Settings → API Keys.
Key prefixUse
sk_test_…Server-side requests in test mode.
pk_test_…Browser-side embedded checkout sessions in test mode.
sk_live_…Server-side requests in live mode.
pk_live_…Browser-side embedded checkout sessions in live mode.
Pass your test secret key in the Authorization header the same way you would a live key:
curl
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": 5000,
    "currency": "ISK",
    "description": "Test charge"
  }'
Never use a live key (sk_live_…) in a development or staging environment. A misconfigured test will result in real ISK charges to real customers.

​
Test card numbers

Use the following card numbers in payment sessions and checkout forms to simulate different outcomes. Use any future expiry date and any 3-digit CVC.
Card numberOutcome
4242 4242 4242 4242Payment succeeds.
4000 0000 0000 0002Payment is declined.
For flows that require 3D Secure authentication, use 4000 0025 0000 3155. The checkout form will present a mock authentication screen that you can pass or fail to test both outcomes.
Use 4000 0000 0000 9995 to simulate a card declined due to insufficient funds. This is useful for testing your retry and dunning logic.
Test card numbers only work with test-mode API keys. Using them with a live key will result in a declined transaction, not a simulated one.

​
Data isolation

Test mode and live mode maintain completely separate data sets. Test payments, customers, subscriptions, and invoices never appear in the live dashboard, and vice versa. The only thing shared between the two environments is your account settings and merchant profile.
1

Build with test keys

Use sk_test_… during development. All objects you create are scoped to test mode.
2

Switch to live keys

When you are ready to accept real payments, replace sk_test_… with sk_live_… in your server configuration. No code changes are needed.
3

Verify live mode data

Live payments appear in the live dashboard. Test data from development is not migrated and does not appear.
Use the Idempotency-Key header during testing when you need to make repeated requests for the same logical operation. Borga deduplicates on the key, so retrying a failed test request with the same key returns the original response rather than creating a duplicate object. See Authentication for details.

​
Webhook endpoints are mode-specific

Webhooks you register in the dashboard are scoped to a single environment. A webhook endpoint configured for test mode only receives events from test-mode operations, and a live-mode endpoint only receives live events.
If you are testing webhooks locally, register a separate test-mode endpoint (for example, using a tunnel tool) in the dashboard under Developers → Webhooks → Test mode. Your live-mode endpoints are unaffected.

​
Applying for live mode

When you are ready to go live, submit your company kennitala from the Borga dashboard:
1

Complete your merchant profile

Navigate to Settings → Business details and fill in your company name, kennitala, and bank account information.
2

Submit for review

Click Apply for live access. Borga verifies your kennitala against the Icelandic company registry.
3

Receive live keys

Once approved, your sk_live_… and pk_live_… keys are activated and visible under Settings → API Keys.
Review typically completes within one business day. You will receive an email confirmation when your account is approved for live mode.