Payrize API
Documentation

curl -X POST https://payrize.et/api/v1/verify-transaction.php \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_id": "cbe",
    "receipt_number": "FT26189ABCDE",
    "amount": 5500.00,
    "currency": "ETB"
  }'

<?php

// Payrize API Verification - PHP Example
// Requires: PHP 7.4+ with cURL extension

class PayrizeAPI {
    private $apiKey;
    private $baseUrl = 'https://api.payrize.et';
    
    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }
    
    /**
     * Verify a payment receipt
     * 
     * @param string $bankId      Bank identifier (cbe, telebirr, boa, etc.)
     * @param string $receipt     Receipt number to verify
     * @param float  $amount      Expected amount (optional)
     * @param string $merchantAcc Merchant account number (optional)
     * @return array              Decoded API response
     * @throws Exception          On API error
     */
    public function verifyTransaction(
        $bankId,
        $receipt,
        $amount = null,
        $merchantAcc = null
    ) {
        $payload = [
            'bank_id' => $bankId,
            'receipt_number' => $receipt,
        ];
        
        if ($amount !== null) {
            $payload['amount'] = $amount;
        }
        
        if ($merchantAcc !== null) {
            $payload['merchant_account'] = $merchantAcc;
        }
        
        $ch = curl_init($this->baseUrl . '/v1/verify-transaction.php');
        
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . $this->apiKey,
                'Content-Type: application/json',
                'Accept: application/json',
            ],
            CURLOPT_POSTFIELDS => json_encode($payload),
            CURLOPT_TIMEOUT => 30,
        ]);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $error = curl_error($ch);
        curl_close($ch);
        
        if ($error) {
            throw new Exception("cURL Error: $error");
        }
        
        $data = json_decode($response, true);
        
        if ($httpCode >= 400) {
            $errorMsg = $data['error'] ?? 'Unknown error';
            throw new Exception("API Error ($httpCode): $errorMsg");
        }
        
        return $data;
    }
}

// Usage Example
try {
    $payrize = new PayrizeAPI('sk_test_your_key_here');
    
    $result = $payrize->verifyTransaction(
        'cbe',                    // Bank ID
        'FT26189ABCDE',            // Receipt number
        5500.00,                   // Expected amount
        '1000123456789'            // Merchant account (optional)
    );
    
    if ($result['success'] && $result['status'] === 'VERIFIED') {
        echo "✓ Payment verified successfully!\n";
        echo "Amount: " . $result['data']['amount'] . " ETB\n";
        echo "Sender: " . $result['data']['sender_name'] . "\n";
        echo "Verification ID: " . $result['data']['verification_id'] . "\n";
    }
    
} catch (Exception $e) {
    error_log("Payrize Error: " . $e->getMessage());
    echo "✗ Verification failed: " . $e->getMessage();
}

import requests
import os
from typing import Optional, Dict, Any

class PayrizeAPI:
    """Payrize Payment Verification API Client"""
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://payrize.et/api"
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
            "Accept": "application/json",
        })
    
    def verify_transaction(
        self,
        bank_id: str,
        receipt_number: str,
        amount: Optional[float] = None,
        merchant_account: Optional[str] = None,
        currency: str = "ETB"
    ) -> Dict[str, Any]:
        """
        Verify a payment receipt.
        
        Args:
            bank_id: Bank identifier (cbe, telebirr, boa, etc.)
            receipt_number: Receipt number to verify
            amount: Expected transaction amount (optional)
            merchant_account: Merchant account number (optional)
            currency: Currency code (default: ETB)
            
        Returns:
            Dict containing verification result
            
        Raises:
            requests.RequestException: On API error
        """
        
        payload = {
            "bank_id": bank_id,
            "receipt_number": receipt_number,
            "currency": currency,
        }
        
        if amount is not None:
            payload["amount"] = amount
        
        if merchant_account:
            payload["merchant_account"] = merchant_account
        
        try:
            response = self.session.post(
                f"{self.base_url}/v1/verify-transaction.php",
                json=payload,
                timeout=30
            )
            response.raise_for_status()
            return response.json()
            
        except requests.exceptions.HTTPError as e:
            error_data = e.response.json() if e.response.text else {}
            error_msg = error_data.get("error", str(e))
            raise requests.RequestException(
                f"API Error ({e.response.status_code}): {error_msg}"
            )
        except requests.exceptions.Timeout:
            raise requests.RequestException("Request timed out after 30 seconds")


