Auth widget

Verify a Ghana phone number with SMS. Redeem the token on your server before you trust the number.

Prerequisites

A platform with a public key (pk_test_ or pk_live_).
Your page origin on that platform’s allowlist.
A secret key on your server for redeem (sk_test_ or sk_live_).

Install

For React apps, install the package:

npm install @payloqa/auth-widget

Usage

React

tsx

import { AuthWidget } from "@payloqa/auth-widget";

<AuthWidget
  publicKey="pk_test_…"
  redirectUrl="https://your-shop.com/in"
  mode="inline"
  onSuccess={(session) => {
    fetch("/your-login", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ token: session.token }),
    });
  }}
/>

HTML (no npm)

html

<script src="https://js.payloqa.com/v1/auth.js"></script>
<div id="payloqa-auth"></div>
<script>
  Payloqa.mountAuthWidget("#payloqa-auth", {
    publicKey: "pk_test_…",
    redirectUrl: "https://your-shop.com/in",
    mode: "inline",
    onSuccess(session) {
      fetch("/your-login", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ token: session.token }),
      });
    },
  });
</script>

If you set redirectUrl, the redirect only adds payloqa_auth=verified — never the token. Do not put the token in the URL.

Redeem the token on your server

onSuccess returns msisdn and token (cs_…). Do not trust the number from the browser. POST the token to Payloqa from your server with your secret key. Each token works once.

Redeem an auth token

POST/v1/client-sessions/redeem

Auth: Authorization: Bearer sk_test_ or sk_live_

Call this from your server, not from the browser.

A used or expired token fails. Ask the customer to verify again.

Request body

{
  "token": "cs_…"
}

Response

{
  "msisdn": "0244123456",
  "expires_at": "2026-09-04T12:10:00.000Z"
}

curl 'https://api.payloqa.com/v1/client-sessions/redeem' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_test_...' \
  -d '{
  "token": "cs_…"
}'