Authentication

Authentication Methods Comparison

Ziba Pay enforces authentication across all sensitive API routes. Depending on whether your system is an automated backend service, a scheduled worker, or a browser-based web application, select the appropriate authentication strategy below:

Bearer Token Authentication (JWT)

Merchant routes authenticate using a signed JSON Web Token (JWT) passed in the standard Authorization HTTP request header:

import axios from "axios";

const response = await axios.get("https://payment-service-mh2d.onrender.com/api/transactions", {
  headers: {
    Authorization: `Bearer ${process.env.ZIBA_TOKEN}`,
    "Content-Type": "application/json",
  },
  timeout: 10000,
});

console.log("Transactions:", response.data);

Gateway API Keys (Server-to-Server)

Automated payment jobs that do not maintain short-lived merchant login sessions authenticate using Gateway API Keys (x-api-key and x-api-secret).

You generate API Keys via POST/developer/gatewayConfigs. The plaintext apiSecret is shown only once and must be stored securely in an environment variable.

curl -X POST "https://payment-service-mh2d.onrender.com/api/payment/mtn-momo-pay" \
  -H "Authorization: Bearer $ZIBA_ACCESS_TOKEN" \
  -H "x-api-secret: $ZIBA_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "RWF",
    "phoneNumber": "+250788000000"
  }'

Token Lifecycles & Automatic Refresh

When you authenticate via POST/auth/login or POST/auth/signup, Ziba Pay returns both an access token and a refresh token in the response JSON and sets corresponding HTTP-only cookies:

CSRF Defense for Browser Cookie Sessions

Direct server-to-server calls authenticated via Bearer tokens or Gateway API Keys do not require CSRF headers.

However, if you invoke mutation endpoints (POST, PATCH, DELETE) from a web browser using cookie-based authentication, you must send the header below to prevent Cross-Site Request Forgery:

Account & Authentication Endpoints

The table below details all identity, session, and credential lifecycle routes: