Ecom API

Use the Ecom API for e-commerce, web, and native mobile integrations.

Detailed Documentation: https://api.blikk.tech/ecom/docs

Service Purpose

Payment initiation, Strong Customer Authentication (SCA) redirection, webhook callbacks and status polling for Blikk ECom payments.

Contact

Questions or API key requests: hello@blikk.tech

Integration Experiences

There are two ways to integrate Blikk ECom payments. Choose based on where your users initiate the payment.

Experience	Use when
Simple	Web apps, desktop, mobile apps or any mobile browser
In-App	Native iOS or Android app
Direct Debtor	Bespoke web apps, desktop apps, mobile apps (iOS/Android) or any mobile/desktop browser

[!IMPORTANT] The In-App experience requires a native mobile app. Mobile browsers (iOS Safari and most Android browsers) block programmatic deep-links to banking apps — the user must tap a link themselves. Use Simple for all browser-based integrations.

Simple

The merchant redirects the user to Blikk's hosted Payment Page to complete SCA. Works on all platforms.

1. Create payment — POST /ecom/v3/payments or POST /v3/payments/direct-debtor. Optionally supply debtor identity (debtorExternalId / debtorPhoneNo). If omitted, the user enters their details on the Payment Page.
2. Redirect user to the scaRedirectUrl from the response. Open in the system browser.
3. User completes SCA on Blikk's Payment Page (identity entry, then bank authentication).
4. User returns to your partnerRedirectUrl (if supplied).
5. Confirm status via webhook or GET /ecom/v3/payments/:id.

In-App

The merchant app polls for an SCA redirect URL and redirects the user from within the native app, typically into their banking app, or to Blikk onboarding when required.

1. Create payment — POST /ecom/v3/payments or POST /v3/payments/direct-debtor with debtorExternalId and/or debtorPhoneNo.
2. Poll GET /ecom/v3/payments/:id for scaRedirectUrl or a terminal status.
3. Redirect the user to scaRedirectUrl from within your native app, only if it is non-empty.
4. User completes SCA in their banking app.
5. User returns to your app via app switching or your partnerRedirectUrl.
6. Confirm status via webhook or GET /ecom/v3/payments/:id.

[!IMPORTANT] Always redirect when scaRedirectUrl is non-empty, regardless of payment status. If the user does not yet have a Blikk account, has no registered bank account, or their bank account consent has expired, scaRedirectUrl will point to Blikk's onboarding page rather than a banking app. The redirect behaviour is the same in all cases — your app does not need to differentiate.

[!NOTE] Some banks (e.g. ISB / Íslandsbanki) use back-channel SCA — the user is notified via a push notification in their banking app rather than through a redirect URL. In this case, scaRedirectUrl may remain empty even while the payment is being processed. Only redirect the user if scaRedirectUrl is non-empty. Regardless of bank, continue polling GET /ecom/v3/payments/:id or rely on the webhook callback to confirm the terminal status of the payment (SUCCESS, ERROR, REJECTED, or CANCELLED). The user will complete SCA via their banking app push notification without any action needed from your app.

Direct Debtor

Direct Debtor creates and initializes a payment for a specific debtor account (POST /v3/payments/direct-debtor). If the debtor is not onboarded then we create a non-onboarded user. This allows the creditor to create a payment without having the debtor go through the onboarding process first.

Required request fields

• debtorBban — debtor account BBAN (dashes/spaces are normalized by the API)
• debtorExternalId — debtor SSN/kennitala
• debtorName — debtor full name
• amount — integer in smallest currency unit

Optional request fields

• debtorPhoneNo — if sent without +354, the API prepends +354
• debtorCorpExternalId — corporate PSU identifier
• currency — defaults to ISK when omitted
• partnerRedirectUrl, callbackUrl, items, expiresAt, source, sourceReferenceId, creditor
• requestedExecutionAt (hidden/internal field; format YYYY-MM-DD)

1. Create payment with the fields above.
2. Receive response with id, status, scaRedirectUrl, message, and partnerRedirectUrl.
3. Redirect to scaRedirectUrl when non-empty for SCA/onboarding.
4. Confirm terminal status via webhook and/or GET /ecom/v3/payments/:id.

[!IMPORTANT] Direct Debtor is enabled per sales channel. If disabled, the endpoint returns 403 Forbidden.

[!NOTE] The handler validates/creates a shadow user from the debtor fields and validates/adds the debtor BBAN account before payment initialization.