# Usage Example
if __name__ == "__main__":
    # Get API key from environment variable (recommended)
    api_key = os.environ.get("PAYRIZE_API_KEY", "sk_test_your_key_here")
    
    payrize = PayrizeAPI(api_key)
    
    try:
        result = payrize.verify_transaction(
            bank_id="cbe",
            receipt_number="FT26189ABCDE",
            amount=5500.00,
            merchant_account="1000123456789"
        )
        
        if result["success"] and result["status"] == "VERIFIED":
            data = result["data"]
            print(f"✓ Payment verified successfully!")
            print(f"Amount: {data['amount']} {data['currency']}")
            print(f"Sender: {data['sender_name']}")
            print(f"Verified at: {data['verified_at']}")
            print(f"Verification ID: {data['verification_id']}")
        else:
            print(f"✗ Verification failed: {result}")
            
    except requests.RequestException as e:
        print(f"✗ Error: {e}")

// Payrize API - JavaScript Fetch Example
// WARNING: Never expose API keys in client-side code!
// Use a backend proxy for production applications.

class PayrizeClient {
    constructor(apiKey, baseUrl = 'https://api.payrize.et') {
        this.apiKey = apiKey;
        this.baseUrl = baseUrl;
    }

    async verifyTransaction({
        bankId,
        receiptNumber,
        amount = null,
        merchantAccount = null,
        currency = 'ETB'
    }) {
        const payload = {
            bank_id: bankId,
            receipt_number: receiptNumber,
            currency: currency
        };

        if (amount !== null) payload.amount = amount;
        if (merchantAccount) payload.merchant_account = merchantAccount;

        const response = await fetch(`${this.baseUrl}/v1/verify-transaction`, {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${this.apiKey}`,
                'Content-Type': 'application/json',
                'Accept': 'application/json'
            },
            body: JSON.stringify(payload)
        });

        const data = await response.json();

        if (!response.ok) {
            throw new Error(
                data.error || `HTTP ${response.status}: Request failed`
            );
        }

        return data;
    }
}

// Usage Example
async function verifyPayment() {
    const payrize = new PayrizeClient('sk_test_your_key_here');

    try {
        const result = await payrize.verifyTransaction({
            bankId: 'cbe',
            receiptNumber: 'FT26189ABCDE',
            amount: 5500.00,
            merchantAccount: '1000123456789'
        });

        if (result.success && result.status === 'VERIFIED') {
            console.log('✓ Payment verified successfully!');
            console.log('Amount:', result.data.amount, result.data.currency);
            console.log('Sender:', result.data.sender_name);
            console.log('Verification ID:', result.data.verification_id);
        }
    } catch (error) {
        console.error('✗ Verification failed:', error.message);
    }
}

verifyPayment();

// Payrize API - Node.js Example
// Requires Node.js 18+ for native fetch, or install node-fetch

class PayrizeAPI {
    constructor(apiKey, baseUrl = 'https://api.payrize.et') {
        this.apiKey = apiKey;
        this.baseUrl = baseUrl;
    }

    async verifyTransaction({
        bankId,
        receiptNumber,
        amount = null,
        merchantAccount = null,
        currency = 'ETB'
    }) {
        const payload = {
            bank_id: bankId,
            receipt_number: receiptNumber,
            currency
        };

        if (amount) payload.amount = amount;
        if (merchantAccount) payload.merchant_account = merchantAccount;

        const response = await fetch(`${this.baseUrl}/v1/verify-transaction`, {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${this.apiKey}`,
                'Content-Type': 'application/json',
                'Accept': 'application/json'
            },
            body: JSON.stringify(payload)
        });

        const data = await response.json();

        if (!response.ok) {
            const error = new Error(data.error || `API returned ${response.status}`);
            error.status = response.status;
            error.data = data;
            throw error;
        }

        return data;
    }
}

// Usage Example with Express.js middleware
const payrize = new PayrizeAPI(process.env.PAYRIZE_API_KEY);

// Example Express route handler
app.post('/api/verify-payment', async (req, res) => {
    try {
        const result = await payrize.verifyTransaction({
            bankId: req.body.bank_id,
            receiptNumber: req.body.receipt_number,
            amount: req.body.amount,
            merchantAccount: req.body.merchant_account
        });

        if (result.success) {
            // Store verification in your database
            await db.saveVerification(result.data);
            
            return res.json({
                success: true,
                message: 'Payment verified successfully',
                data: result.data
            });
        }
    } catch (error) {
        console.error('Verification error:', error.message);
        
        return res.status(error.status || 500).json({
            success: false,
            error: error.message
        });
    }
});

// Standalone usage
(async () => {
    try {
        const result = await payrize.verifyTransaction({
            bankId: 'cbe',
            receiptNumber: 'FT26189ABCDE',
            amount: 5500.00
        });
        console.log('✓ Verified:', result.data);
    } catch (error) {
        console.error('✗ Failed:', error.message);
    }
})();