Checkout Link

// server.js
const express = require('express');
const app = express();
app.use(express.json());

const KWIK_API = 'https://api.kwik.co.za/v2';

// Keep credentials server-side only
const KWIK_API_KEY = process.env.KWIK_API_KEY;
const KWIK_API_SECRET = process.env.KWIK_API_SECRET;

const basicAuth = Buffer
  .from(`${KWIK_API_KEY}:${KWIK_API_SECRET}`)
  .toString('base64');

const headers = {
  'Content-Type': 'application/json',
  'Authorization': `Basic ${basicAuth}`
};

// TODO: Add your own authentication

// 1. Create a checkout session for the app
app.post('/api/checkout', async (req, res) => {
  const response = await fetch(`${KWIK_API}/checkout/link`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      type: 'CHOOSE_WHAT_TO_PAY',
      item: {
        title: 'My product name',
        amount: '1200.00' // in production, derive from your own order data
      },
      customization: {
        type: 'EMBED', // required for in-app payments — sends events instead of redirecting
        embed_channel: 'APP', // required to specify how events are returned. APP = Mobile apps, Web = Websites
        is_display_cancel_button: true
      }
    })
  });

  const { status, result } = await response.json();
  if (!status) return res.status(502).json({ error: 'Could not create checkout' });

  // The app only needs the URL to load
  res.json({ checkoutUrl: result.link_url });
});

// 2. Verify a transaction after the app receives payment.successful
app.get('/api/transactions/:transactionPublicId/verify', async (req, res) => {
  const { transactionPublicId } = req.params;

  const response = await fetch(
    `${KWIK_API}/transactions/record/${transactionPublicId}`,
    { headers }
  );

  const data = await response.json();
  const paid = data.status === true
    && data.transaction?.transaction_status === 'PAID';

  res.json({ paid });
});

app.listen(3000);

import React, { useEffect, useState } from 'react';
import { ActivityIndicator } from 'react-native';
import { WebView } from 'react-native-webview';

const BACKEND = 'https://your-server.example';
const KWIK_SCHEME = 'kwikpay://';

export function KwikCheckout({ onComplete, onCancel }) {
  const [checkoutUrl, setCheckoutUrl] = useState(null);

  // Ask your backend to create the checkout session
  useEffect(() => {
    (async () => {
      const res = await fetch(`${BACKEND}/api/checkout`, { method: 'POST' });
      const { checkoutUrl } = await res.json();
      setCheckoutUrl(checkoutUrl);
    })();
  }, []);

  const verifyTransaction = async (transactionPublicId) => {
    const res = await fetch(
      `${BACKEND}/api/transactions/${transactionPublicId}/verify`
    );
    const { paid } = await res.json();
    return paid;
  };

  const handleKwikEvent = async (evt) => {
    // evt example on success:
    // { source: 'kwik-payments', event: 'payment.successful',
    //   sessionId: 'ses_...', transactionPublicId: 'tra_...',
    //   customerId: 'cus_...', status: 'PAID' }
    switch (evt.event) {
      case 'payment.loaded':
        break; // checkout ready
      case 'payment.pending':
        break; // e.g. 3DS in progress — keep the WebView open
      case 'payment.successful': {
        const paid = await verifyTransaction(evt.transactionPublicId);
        if (paid) {
          onComplete(evt.transactionPublicId);
        }
        // If not yet PAID (e.g. still settling), poll again or
        // rely on your webhook before fulfilling.
        break;
      }
      case 'payment.failed':
        break; // checkout shows its own retry UI — keep it open
      case 'payment.cancelled':
      case 'payment.closed':
        onCancel();
        break;
    }
  };

  if (!checkoutUrl) return <ActivityIndicator />;

  return (
    <WebView
      source={{ uri: checkoutUrl }}
      applicationNameForUserAgent="KwikPay/2.0"
      enableApplePay={true}
      thirdPartyCookiesEnabled={true}
      onShouldStartLoadWithRequest={(request) => {
        if (request.url.startsWith(KWIK_SCHEME)) {
          const qs = request.url.split('?')[1] ?? '';
          handleKwikEvent(Object.fromEntries(new URLSearchParams(qs)));
          return false; // cancel — the checkout page stays loaded
        }
        return true; // allow 3DS, Ozow, and other payment redirects
      }}
    />
  );
}

