README

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

PHP: 8.0+
Docs: https://docs.oxapay.com

Installation

composer require oxapay/oxapay-php

After installing, if you updated autoloaded classes, run:

composer dump-autoload -o

Quick start

<?php
require __DIR__ . '/vendor/autoload.php';

use OxaPay\PHP\OxaPayManager;
use OxaPay\PHP\Support\Facades\OxaPay;

// via static method
$oxapay = new OxaPayManager(timeout: 10);
$res = $oxapay->payment("XXXXXX-XXXXXX-XXXXXX-XXXXXX")
              ->createInvoice([
                  'amount' => 10.5,
                  'currency' => 'USDT'
              ]);

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

print_r($res);

Handling Webhooks (Payments & Payouts)

<?php
require __DIR__ . '/../vendor/autoload.php';

use OxaPay\PHP\Support\Facades\OxaPay;
use OxaPay\PHP\Exceptions\WebhookSignatureException;


// use for merchant webhook endpoint
try {
    $data = OxaPay::webhook(merchantApiKey: "XXXXXX-XXXXXX-XXXXXX-XXXXXX")->getData();
    // ...
} catch (WebhookSignatureException $e) {
    // ...
}

// use for payout webhook endpoint
try {
    $data = OxaPay::webhook(payoutApiKey: "XXXXXX-XXXXXX-XXXXXX-XXXXXX")->getData();
    // ...
} catch (WebhookSignatureException $e) {
    // ...
}

// Use when your endpoint is used for both webhook merchant and payout
try {
    $data = OxaPay::webhook(merchantApiKey: "XXXXXX-XXXXXX-XXXXXX-XXXXXX", payoutApiKey: "XXXXXX-XXXXXX-XXXXXX-XXXXXX")->getData();
    // ...
} catch (WebhookSignatureException $e) {
    // ...
}

// or you can get data without verify HMAC
$data = 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\PHP\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

PHP +8.x

Security

If you discover a security vulnerability, please email security@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 PHP.

oxapay / oxapay-php

Maintainers

Details