Step-by-Step

1. Create Payment

POST /ecom/v3/payments or POST /v3/payments/direct-debtor

[!NOTE] Corporate payments require debtor phone, debtor SSN, and corporate ID (fyrirtækjakennitala).

[!TIP] Idempotency via sourceReferenceId: If you supply a sourceReferenceId on the create request, the API checks whether a non-terminal payment with the same sourceReferenceId and amount already exists for your merchant account. If one is found, it is returned instead of creating a new payment. This prevents duplicate payments on retries — set it to your internal order or transaction ID.

[!IMPORTANT] Open scaRedirectUrl in the system browser (preferred) rather than an embedded WebView. Desktop users will see a QR code to scan with their mobile device.

[!WARNING] If using a WebView, ensure deep/universal link handling is enabled so banking app handoff works.

2. Redirect User to SCA

2.1 New User (Light Onboarding)

[!IMPORTANT] This step does not apply to Direct Debtor payments. Skip to step 2.2 if you are using Direct Debtor.

If the debtor is not yet a Blikk user, scaRedirectUrl presents a 1-step onboarding form (phone, SSN, BBAN in format 0101-26-123456). After completion, the flow proceeds directly to bank authentication.

2.2 Authentication (SCA)

User reaches their banking app (or scans desktop QR) and authorizes the payment.

3. Return to Merchant

After bank authentication, the user is redirected to partnerRedirectUrl (if supplied). Otherwise they can manually return (for example via app switching from a bank app to a browser or merchant app).

[!TIP] You may append query parameters (for example order identifiers) to partnerRedirectUrl.

4. Retrieve / Confirm Status

Use either:

• Webhook (from callbackUrl) + verify via GET
• Poll GET /ecom/v3/payments/:id until a terminal status

[!CAUTION] Webhooks are currently unsigned. Always verify by calling GET /ecom/v3/payments/:id before finalizing business logic.

Status Lifecycle

Status	Description	Keep Polling
DRAFT	Created; not yet initiated by debtor	✅
PENDING	Initiated; awaiting bank processing	✅
SCA_REQUIRED	Bank indicates SCA is required	✅
SCA_COMPLETE	User has completed SCA; settlement pending	✅
ERROR	Irrecoverable error; payment invalid	❌
CANCELLED	Cancelled by user or merchant	❌
REJECTED	Rejected by user or bank	❌
SUCCESS	Completed; funds transferred	❌

Terminal statuses: ERROR, CANCELLED, REJECTED, SUCCESS.

API Reference (Environments)

ENV	Docs URL	Demo API Key
Stage	https://stage.blikk.tech/ecom/docs	HC34QUE3RM ¹
Production	https://api.blikk.tech/ecom/docs	—

¹ This is a shared, rotatable staging key for quick evaluation only. For sustained development, request a dedicated Stage key via hello@blikk.tech.

Getting Started

1. Obtain API key (email support)
2. Use HTTPS endpoints
3. Include API key header in every request (example below)
4. Redirect users using returned scaRedirectUrl
5. Verify payment result via GET or webhook+GET

[!IMPORTANT] Stage uses bank sandbox systems: no real funds move.

Authentication

Typical HTTP header

Api-Key: YOUR_API_KEY

Demo Users and Simulation (Stage Environment)

Use these debtor phone numbers to create test payments:

+3540002329 or 0002329 (Landsbankinn)
+3540002328 or 0002328 (Arion)

Set amount to force an immediate status (after creation):

Amount	Simulated Status
121	ERROR
131	CANCELLED
141	REJECTED
151	SUCCESS

GET /ecom/v3/payments/:id returns the simulated status right after creation.

Items (Line Items)

Add items array in create request to persist purchased item metadata for user visibility inside the Blikk app. Strongly encouraged for transparency and reconciliation.

Example item object (fields illustrative; use canonical spec names):

{
  "name": "Subscription Plan A",
  "quantity": 1,
  "unitPrice": 9900,
  "currency": "ISK",
  "reference": "SKU-PLAN-A"
}

Webhooks (Callbacks)

Provide callbackUrl in create request to receive payment lifecycle updates.

Best practice on receipt:

1. Parse JSON request body
2. Extract id, status, source and sourceReferenceId alongside other payment fields (see callback request schema in the endpoint docs)
3. Act on business logic using id and status
4. Optionally verify status via GET /ecom/v3/payments/:id
5. Respond with HTTP 200

