README

Official Laravel SDK for OxaPay — accept crypto payments, exchanges, and payouts.

Frameworks: Laravel 8–13
PHP: 8.0+ (Laravel 8–9) / 8.1+ (Laravel 10) / 8.2+ (Laravel 11–12) / 8.3+ (Laravel 13)
Docs: https://docs.oxapay.com

Installation

composer require oxapay/oxapay-laravel

Publish config/oxapay.php

php artisan oxapay:install

You can use --force flag to overwrite config from package

Service provider and facade are auto-discovered.

Add your keys to .env or update oxapay config:

OXAPAY_MERCHANT_KEY=your_merchant_api_key
OXAPAY_PAYOUT_KEY=your_payout_api_key
OXAPAY_GENERAL_KEY=your_general_api_key

You can define multiple slots.

Quick start

use OxaPay\Laravel\Support\Facades\OxaPay;

// via facade
$res = OxaPay::payment()->generateInvoice([
    'amount' => 10.5,
    'currency' => 'USDT'
]);

// via helper
$res = oxapay()->payment()->generateInvoice([ 
    'amount' => 10.5,
    'currency' => 'USDT'
]);

// key is optional and use default key from config if no passed
$res = OxaPay::payment('key_2')->generateInvoice([
    'amount' => 10.5,
    'currency' => 'USDT'
]);

// or use raw key
$res = OxaPay::payment("XXXXXX-XXXXXX-XXXXXX-XXXXXX")->generateInvoice([
    'amount' => 10.5,
    'currency' => 'USDT'
]);

Handling Webhooks (Payments & Payouts)

use OxaPay\Laravel\Support\Facades\OxaPay;

try{
    $res = OxaPay::webhook()->getData();
    // ...
}catch (WebhookSignatureException $e) {
    // ...
}


// or you can get data without verify HMAC
$res = OxaPay::webhook()->getData(false);

Available methods

🔹payment

• generateInvoice – Create invoice & get payment URL. More details
• generateWhiteLabel – White-label payment. More details
• generateStaticAddress – Create static deposit address. More details
• revokeStaticAddress – Revoke static address. More details
• staticAddressList – List static addresses. More details
• information – Single payment information. More details
• history – Payment history list. More details
• acceptedCurrencies – Accepted currencies. More details

🔹account

• balance – Account balance. More details

🔹payout

• generate – Request payout. More details
• information – Single payout information. More details
• history – Payout history list. More details

🔹exchange

• swapRequest – Swap request. More details
• swapHistory – Swap history. More details
• swapPairs – Swap pairs. More details
• swapCalculate – Swap pre-calc. More details
• swapRate – Swap Quote rate. More details

🔹common

• prices – Market prices. More details
• currencies – Supported crypto. More details
• fiats – Supported fiats. More details
• networks – Supported networks. More details
• monitor – System status. More details

🔹webhook

• verify – Validates HMAC header (sha512 of raw body).
• getData – Validates HMAC header and return webhook data. More details

Exceptions

All SDK exceptions extend OxaPay\Laravel\Exceptions\OxaPayException:

• ValidationRequestException (HTTP 400)
• InvalidApiKeyException (HTTP 401)
• NotFoundException (HTTP 404)
• RateLimitException (HTTP 429)
• ServerErrorException (HTTP 500)
• ServiceUnavailableException (HTTP 503)
• HttpException (network/unknown)
• MissingApiKeyException (missing api key)
• MissingTrackIdException (missing track id)
• MissingAddressException (missing address)
• WebhookSignatureException (bad/missing HMAC)
• WebhookNotReceivedException (webhook request was not received)

Security Notes

• Verify webhook HMAC before use input data.
• Whitelist OxaPay IPs on your firewall (ask support).
• Use HTTPS everywhere.
• Store keys in .env, not code.
• Rotate keys regularly.

Testing (safe & offline)

This package uses Pest, PHPUnit, and Orchestra Testbench for testing.
Dependencies are already listed under require-dev in composer.json.

Run tests with composer:

composer test

Run tests with pest:

vendor/bin/pest

Compatibility

• Laravel 8–9 → PHP 8.0+
• Laravel 10 → PHP 8.1+
• Laravel 11–12 → PHP 8.2+

Security

If you discover a security vulnerability, please email contact@oxapay.com.
Do not disclose publicly until it has been fixed.

Contributing

Pull requests are welcome. For major changes, open an issue first.
Run coding standards & static analysis before PR:

composer cs-fix
composer phpstan
composer test

License

Apache-2.0 — see LICENSE.

Changelog

See CHANGELOG.md for version history.

OxaPay Made with ♥ for Laravel.