Payrify | Quick Start Guide
Full Documentation Postman Collection

Payrify API - Quick Start Guide

Get started with the Payrify API in 5 minutes.

1

Get Your API Key

  1. Log in to your Payrify Dashboard
  2. Navigate to Settings → API Keys
  3. Click Generate New API Key
  4. Copy and securely store your API key

Important: Keep your API key secret. Never commit it to version control or share it publicly.

2

Make Your First API Call

Using cURL

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

Expected Response

{
  "success": true,
  "data": {
    "current_page": 1,
    "data": [],
    "total": 0
  }
}

If you see this response, your API key is working!

3

Create Your First Transaction

Prepare Your Data

You'll need:

  • Payment receipt image URL (must be publicly accessible)
  • Expected payment amount in ETB
  • Expected payer name (the person who should make the payment)
  • Your bank account ID (get this from your dashboard)
  • Unique reference ID (your internal order/transaction ID)

Make the Request

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

Expected Response

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

Check Transaction Status

Using System Transaction ID

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

Transaction Statuses

Status Description Next Action
pending Waiting to be processed Wait for processing
processing Being verified Wait for verification
completed ✅ Payment verified successfully Payment confirmed
failed ❌ Verification failed Check failure_reason
needs_review ⚠️ Requires manual review Submit verification ID
5

Handle Transaction Results

Successful Transaction

{
  "success": true,
  "data": {
    "id": 124,
    "status": "completed",
    "amount_expected_etb": 1500.00,
    "verified_amount_etb": 1500.00,
    "verified_transaction_id": "CI72PQRS3A",
    "verified_payer_name": "John Doe",
    "verified_payment_date": "2025-01-15T10:55:00Z"
  }
}

✅ Action: Mark order as paid in your system

Failed Transaction

{
  "success": true,
  "data": {
    "id": 124,
    "status": "failed",
    "failure_reason": "Amount mismatch. Expected 1500.00 ETB but received 1000.00 ETB."
  }
}

❌ Action: Notify customer about the issue

Transaction Needs Review

{
  "success": true,
  "data": {
    "id": 124,
    "status": "needs_review",
    "review_reason": "Payer name mismatch. Expected 'John Doe' but receipt shows 'Jane Doe'."
  }
}

⚠️ Action: Request customer to submit ID verification

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,
]);

if ($response->successful()) {
    $transaction = $response->json()['data'];
    // Store transaction ID and poll for status
}

JavaScript (Node.js)

const axios = require('axios');

async function createTransaction() {
  try {
    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('Transaction created:', response.data);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

createTransaction();

Python

import requests
import time

def create_transaction():
    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
        }
    )
    
    if response.status_code == 202:
        data = response.json()
        print('Transaction created:', data)
        return data['data']['system_transaction_id']
    else:
        print('Error:', response.json())
        return None

transaction_id = create_transaction()

Next Steps

  • Read Full Documentation
  • Set Up Webhooks (configure webhook URL in dashboard)
  • Implement Error Handling (handle all possible transaction states)
  • Go Live (switch to production API key)

Need Help?

Contact us for support:

support@payrify.et payrify.et