//dependencies:
//  flutter_inappwebview: ^6.0.0
//  http: ^1.2.0
import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:flutter_inappwebview/flutter_inappwebview.dart';
import 'package:http/http.dart' as http;

const backend = 'https://your-server.example';
const kwikScheme = 'kwikpay';

class KwikCheckout extends StatefulWidget {
  final void Function(String transactionPublicId) onComplete;
  final VoidCallback onCancel;

  const KwikCheckout({
    super.key,
    required this.onComplete,
    required this.onCancel,
  });

  @override
  State<KwikCheckout> createState() => _KwikCheckoutState();
}

class _KwikCheckoutState extends State<KwikCheckout> {
  String? checkoutUrl;

  @override
  void initState() {
    super.initState();
    _createCheckout();
  }

  // Ask your backend to create the checkout session
  Future<void> _createCheckout() async {
    final res = await http.post(Uri.parse('$backend/api/checkout'));
    final body = jsonDecode(res.body) as Map<String, dynamic>;
    setState(() => checkoutUrl = body['checkoutUrl'] as String);
  }

  Future<bool> _verifyTransaction(String transactionPublicId) async {
    final res = await http.get(
      Uri.parse('$backend/api/transactions/$transactionPublicId/verify'),
    );
    final body = jsonDecode(res.body) as Map<String, dynamic>;
    return body['paid'] == true;
  }

  Future<void> _handleKwikEvent(Map<String, String> evt) async {
    // evt example on success:
    // { source: 'kwik-payments', event: 'payment.successful',
    //   sessionId: 'ses_...', transactionPublicId: 'tra_...',
    //   customerId: 'cus_...', status: 'PAID' }
    switch (evt['event']) {
      case 'payment.loaded':
        break; // checkout ready
      case 'payment.pending':
        break; // e.g. 3DS in progress — keep the WebView open
      case 'payment.successful':
        final paid = await _verifyTransaction(evt['transactionPublicId']!);
        if (paid) {
          widget.onComplete(evt['transactionPublicId']!);
        }
        // If not yet PAID (e.g. still settling), poll again or
        // rely on your webhook before fulfilling.
        break;
      case 'payment.failed':
        break; // checkout shows its own retry UI — keep it open
      case 'payment.cancelled':
      case 'payment.closed':
        widget.onCancel();
        break;
    }
  }

  @override
  Widget build(BuildContext context) {
    if (checkoutUrl == null) {
      return const Center(child: CircularProgressIndicator());
    }

    return InAppWebView(
      initialUrlRequest: URLRequest(url: WebUri(checkoutUrl!)),
      initialSettings: InAppWebViewSettings(
        applicationNameForUserAgent: 'KwikPay/2.0',
        applePayAPIEnabled: true, // iOS
        thirdPartyCookiesEnabled: true, // Android
        useShouldOverrideUrlLoading: true, // required for the callback below
      ),
      shouldOverrideUrlLoading: (controller, navigationAction) async {
        final uri = navigationAction.request.url;
        if (uri != null && uri.scheme == kwikScheme) {
          _handleKwikEvent(uri.queryParameters);
          return NavigationActionPolicy.CANCEL; // checkout page stays loaded
        }
        return NavigationActionPolicy.ALLOW; // allow 3DS, Ozow, etc.
      },
    );
  }
}

import UIKit
import WebKit

final class KwikCheckoutViewController: UIViewController, WKNavigationDelegate {

    private let backend = URL(string: "https://your-server.example")!
    private let kwikScheme = "kwikpay"

    var onComplete: ((String) -> Void)?
    var onCancel: (() -> Void)?

    private var webView: WKWebView!

