Payrify API Documentation

Version 1.0 | Base URL: https://payrify.et/api/v1

Key Features

• Automated Payment Verification - Submit payment receipts and get automated verification
• Real-time Status Updates - Track transaction status in real-time
• Webhook Notifications - Receive instant notifications when transaction status changes
• Secure Authentication - API key-based authentication with subscription validation

Authentication

All API requests must be authenticated using a Bearer token (your API key).

Getting Your API Key

1. Log in to your Payrify dashboard at https://payrify.et
2. Navigate to Settings → API Keys
3. Copy your API key
4. Ensure your subscription includes API access

Authentication Header

Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY_HERE

Example Request

curl -X GET https://payrify.et/api/v1/transactions \
  -H "Authorization: Bearer sk_live_abc123xyz456"

Rate Limiting

Current Limit: 100 requests per minute per API key

When you exceed the rate limit, you'll receive a 429 Too Many Requests response.

List Transactions

Retrieve a paginated list of your transactions.

Query Parameters

Example Request

curl -X GET "https://payrify.et/api/v1/transactions?page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response (200 OK)

{
  "success": true,
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 123,
        "client_reference_id": "ORDER-2025-001",
        "status": "completed",
        "amount_expected_etb": 1500.00,
        "verified_amount_etb": 1500.00,
        "created_at": "2025-01-15T10:30:00Z"
      }
    ],
    "total": 67
  }
}

Create Transaction

Create a new payment transaction for verification.

Request Body

Example Request

curl -X POST https://payrify.et/api/v1/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_expected_etb": 2500.00,
    "expected_account_name": "Jane Smith",
    "image_url": "https://example.com/receipts/payment-001.jpg",
    "client_reference_id": "ORDER-2025-002",
    "client_bank_account_id": 5
  }'

Example Response (202 Accepted)

{
  "success": true,
  "message": "Transaction received and is being processed.",
  "data": {
    "system_transaction_id": 124,
    "client_reference_id": "ORDER-2025-002",
    "status": "pending",
    "created_at": "2025-01-15T11:00:00Z"
  }
}

Get Transaction Details

Retrieve details of a specific transaction by ID or reference.

Example Request

curl -X GET https://payrify.et/api/v1/transactions/124 \
  -H "Authorization: Bearer YOUR_API_KEY"

Transaction Statuses

Submit Verification ID

Submit a verification ID document when a transaction requires manual review.

Response Codes

Error Handling

All error responses follow this format:

{
  "success": false,
  "message": "Error description",
  "errors": {
    "field_name": ["Validation error message"]
  }
}

Webhooks

Payrify can send webhook notifications when transaction status changes.

Webhook Events

• transaction.completed - Transaction verification completed successfully
• transaction.failed - Transaction verification failed
• transaction.needs_review - Transaction requires manual review

Best Practices

1. Use Unique Reference IDs

Always use unique client_reference_id values to avoid conflicts.

2. Handle Asynchronous Processing

Transaction verification is asynchronous. Use webhooks for real-time updates.

3. Implement Retry Logic

Handle rate limiting with exponential backoff.

Code Examples

PHP (Laravel)

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'Authorization' => 'Bearer ' . config('services.payrify.api_key'),
])->post('https://payrify.et/api/v1/transactions', [
    'amount_expected_etb' => 1500.00,
    'expected_account_name' => 'John Doe',
    'image_url' => 'https://example.com/receipt.jpg',
    'client_reference_id' => 'ORDER-' . time(),
    'client_bank_account_id' => 5,
]);

$result = $response->json();

JavaScript (Node.js)

const axios = require('axios');

const response = await axios.post('https://payrify.et/api/v1/transactions', {
  amount_expected_etb: 1500.00,
  expected_account_name: 'John Doe',
  image_url: 'https://example.com/receipt.jpg',
  client_reference_id: `ORDER-${Date.now()}`,
  client_bank_account_id: 5
}, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

console.log(response.data);

Python

import requests
import time

response = requests.post(
    'https://payrify.et/api/v1/transactions',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'amount_expected_etb': 1500.00,
        'expected_account_name': 'John Doe',
        'image_url': 'https://example.com/receipt.jpg',
        'client_reference_id': f'ORDER-{int(time.time())}',
        'client_bank_account_id': 5
    }
)

result = response.json()
print(result)