Retries: Implement idempotent handling (webhooks may be delivered more than once). Respond with HTTP 200 OK to acknowledge.

Displaying Payment Status (User-Facing Icelandic)

Status	Recommended Translation
DRAFT	Beðið eftir heimild…
PENDING	Beðið eftir heimild…
SCA_REQUIRED	Beðið eftir heimild…
SCA_COMPLETE	Beðið eftir heimild…
SUCCESS	Greiðsla tókst
ERROR	Villa við greiðslu
REJECTED	Greiðslu hafnað
CANCELLED	Hætt var við greiðslu

Group non-terminal waiting statuses with the same message to reduce flicker.

Error Cases

HTTP Status	Cause
400 Bad Request	Missing/invalid externalId or amount; requested amount exceeds remaining refundable balance
401 Unauthorized	Missing or invalid API-Key
403 Forbidden	externalId does not have access to the creditor bank account
404 Not Found	Original payment not found or does not belong to your merchant account
500 Internal Server Error	Upstream error during payment creation or initialization

Implementation Tips

• Treat payment id as the canonical key for reconciliation
• We recommend always verifying terminal state server-side before granting value when receiving a webhook callback (fetch payment status via GET)
• Use exponential backoff if polling (for example 1s → 2s → 4s, cap around 15s)
• Log full webhook body before processing
• Avoid embedding scaRedirectUrl in iframes / restricted WebViews
• Set source and sourceReferenceId fields when creating payments to link to your internal order or sales IDs

Refunds

Use POST /v4/payments/refund/{id} to refund a completed payment. Partial refunds are supported — you can refund any amount up to the remaining refundable amount of the original payment.

[!IMPORTANT] Refunds require a SUCCESS status on the original payment. The request is rejected if the requested amount exceeds the remaining refundable amount.

Endpoint

POST /v4/payments/refund/{id}

Parameter	Location	Description
id	Path	Original payment ID to refund
externalId	Body	Kennitala (SSN) of the person authorizing the refund from the merchant's account. Must have access to the original creditor (merchant) bank account.
amount	Body	Refund amount in ISK (integer, smallest currency unit). Must be positive and ≤ remaining refundable amount.

Authentication: API-Key header required.

Refund Flow

1. Merchant calls POST /v4/payments/refund/{id} with the original payment ID, the authorizing person's kennitala (externalId), and the refund amount.
2. Ecom fetches the original payment and validates ownership against your API key.
3. Ecom checks that the requested amount does not exceed the remaining refundable balance (originalPayment.Amount - sum(previousRefunds)).
4. A refund payment is created with debtor/creditor accounts reversed from the original: the merchant account is debited and the customer account is credited.
5. The payment is initialized via bank A2A. The response includes a scaRedirectUrl for the merchant-side person to authorize the debit in their banking app.
6. After SCA, the refund settles and the original payment's refunded amount is updated in paymentsms.

[!NOTE] The scaRedirectUrl in the refund response should be presented to the merchant-side authorizer (the person whose kennitala was provided).

Error Cases

HTTP Status	Cause
400 Bad Request	Missing/invalid externalId or amount; requested amount exceeds remaining refundable balance
401 Unauthorized	Missing or invalid API-Key
403 Forbidden	externalId does not have access to the creditor bank account
404 Not Found	Original payment not found or does not belong to your merchant account
500 Internal Server Error	Upstream error during payment creation or initialization

Security Notes

Keep credentials server-side only. Do not embed API keys in frontend code, mobile binaries, logs, screenshots, or support tickets.

Glossary

Term	Meaning
SCA	Strong Customer Authentication (bank mandated user auth)
Debtor	Paying user (payer)
Creditor	Receiving merchant (payee)
Partner Redirect URL	URL to which user is redirected after SCA completion
Callback URL	Webhook target URL for payment status updates
BBAN	Domestic bank account number
Kennitala (SSN)	Icelandic national ID
Corporate ID	Icelandic company identifier (fyrirtækjakennitala)
Light Onboarding	A streamlined onboarding flow for new users that collects the minimum required identity/details before continuing to payment or account setup
Refund	A reverse payment that credits the original debtor (customer) from the original creditor (merchant) account
Anonymous Payment	Payment where the merchant creates a payment without providing debtor identity upfront (phone/SSN). Debtor provides their identity via Blikk's secure Payment Page

Support

Contact hello@blikk.tech for support.