    override func viewDidLoad() {
        super.viewDidLoad()

        let config = WKWebViewConfiguration()
        config.applicationNameForUserAgent = "KwikPay/2.0"
        // Do NOT add WKUserScripts or script message handlers to this
        // configuration — script injection disables Apple Pay.

        webView = WKWebView(frame: view.bounds, configuration: config)
        webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        webView.navigationDelegate = self
        view.addSubview(webView)

        createCheckout()
    }

    // MARK: - Backend calls

    /// Ask your backend to create the checkout session
    private func createCheckout() {
        var request = URLRequest(url: backend.appendingPathComponent("api/checkout"))
        request.httpMethod = "POST"

        URLSession.shared.dataTask(with: request) { [weak self] data, _, _ in
            guard let data,
                  let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
                  let checkoutUrl = json["checkoutUrl"] as? String,
                  let url = URL(string: checkoutUrl) else { return }

            DispatchQueue.main.async {
                self?.webView.load(URLRequest(url: url))
            }
        }.resume()
    }

    private func verifyTransaction(_ transactionPublicId: String,
                                   completion: @escaping (Bool) -> Void) {
        let url = backend.appendingPathComponent(
            "api/transactions/\(transactionPublicId)/verify")

        URLSession.shared.dataTask(with: url) { data, _, _ in
            let paid = (try? JSONSerialization.jsonObject(with: data ?? Data())
                as? [String: Any])?["paid"] as? Bool ?? false
            DispatchQueue.main.async { completion(paid) }
        }.resume()
    }

    // MARK: - Event handling

    private func handleKwikEvent(_ evt: [String: String]) {
        // evt example on success:
        // { source: 'kwik-payments', event: 'payment.successful',
        //   sessionId: 'ses_...', transactionPublicId: 'tra_...',
        //   customerId: 'cus_...', status: 'PAID' }
        switch evt["event"] {
        case "payment.loaded":
            break // checkout ready
        case "payment.pending":
            break // e.g. 3DS in progress — keep the WebView open
        case "payment.successful":
            guard let transactionPublicId = evt["transactionPublicId"] else { return }
            verifyTransaction(transactionPublicId) { [weak self] paid in
                if paid {
                    self?.onComplete?(transactionPublicId)
                }
                // If not yet PAID (e.g. still settling), poll again or
                // rely on your webhook before fulfilling.
            }
        case "payment.failed":
            break // checkout shows its own retry UI — keep it open
        case "payment.cancelled", "payment.closed":
            onCancel?()
        default:
            break // ignore unknown events for forward compatibility
        }
    }

    // MARK: - WKNavigationDelegate

    func webView(_ webView: WKWebView,
                 decidePolicyFor navigationAction: WKNavigationAction,
                 decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {

        if let url = navigationAction.request.url, url.scheme == kwikScheme {
            let components = URLComponents(url: url, resolvingAgainstBaseURL: false)
            let evt = Dictionary(
                uniqueKeysWithValues: (components?.queryItems ?? [])
                    .map { ($0.name, $0.value ?? "") }
            )
            handleKwikEvent(evt)
            decisionHandler(.cancel) // checkout page stays loaded
            return
        }

        decisionHandler(.allow) // allow 3DS, Ozow, and other payment redirects
    }
}

//dependencies {
//    implementation("androidx.webkit:webkit:1.14.0")
//}
import android.annotation.SuppressLint
import android.net.Uri
import android.os.Bundle
import android.webkit.CookieManager
import android.webkit.WebResourceRequest
import android.webkit.WebView
import android.webkit.WebViewClient
import androidx.appcompat.app.AppCompatActivity
import androidx.lifecycle.lifecycleScope
import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
import okhttp3.OkHttpClient
import okhttp3.Request
import org.json.JSONObject

class KwikCheckoutActivity : AppCompatActivity() {

    private val backend = "https://your-server.example"
    private val kwikScheme = "kwikpay"
    private val http = OkHttpClient()

    private lateinit var webView: WebView

