API Documentation | Professional Payment Processing

Introduction

Welcome to the official Payrify API documentation for our Payment Processing Platform. Our API is organized around REST principles and is designed to be predictable and easy to use. All API requests and responses are in JSON format.

Base URL: All API v2 endpoints are relative to the following base URL:

https://check.payrify.et/api/v2

Getting Started

To get started with our API, you'll need to:

Create an account on our platform
Navigate to the "API & Settings" section in your dashboard
Generate your API keys
Configure your webhook endpoint to receive events

Authentication

All API requests must be authenticated using your unique API Key. Provide this key as a Bearer Token in the Authorization header of every request.

Keep your API keys secure and never expose them in client-side code. Treat them like passwords.

Header Example:

HTTP Headers


Authorization: Bearer YOUR_API_KEY_HERE
Accept: application/json
Content-Type: application/json

Workflow 1: The Standard Transaction Flow

This is the "happy path" for a typical transaction where all information matches correctly.

Process Flow:

You Initiate the Transaction: Your system sends a request to our POST /transactions endpoint. You must include the amount, the receipt image URL, and the full name of the account holder who is supposed to be making the payment.
We Verify Asynchronously: Our system accepts your request and immediately responds with status: "pending". We then begin verifying the transaction in the background using the receipt image.
Verification Succeeds: Our system checks the receipt. It confirms that the Payer Name and the amount on the receipt match what you provided.
You Receive a Webhook: Once verification is complete, we send a webhook to your configured URL with "status": "completed". Your user's balance is credited, and the transaction is finished.

Note: The standard flow typically completes within 2-5 minutes, depending on image quality and system load.

Workflow 2: The Manual Review Flow (Name Mismatch)

This workflow is triggered automatically as a fraud prevention measure when the name on the payment receipt does not match the name you provided.

Process Flow:

You Initiate the Transaction: Same as the standard flow. You send the expected account name.
Verification Finds a Mismatch: Our system checks the receipt and finds that the Payer Name (e.g., "Jane Doe") does not match the expected_account_name you sent (e.g., "John Doe").
You Receive a "Needs Review" Webhook: Instead of failing, we send a webhook with "status": "needs_review". The webhook will also contain a review_reason field explaining the name mismatch. The transaction is paused.
You Request an ID from Your User: Your system should see the "needs_review" status and ask your user to provide a photo of their government-issued ID to prove they are the legitimate payer.
You Submit the ID for Review: Once you have the ID image hosted at a URL, you send this URL to our new POST /transactions/submit-id endpoint, referencing the original transaction.
Our Team Reviews: Our admin team is notified. We will compare the name on the submitted ID with the name on the payment receipt.
You Receive a Final Webhook: After our review, we will manually set the transaction to either "completed" or "failed". You will receive a final webhook with this outcome.

Time Limit: You have 48 hours to submit the ID after receiving the "needs_review" status. After this period, the transaction will automatically be marked as failed.

Webhooks

We use webhooks to notify your application about events in real-time. Configure your webhook URL in your "API & Settings" page to receive these events.

Webhook Security

For security, all webhook requests sent from our server will include an Authorization: Bearer YOUR_WEBHOOK_SECRET header. You must verify this secret to ensure the request is legitimate.

Webhook Payload Example

JSON


{
    "event_id": "evt_1MjqD72eZvKYlo2C",
    "type": "transaction.updated",
    "created_at": "2023-04-15T12:34:56Z",
    "data": {
        "transaction_id": "txn_1MjqC72eZvKYlo2B",
        "client_reference_id": "YOUR-UNIQUE-INVOICE-ID-123",
        "status": "completed",
        "amount_expected_etb": "1000.00",
        "amount_verified_etb": "1000.00"
    }
}

Retry Policy

If your webhook endpoint returns a non-2xx HTTP status code, we will retry the delivery with exponential backoff for up to 24 hours.

Transaction Statuses

Transactions go through various statuses during their lifecycle. Understanding these statuses is crucial for implementing proper handling logic in your application.

Status	Description	Next Possible Statuses
pending	The transaction has been received and is awaiting verification.	processing, failed
processing	The transaction is actively being verified by our system.	completed, needs_review, failed
completed	The transaction was successful, and the funds have been added to your balance.	Final status
failed	The transaction failed due to an error (e.g., amount mismatch, invalid receipt). The reason will be in the `failure_reason` field.	Final status
needs_review	The transaction requires manual intervention due to a data mismatch (e.g., payer name). The reason will be in the `review_reason` field. You must submit an ID to proceed.	completed, failed

Endpoint: Exchange Rates

Get Live Exchange Rate

GET/exchange-rate

Retrieves the current exchange rate used by the platform for currency conversions.

Response Example:

JSON


{
    "base_currency": "USD",
    "target_currency": "ETB",
    "exchange_rate": "54.75",
    "last_updated": "2023-04-15T10:30:00Z"
}

Endpoint: Transactions

Create a Transaction

POST/transactions

Submits a new incoming transaction for verification. This is the first step in any payment flow.

Request Parameters:

Parameter	Type	Required	Description
`amount_expected_etb`	String	Yes	The expected amount in ETB
`expected_account_name`	String	Yes	Full name of the expected account holder
`image_url`	String	Yes	URL of the payment receipt image
`account_number`	String	No	Account number if available
`client_reference_id`	String	Yes	Your unique identifier for this transaction

Request Example:

JSON


{
    "amount_expected_etb": "1000.00",
    "expected_account_name": "John Doe",
    "image_url": "https://example.com/receipt.jpg",
    "account_number": "1000123456789",
    "client_reference_id": "YOUR-UNIQUE-INVOICE-ID-123"
}

Response Example:

JSON


{
    "transaction_id": "txn_1MjqC72eZvKYlo2B",
    "client_reference_id": "YOUR-UNIQUE-INVOICE-ID-123",
    "status": "pending",
    "created_at": "2023-04-15T12:34:56Z"
}

Submit Payer ID for Review

POST/transactions/submit-id

Use this endpoint only when a transaction's status is needs_review. Submit a URL to an image of the payer's ID to allow our team to manually verify the transaction.

Request Example:

JSON


{
    "client_reference_id": "THE-SAME-ID-FROM-THE-ORIGINAL-REQUEST",
    "id_image_url": "https://example.com/user_id_photo.jpg"
}

List Transactions

GET/transactions

Retrieves a paginated list of all transactions.

Query Parameters:

Parameter	Type	Description
`limit`	Integer	Number of records to return (default: 10, max: 100)
`offset`	Integer	Number of records to skip for pagination
`status`	String	Filter by status (e.g., pending, completed)

Get Transaction

GET/transactions/{id}

Retrieves a single transaction by its system_transaction_id.

Endpoint: Payouts

These endpoints allow you to manage withdrawing your funds from the platform.

Get Supported Banks

GET/payouts/banks

Retrieves a list of all supported banks for bank transfer payouts.

Request a Payout

POST/payouts

Submits a new payout request from your available balance.

Request Example:

JSON


{
    "amount": "5000.00",
    "bank_code": "BOFAUS3M",
    "account_number": "0987654321",
    "currency": "ETB"
}

List Payouts

GET/payouts

Retrieves a paginated list of all your payout requests.

Get Payout

GET/payouts/{id}

Retrieves a single payout request by its payout_id.