Card Vault

// 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/card-vault/', async (req, res) => {

  // TODO: Get the customerId stored from your session, token or DB that was created through the /customers API
  const response = await fetch(`${KWIK_API}/card-vault/${customerId}/link`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      type: 'STORE_CARD',
      item: {
        title: 'My product name',
        amount: '2.00' // initial charge amount, min R2.00
      },
      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 vault link' });

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

// 2. Verify a transaction after the app receives card.stored
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 KwikVault({ onComplete, onCancel }) {
  const [vaultUrl, setVaultUrl] = useState(null);

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

  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: 'card.stored',
    //   sessionId: 'ses_...', transactionPublicId: 'tra_...',
    //   customerId: 'cus_...', status: 'PAID' }
    switch (evt.event) {
      case 'card.loaded':
        break; // checkout ready
      case 'card.pending':
        break; // e.g. 3DS in progress — keep the WebView open
      case 'card.stored': {
        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 'card.failed':
        break; // checkout shows its own retry UI — keep it open
      case 'card.cancelled':
      case 'card.closed':
        onCancel();
        break;
    }
  };

  if (!vaultUrl) return <ActivityIndicator />;

  return (
    <WebView
      source={{ uri: vaultUrl }}
      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 KwikVault extends StatefulWidget {
  final void Function(String transactionPublicId) onComplete;
  final VoidCallback onCancel;

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

  @override
  State<KwikVault> createState() => _KwikVaultState();
}

class _KwikVaultState extends State<KwikVault> {
  String? vaultUrl;

  @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/card-vault'));
    final body = jsonDecode(res.body) as Map<String, dynamic>;
    setState(() => vaultUrl = body['vaultUrl'] 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: 'card.stored',
    //   sessionId: 'ses_...', transactionPublicId: 'tra_...',
    //   customerId: 'cus_...', status: 'PAID' }
    switch (evt['event']) {
      case 'card.loaded':
        break; // checkout ready
      case 'card.pending':
        break; // e.g. 3DS in progress — keep the WebView open
      case 'card.stored':
        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 'card.failed':
        break; // checkout shows its own retry UI — keep it open
      case 'card.cancelled':
      case 'card.closed':
        widget.onCancel();
        break;
    }
  }

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

    return InAppWebView(
      initialUrlRequest: URLRequest(url: WebUri(vaultUrl!)),
      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 KwikVaultViewController: 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/card-vault"))
        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 vaultUrl = json["vaultUrl"] as? String,
                  let url = URL(string: vaultUrl) 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: 'card.stored',
        //   sessionId: 'ses_...', transactionPublicId: 'tra_...',
        //   customerId: 'cus_...', status: 'PAID' }
        switch evt["event"] {
        case "card.loaded":
            break // checkout ready
        case "card.pending":
            break // e.g. 3DS in progress — keep the WebView open
        case "card.stored":
            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 "card.failed":
            break // checkout shows its own retry UI — keep it open
        case "card.cancelled", "card.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 KwikVaultActivity : 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 vaultUrl = withContext(Dispatchers.IO) {
                val req = Request.Builder()
                    .url("$backend/api/card-vault")
                    .post(okhttp3.RequestBody.create(null, ByteArray(0)))
                    .build()
                http.newCall(req).execute().use { res ->
                    JSONObject(res.body!!.string()).getString("vaultUrl")
                }
            }
            webView.loadUrl(vaultUrl)
        }
    }

    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=card.stored
        //   &sessionId=ses_...&transactionPublicId=tra_...
        //   &customerId=cus_...&status=PAID
        when (uri.getQueryParameter("event")) {
            "card.loaded" -> Unit // checkout ready
            "card.pending" -> Unit // e.g. 3DS in progress — keep the WebView open
            "card.stored" -> {
                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.
                }
            }
            "card.failed" -> Unit // checkout shows its own retry UI — keep it open
            "card.cancelled", "card.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 { vaultUrl } = await fetch(`${BACKEND}/api/card-vault`, {
      method: 'POST',
    }).then((r) => r.json());

    const iframe = document.createElement('iframe');
    iframe.src = vaultUrl;
    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 'card.stored': {
        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 'card.cancelled':
      case 'card.closed':
        document.getElementById('checkout-container').replaceChildren();
        break;
      // card.loaded / card.pending / card.failed:
      // no action needed — the checkout handles its own UI
    }
  });

  startCheckout();
</script>