    @SuppressLint("SetJavaScriptEnabled")
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        webView = WebView(this)
        setContentView(webView)

        webView.settings.apply {
            javaScriptEnabled = true
            domStorageEnabled = true
            userAgentString = "$userAgentString KwikPay/2.0"
        }
        CookieManager.getInstance().setAcceptThirdPartyCookies(webView, true)

        // Enable the Payment Request API (Google Pay) when the
        // device WebView supports it — androidx.webkit 1.14.0+
        if (WebViewFeature.isFeatureSupported(WebViewFeature.PAYMENT_REQUEST)) {
            WebSettingsCompat.setPaymentRequestEnabled(webView.settings, true)
        }

        webView.webViewClient = object : WebViewClient() {
            override fun shouldOverrideUrlLoading(
                view: WebView,
                request: WebResourceRequest
            ): Boolean {
                val url = request.url
                if (url.scheme == kwikScheme) {
                    handleKwikEvent(url)
                    return true // cancel — the checkout page stays loaded
                }
                return false // allow 3DS, Ozow, and other payment redirects
            }
        }

        createCheckout()
    }

    // MARK: Backend calls

    /** Ask your backend to create the checkout session */
    private fun createCheckout() {
        lifecycleScope.launch {
            val checkoutUrl = withContext(Dispatchers.IO) {
                val req = Request.Builder()
                    .url("$backend/api/checkout")
                    .post(okhttp3.RequestBody.create(null, ByteArray(0)))
                    .build()
                http.newCall(req).execute().use { res ->
                    JSONObject(res.body!!.string()).getString("checkoutUrl")
                }
            }
            webView.loadUrl(checkoutUrl)
        }
    }

    private suspend fun verifyTransaction(transactionPublicId: String): Boolean =
        withContext(Dispatchers.IO) {
            val req = Request.Builder()
                .url("$backend/api/transactions/$transactionPublicId/verify")
                .build()
            http.newCall(req).execute().use { res ->
                JSONObject(res.body!!.string()).optBoolean("paid", false)
            }
        }

    // MARK: Event handling

    private fun handleKwikEvent(uri: Uri) {
        // Event example on success:
        // kwikpay://event?source=kwik-payments&event=payment.successful
        //   &sessionId=ses_...&transactionPublicId=tra_...
        //   &customerId=cus_...&status=PAID
        when (uri.getQueryParameter("event")) {
            "payment.loaded" -> Unit // checkout ready
            "payment.pending" -> Unit // e.g. 3DS in progress — keep the WebView open
            "payment.successful" -> {
                val transactionPublicId =
                    uri.getQueryParameter("transactionPublicId") ?: return
                lifecycleScope.launch {
                    val paid = verifyTransaction(transactionPublicId)
                    if (paid) {
                        onComplete(transactionPublicId)
                    }
                    // If not yet PAID (e.g. still settling), poll again or
                    // rely on your webhook before fulfilling.
                }
            }
            "payment.failed" -> Unit // checkout shows its own retry UI — keep it open
            "payment.cancelled", "payment.closed" -> onCancel()
            else -> Unit // ignore unknown events for forward compatibility
        }
    }

    private fun onComplete(transactionPublicId: String) {
        // Payment verified — dismiss the checkout and continue your flow
        finish()
    }

    private fun onCancel() {
        finish()
    }
}

<div id="checkout-container"></div>

