Uthibitishaji

Wakapay inatumia funguo za API na tokeni za Bearer kuthibitisha maombi kwa API. Mwongozo huu unaeleza jinsi ya kuthibitisha simu zako za API kwa usalama.

Muhtasari

Wakapay inasaidia mbinu mbili za uthibitishaji:

Uthibitishaji wa Funguo ya API — Hutumika kupata tokeni za upatikanaji
Uthibitishaji wa Tokeni ya Bearer — Hutumika kwa maombi yote ya API

⚠️

Hifadhi vitambulisho vyako kwa usalama! Usiwahi kuweka funguo za API katika udhibiti wa toleo (version control) au kushiriki hadharani. Vichukue kama nywila.

Hatua ya 1: Pata Tokeni ya Upatikanaji

Tumia vitambulisho vyako vya API kupata tokeni ya upatikanaji:

Ombi


POST /business/auth
Content-Type: application/json
 
{
  "apiKey": "pk_test_****123",
  "apiSecret": "sk_test_****456"
}

Mfano wa Ombi la Tokeni


curl -X POST https://api.test.wakapay.io/business/auth \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "pk_test_****123",
    "apiSecret": "sk_test_****456"
  }'

Jibu


{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.****...****",
  "expiresIn": 3600
}

Hatua ya 2: Tumia Tokeni ya Upatikanaji

Jumuisha tokeni ya upatikanaji katika kichwa cha Authorization cha maombi yote ya API:


Authorization: Bearer YOUR_ACCESS_TOKEN

Mfano wa Ombi Lililothibitishwa


curl https://api.test.wakapay.io/business/balance \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Usimamizi wa Tokeni

Muda wa Kumalizika kwa Tokeni

Tokeni za upatikanaji zinamalizika baada ya saa 1 (sekunde 3600). Tokeni inapomalizika, utapokea jibu la 401 Unauthorized:


{
  "message": "token is malformed: token contains an invalid number of segments"
}

Tokeni za Kuongeza Muda (Refresh)

Tokeni yako inapomalizika, omba mpya kwa kutumia vitambulisho vyako vya API. Hakuna utaratibu tofauti wa tokeni za refresh.

Mbinu Bora

Hifadhi tokeni: Hifadhi tokeni katika kumbukumbu na zitumie tena hadi zimalizike
Shughulikia kumalizika: Tekeleza uongezaji wa tokeni kiotomatiki unapopokea kosa la 401
Usiombe bila sababu: Omba tokeni mpya tu zinapohitajika ili kuepuka vikomo vya kiwango

Mbinu Bora za Usalama

Hifadhi Salama

Vigeu vya mazingira (environment variables): Hifadhi vitambulisho katika vigeu vya mazingira, si katika msimbo
Usimamizi wa siri: Tumia huduma za usimamizi wa siri (AWS Secrets Manager, HashiCorp Vault)
Usiwahi kuweka kumbukumbu: Usiweke vitambulisho au tokeni katika kumbukumbu za programu


// Vizuri
const apiKey = process.env.WAKAPAY_API_KEY;
 
// Vibaya
const apiKey = "pk_test_****123";

Aina za Funguo za API

Wakapay inatoa aina mbili za funguo za API:

Aina	Kiambishi	Mazingira	Matumizi
Majaribio	`yeuc...`	Test/Sandbox	Maendeleo na majaribio
Halisi	Maalum	Uzalishaji	Miamala halisi

Mfano wa Funguo ya API ya Majaribio: yeuc****...****bbe3

Daima tumia funguo za majaribio wakati wa maendeleo. Badilisha kwa funguo halisi tu unapokuwa tayari kwa uzalishaji.

Makosa ya Uthibitishaji

Vitambulisho Visivyo Sahihi


{
  "code": 0,
  "error": "invalid credentials"
}

Hali ya HTTP: 401

Sababu:

apiKey isiyo sahihi
apiSecret isiyo sahihi
Vitambulisho vimeghairiwa

Vitambulisho Vinakosekana


{
  "code": 0,
  "error": "apiKey and apiSecret required"
}

Hali ya HTTP: 400

Sababu:

Sehemu ya apiKey inakosekana
Sehemu ya apiSecret inakosekana
apiKey au apiSecret ni tupu

Kichwa cha Authorization Kinakosekana


{
  "message": "missing value in request header"
}

Hali ya HTTP: 401

Sababu: Hakuna kichwa cha Authorization katika ombi

Tokeni Iliyoharibika


{
  "message": "token is malformed: token contains an invalid number of segments"
}

Hali ya HTTP: 401

Sababu:

Muundo wa JWT usio sahihi
Tokeni iliyoharibika
Tokeni iliyomalizika

Mzigo Usio Sahihi


