Developer integration

Sign in to YoqPay from your app.

Authenticate an existing YoqPay account using its email address or phone number. Requests are signed server-to-server, so your shared secret stays private.

Email loginPhone loginHMAC-SHA256

SSO endpoints

Send JSON over HTTPS and sign the exact request body with your shared secret.

Sign in

Verify an existing YoqPay account. Use an email or phone number in identifier.

POSThttps://www.yoqpay.com/sso/login

Create an account

Create an external identity for a new business account. Email must not already be registered.

POSThttps://www.yoqpay.com/sso/register

Keep the secret on your server. Configure the same external_auth_shared_secret on your YoqPay and client servers. Never put it in browser JavaScript, a mobile app bundle, or a public repository. Timestamps are accepted for five minutes.

The signed JSON body is the same for both login methods; change only the identifier value.

PHP · cURL

<?php
$payload = [
    'identifier' => 'customer@example.com', // or +255712345678
    'password' => $customerPassword,
];
$body = json_encode($payload, JSON_UNESCAPED_SLASHES);
$timestamp = (string) time();
$secret = getenv('YOQPAY_SSO_SECRET');
$signature = hash_hmac('sha256', $timestamp . '.' . $body, $secret);

$ch = curl_init('https://www.yoqpay.com/sso/login');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-External-Timestamp: ' . $timestamp,
        'X-External-Signature: ' . $signature,
    ],
    CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Node.js · fetch

import { createHmac } from 'node:crypto';

const payload = {
  identifier: '+255712345678', // or customer@example.com
  password: customerPassword,
};
const body = JSON.stringify(payload);
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac('sha256', process.env.YOQPAY_SSO_SECRET)
  .update(`${timestamp}.${body}`)
  .digest('hex');

const response = await fetch('https://www.yoqpay.com/sso/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-External-Timestamp': timestamp,
    'X-External-Signature': signature,
  },
  body,
});
console.log(response.status, await response.json());

Request and response

Phone values can use local or international format. Use a unique phone number on the YoqPay account.

Email or phone payload

{
  "identifier": "customer@example.com",
  "password": "customer-password"
}

// Phone login
{
  "identifier": "+255712345678",
  "password": "customer-password"
}

Successful response · 200

{
  "success": true,
  "external_id": 123,
  "email": "customer@example.com",
  "phone_number": "+255712345678"
}

Configure the secretSet external_auth_shared_secret in both server environments. Keep it out of client-side code.

Sign every requestHMAC the timestamp, a dot, and the exact raw JSON body using SHA-256.

Handle the resultOn success, use external_id to link the authenticated YoqPay identity to your local session.

SSO endpoints

Sign in

Create an account

Login request examples

Request and response