<script>
  const KWIK_ORIGIN = 'https://pay.kwik.co.za';
  const BACKEND = 'https://your-server.example';

  async function startCheckout() {
    const { checkoutUrl } = await fetch(`${BACKEND}/api/checkout`, {
      method: 'POST',
    }).then((r) => r.json());

    const iframe = document.createElement('iframe');
    iframe.src = checkoutUrl;
    iframe.allow = 'payment *';                      // required for Apple Pay / Payment Request
    iframe.referrerPolicy = 'strict-origin-when-cross-origin';
    iframe.style.cssText = 'width:100%;height:560px;border:0';
    document.getElementById('checkout-container').replaceChildren(iframe);
  }

  window.addEventListener('message', async (e) => {
    if (e.origin !== KWIK_ORIGIN) return;            // trust only the checkout
    const evt = e.data || {};
    if (evt.source !== 'kwik-payments') return;

    switch (evt.event) {
      case 'payment.successful': {
        const { paid } = await fetch(
          `${BACKEND}/api/transactions/${evt.transactionPublicId}/verify`
        ).then((r) => r.json());
        if (paid) {
          // fulfil the order / show your own confirmation
        }
        break;
      }
      case 'payment.cancelled':
      case 'payment.closed':
        document.getElementById('checkout-container').replaceChildren();
        break;
      // payment.loaded / payment.pending / payment.failed:
      // no action needed — the checkout handles its own UI
    }
  });

  startCheckout();
</script>

const crypto = require('crypto')

function canonicalize(value) {
  if (value === null || typeof value !== 'object') {
    return JSON.stringify(value)
  }

  if (Array.isArray(value)) {
    return `[${value.map(canonicalize).join(',')}]`
  }

  return `{${Object.keys(value)
    .filter((key) => key !== 'signature' && value[key] !== undefined)
    .sort()
    .map((key) => `${JSON.stringify(key)}:${canonicalize(value[key])}`)
    .join(',')}}`
}

function generateKwikSignature(payload, passphrase) {
  const canonicalPayload = canonicalize(payload)

  return crypto
    .createHmac('sha256', passphrase)
    .update(canonicalPayload)
    .digest('hex')
}

// Usage example
const payload = {
  type: 'CHOOSE_WHAT_TO_PAY',
  item: {
    title: 'My product name',
    frequency: ['ONE_TIME'], // optional
    amount: '1200.00'       // optional
  }
}

// get this from the dashboard when creating an API key
const passphrase = 'your-secure-passphrase'

const signature = generateKwikSignature(payload, passphrase)

const requestBody = {
  ...payload,
  signature
}

console.log('Canonical payload:', canonicalize(payload))
console.log('Signature:', signature)
console.log('Request body:', requestBody)

<?php

function canonicalize($value) {
    if ($value === null) return 'null';
    if (is_bool($value)) return $value ? 'true' : 'false';
    if (is_int($value) || is_float($value)) return json_encode($value);
    if (is_string($value)) return json_encode($value);

    if (is_array($value)) {
        $isList = array_keys($value) === range(0, count($value) - 1);

        if ($isList) {
            return '[' . implode(',', array_map('canonicalize', $value)) . ']';
        }

        ksort($value);

        $parts = [];
        foreach ($value as $key => $item) {
            if ($key === 'signature') continue;
            $parts[] = json_encode((string)$key) . ':' . canonicalize($item);
        }

        return '{' . implode(',', $parts) . '}';
    }

    return json_encode($value);
}

function generateKwikSignature($payload, $passphrase) {
    return hash_hmac('sha256', canonicalize($payload), $passphrase);
}

// Usage
$payload = [
    "type" => "CHOOSE_WHAT_TO_PAY",
    "item" => [
        "title" => "My product name",
        "frequency" => ["ONE_TIME"],
        "amount" => "1200.00"
    ]
];

$passphrase = 'your-secure-passphrase';

$signature = generateKwikSignature($payload, $passphrase);

$requestBody = array_merge($payload, [
    "signature" => $signature
]);

print_r($requestBody);

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

public class KwikSignature
{
    public static string Canonicalize(object value)
    {
        if (value == null) return "null";

        if (value is string || value is bool || value is int || value is long || value is decimal || value is double)
            return JsonSerializer.Serialize(value);

        if (value is IEnumerable<object> list)
            return "[" + string.Join(",", list.Select(Canonicalize)) + "]";

        if (value is IDictionary<string, object> dict)
        {
            var parts = dict
                .Where(kvp => kvp.Key != "signature")
                .OrderBy(kvp => kvp.Key)
                .Select(kvp => JsonSerializer.Serialize(kvp.Key) + ":" + Canonicalize(kvp.Value));

            return "{" + string.Join(",", parts) + "}";
        }

        return JsonSerializer.Serialize(value);
    }