{
  "code": 0,
  "error": "invalid payload"
}

Hali ya HTTP: 400

Sababu:

JSON iliyoharibika katika mwili wa ombi
Kichwa kibaya cha Content-Type (lazima kiwe application/json)

Mifano ya Utekelezaji

Node.js


const axios = require("axios");
 
class WakapayClient {
  constructor(apiKey, apiSecret, environment = "test") {
    this.apiKey = apiKey;
    this.apiSecret = apiSecret;
    this.baseURL =
      environment === "production"
        ? "https://api.wakapay.io"
        : "https://api.test.wakapay.io";
    this.token = null;
    this.tokenExpiry = null;
  }
 
  async authenticate() {
    const response = await axios.post(`${this.baseURL}/business/auth`, {
      apiKey: this.apiKey,
      apiSecret: this.apiSecret,
    });
 
    this.token = response.data.data.accessToken;
    this.tokenExpiry = Date.now() + response.data.data.expiresIn * 1000;
 
    return this.token;
  }
 
  async getToken() {
    // Return cached token if still valid
    if (this.token && Date.now() < this.tokenExpiry - 60000) {
      return this.token;
    }
 
    // Otherwise, get a new token
    return await this.authenticate();
  }
 
  async request(method, endpoint, data = null) {
    const token = await this.getToken();
 
    const config = {
      method,
      url: `${this.baseURL}${endpoint}`,
      headers: {
        Authorization: "Bearer " + token,
        "Content-Type": "application/json",
      },
    };
 
    if (data) {
      config.data = data;
    }
 
    try {
      const response = await axios(config);
      return response.data;
    } catch (error) {
      if (error.response?.status === 401) {
        // Token expired, retry once with new token
        this.token = null;
        return await this.request(method, endpoint, data);
      }
      throw error;
    }
  }
}
 
// Usage
const client = new WakapayClient(
  process.env.WAKAPAY_API_KEY,
  process.env.WAKAPAY_API_SECRET,
  "test",
);
 
// Make authenticated requests
const balance = await client.request("GET", "/business/balance");

Python


import os
import time
import requests
from datetime import datetime, timedelta
 
class WakapayClient:
    def __init__(self, api_key, api_secret, environment='test'):
        self.api_key = api_key
        self.api_secret = api_secret
        self.base_url = (
            'https://api.wakapay.io' if environment == 'production'
            else 'https://api.test.wakapay.io'
        )
        self.token = None
        self.token_expiry = None
 
    def authenticate(self):
        response = requests.post(
            f'{self.base_url}/business/auth',
            json={
                'apiKey': self.api_key,
                'apiSecret': self.api_secret
            }
        )
        response.raise_for_status()
 
        data = response.json()['data']
        self.token = data['accessToken']
        self.token_expiry = datetime.now() + timedelta(seconds=data['expiresIn'])
 
        return self.token
 
    def get_token(self):
        # Return cached token if still valid (with 60s buffer)
        if self.token and datetime.now() < self.token_expiry - timedelta(seconds=60):
            return self.token
 
        # Otherwise, get a new token
        return self.authenticate()
 
    def request(self, method, endpoint, data=None):
        token = self.get_token()
 
        headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
 
        url = f'{self.base_url}{endpoint}'
 
        try:
            if method == 'GET':
                response = requests.get(url, headers=headers)
            elif method == 'POST':
                response = requests.post(url, json=data, headers=headers)
            elif method == 'PUT':
                response = requests.put(url, json=data, headers=headers)
            elif method == 'DELETE':
                response = requests.delete(url, headers=headers)
 
            response.raise_for_status()
            return response.json()
 
        except requests.exceptions.HTTPError as e:
            if e.response.status_code == 401:
                # Token expired, retry once with new token
                self.token = None
                return self.request(method, endpoint, data)
            raise
 
# Usage
client = WakapayClient(
    os.getenv('WAKAPAY_API_KEY'),
    os.getenv('WAKAPAY_API_SECRET'),
    'test'
)
 
# Make authenticated requests
balance = client.request('GET', '/business/balance')

Kujaribu Uthibitishaji

Jaribu utekelezaji wako wa uthibitishaji:


# 1. Pata tokeni
TOKEN=$(curl -s -X POST https://api.test.wakapay.io/business/auth \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "apiSecret": "YOUR_API_SECRET"
  }' | jq -r '.data.accessToken')
 
# 2. Tumia tokeni
curl https://api.test.wakapay.io/business/balance \
  -H "Authorization: Bearer $TOKEN"

Hatua Zinazofuata

Sasa kwa kuwa unaelewa uthibitishaji, chunguza:

Pochi na Salio — Angalia salio la akaunti yako
Malipo ya Nje — Tuma malipo
Miamala — Fuatilia hali ya muamala