README

A PHP client library for interacting with the XPaymen cryptocurrency payment gateway API. This library makes it easy to create and manage crypto transactions, wallets, and verify callback data.

Table of Contents

• Installation
• Configuration
• Obtaining an API Key
• API Documentation
• Usage
  • Create a Crypto Transaction
  • Get Crypto Transactions
  • Get Transaction Detail
  • Get Crypto Wallets
  • Verify Callback Data
• Testing
• License

Installation

Install this package via Composer:

composer require m-derakhshi/xpaymen

Configuration

Set your API key in your environment or pass it directly to the client:

$apiKey = 'YOUR_API_KEY_HERE';
$service = new XPaymen\Classes\XPaymenApiService($apiKey);

Obtaining an API Key

To obtain an API key, visit the official XPaymen website. Once registered, you can create and manage crypto payment gateways, and retrieve your API key from the gateway details page.

API Documentation

For developers who want to explore the full API specification interactively, we provide a Swagger UI page:

👉 Open API Documentation (Swagger UI)

This page allows you to browse available endpoints, request/response formats, and test the API directly in your browser.

Usage

Create a Crypto Transaction

try {
    $transaction = $service->createCryptoTransaction([
        'order_id' => '1234',                // required
        'source_amount' => 10,               // required
        'source_currency_code' => 'USD',     // required
    
        'payer_email' => 'user@example.com', // optional
        'payer_message' => 'hi!',            // optional
        'note' => 'Order contains 5 items',  // optional
    ]);
    echo $transaction->transactionId;
    echo $transaction->invoiceUrl;
} catch (Throwable $e) {
    echo "❌ Error creating transaction: ".$e->getMessage();
}

Get Crypto Transactions

try {
    $paginated = $service->getCryptoTransactions();

    foreach ($paginated->data as $transaction) {
        print_r($transaction->toArray());
    }
} catch (Throwable $e) {
    echo "❌ Error fetching transactions: " . $e->getMessage();
}

Get Transaction Detail

try {
    $transaction = $service->getCryptoTransactionDetail('TX123456');

    print_r($transaction->toArray());
} catch (Throwable $e) {
    echo "❌ Error fetching transaction detail: " . $e->getMessage();
}

Get Crypto Wallets

try {
    $wallets = $service->getCryptoWallets();
    foreach ($wallets->data as $wallet) {
        print_r($wallet->toArray());
    }
} catch (Throwable $e) {
    echo "❌ Error fetching wallets: " . $e->getMessage();
}

Verify Callback Data

To handle payment callbacks, you need to create a dedicated file or route in your website (for example: callback.php).

Place this file on your server and then configure its URL in your Crypto Payment Gateway settings on XPaymen.com.

Example callback.php:

<?php

use XPaymen\Classes\XPaymenApiService;
use XPaymen\DTOs\CryptoTransactionDTO;

require 'vendor/autoload.php';

$apiKey = 'YOUR_API_KEY_HERE';
$service = new XPaymenApiService($apiKey);

echo '<pre>';
try {
    $verifiedTransaction = $service->verifyCallbackData();

    if ($verifiedTransaction instanceof CryptoTransactionDTO) {
        echo "✅ Callback verified transaction:\n";
        print_r($verifiedTransaction->toArray());

        // Optional: Verify transaction on XPaymen.com
        try {
            $callbackTransaction = $service->verifyCryptoTransactionInSite($verifiedTransaction);

            if ($callbackTransaction->is_callback_url_verified) {
                echo "\n✅ Callback URL is verified.\n";
            } else {
                echo "\n⚠ Callback URL not verified.\n";
            }

        } catch (Throwable $e) {
            echo "\n❌ Error verifying transaction on site: " . $e->getMessage() . "\n";
        }

    } else {
        echo "⚠ Callback verification failed.\n";
    }

} catch (Throwable $e) {
    echo '❌ Error verifying callback data: '.$e->getMessage()."\n";
}
echo '</pre>';

Testing

This repository includes PHPUnit tests. You can run the tests with your API key in a single command:

API_KEY="your_api_key_here" vendor/bin/phpunit

License

This project is licensed under the MIT License.