    public static string GenerateKwikSignature(IDictionary<string, object> payload, string passphrase)
    {
        var canonical = Canonicalize(payload);

        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(passphrase));
        var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(canonical));

        return Convert.ToHexString(hash).ToLowerInvariant();
    }

    public static void Main()
    {
        var payload = new Dictionary<string, object>
        {
            ["type"] = "CHOOSE_WHAT_TO_PAY",
            ["item"] = new Dictionary<string, object>
            {
                ["title"] = "My product name",
                ["frequency"] = new List<object> { "ONE_TIME" },
                ["amount"] = "1200.00"
            }
        };

        var passphrase = "your-secure-passphrase";

        var signature = GenerateKwikSignature(payload, passphrase);
        payload["signature"] = signature;

        Console.WriteLine(JsonSerializer.Serialize(payload));
    }
}

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.*;

public class KwikSignature {

    public static String canonicalize(Object value) {
        if (value == null) return "null";

        if (value instanceof String) return "\"" + value + "\"";
        if (value instanceof Boolean || value instanceof Number) return value.toString();

        if (value instanceof List<?>) {
            List<?> list = (List<?>) value;
            List<String> parts = new ArrayList<>();
            for (Object item : list) parts.add(canonicalize(item));
            return "[" + String.join(",", parts) + "]";
        }

        if (value instanceof Map<?, ?> map) {
            List<String> keys = new ArrayList<>();
            for (Object k : map.keySet()) {
                if (!"signature".equals(k)) keys.add((String) k);
            }
            Collections.sort(keys);

            List<String> parts = new ArrayList<>();
            for (String key : keys) {
                parts.add("\"" + key + "\":" + canonicalize(map.get(key)));
            }

            return "{" + String.join(",", parts) + "}";
        }

        return "\"" + value.toString() + "\"";
    }

    public static String generateKwikSignature(Map<String, Object> payload, String passphrase) throws Exception {
        String canonical = canonicalize(payload);

        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(passphrase.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));

        byte[] hash = mac.doFinal(canonical.getBytes(StandardCharsets.UTF_8));

        StringBuilder hex = new StringBuilder();
        for (byte b : hash) hex.append(String.format("%02x", b));

        return hex.toString();
    }

    public static void main(String[] args) throws Exception {
        Map<String, Object> payload = new HashMap<>();

        payload.put("type", "CHOOSE_WHAT_TO_PAY");

        Map<String, Object> item = new HashMap<>();
        item.put("title", "My product name");
        item.put("frequency", List.of("ONE_TIME"));
        item.put("amount", "1200.00");

        payload.put("item", item);

        String passphrase = "your-secure-passphrase";

        String signature = generateKwikSignature(payload, passphrase);

        payload.put("signature", signature);

        System.out.println(payload);
    }
}

import json
import hmac
import hashlib

def canonicalize(value):
    if value is None or not isinstance(value, (dict, list)):
        return json.dumps(value, separators=(',', ':'))

    if isinstance(value, list):
        return '[' + ','.join(canonicalize(v) for v in value) + ']'

    return '{' + ','.join(
        json.dumps(k) + ':' + canonicalize(value[k])
        for k in sorted(value.keys())
        if k != 'signature'
    ) + '}'

def generate_kwik_signature(payload, passphrase):
    canonical = canonicalize(payload)

    return hmac.new(
        passphrase.encode(),
        canonical.encode(),
        hashlib.sha256
    ).hexdigest()

# Usage
payload = {
    "type": "CHOOSE_WHAT_TO_PAY",
    "item": {
        "title": "My product name",
        "frequency": ["ONE_TIME"],
        "amount": "1200.00"
    }
}

passphrase = "your-secure-passphrase"

signature = generate_kwik_signature(payload, passphrase)

request_body = {
    **payload,
    "signature": signature
}

print(request_body)