# PHP SDK

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

## Installation <a href="#installation" id="installation"></a>

```bash
composer  require  oxapay/oxapay-php
```

After installing, if you updated autoloaded classes, run:

```bash
composer  dump-autoload  -o
```

### Quick start <a href="#quick-start" id="quick-start"></a>

```php

<?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")

->generateInvoice([

'amount' => 10.5,

'currency' => 'USDT'

]);

// via facade

$res = OxaPay::payment("XXXXXX-XXXXXX-XXXXXX-XXXXXX")

->generateInvoice([

'amount' => 10.5,

'currency' => 'USDT'

]);

print_r($res);
```

### Handling Webhooks (Payments & Payouts) <a href="#handling-webhooks-payments--payouts" id="handling-webhooks-payments--payouts"></a>

```php

<?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 <a href="#available-methods" id="available-methods"></a>

#### 🔹payment <a href="#payment" id="payment"></a>

* `generateInvoice` – Create invoice & get payment URL. [More details](https://docs.oxapay.com/api-reference/payment/generate-invoice)
* `generateWhiteLabel` – White-label payment. [More details](https://docs.oxapay.com/api-reference/payment/generate-white-label)
* `generateStaticAddress` – Create static deposit address. [More details](https://docs.oxapay.com/api-reference/payment/generate-static-address)
* `revokeStaticAddress` – Revoke static address. [More details](https://docs.oxapay.com/api-reference/payment/revoking-static-address)
* `staticAddressList` – List static addresses. [More details](https://docs.oxapay.com/api-reference/payment/static-address-list)
* `information` – Single payment information. [More details](https://docs.oxapay.com/api-reference/payment/payment-information)
* `history` – Payment history list. [More details](https://docs.oxapay.com/api-reference/payment/payment-history)
* `acceptedCurrencies` – Accepted currencies. [More details](https://docs.oxapay.com/api-reference/payment/accepted-currencies)

#### 🔹account <a href="#account" id="account"></a>

* `balance` – Account balance. [More details](https://docs.oxapay.com/api-reference/common/account-balance)

#### 🔹payout <a href="#payout" id="payout"></a>

* `generate` – Request payout. [More details](https://docs.oxapay.com/api-reference/payout/generate-payout)
* `information` – Single payout information. [More details](https://docs.oxapay.com/api-reference/payout/payout-information)
* `history` – Payout history list. [More details](https://docs.oxapay.com/api-reference/payout/payout-history)

#### 🔹exchange <a href="#exchange" id="exchange"></a>

* `swapRequest` – Swap request. [More details](https://docs.oxapay.com/api-reference/swap/swap-request)
* `swapHistory` – Swap history. [More details](https://docs.oxapay.com/api-reference/swap/swap-history)
* `swapPairs` – Swap pairs. [More details](https://docs.oxapay.com/api-reference/swap/swap-pairs)
* `swapCalculate` – Swap pre-calc. [More details](https://docs.oxapay.com/api-reference/swap/swap-calculate)
* `swapRate` – Swap Quote rate. [More details](https://docs.oxapay.com/api-reference/swap/swap-rate)

#### 🔹common <a href="#common" id="common"></a>

* `prices` – Market prices. [More details](https://docs.oxapay.com/api-reference/common/prices)
* `currencies` – Supported crypto. [More details](https://docs.oxapay.com/api-reference/common/supported-currencies)
* `fiats` – Supported fiats. [More details](https://docs.oxapay.com/api-reference/common/supported-fiat-currencies)
* `networks` – Supported networks. [More details](https://docs.oxapay.com/api-reference/common/supported-networks)
* `monitor` – System status. [More details](https://docs.oxapay.com/api-reference/common/system-status)

#### 🔹webhook <a href="#webhook" id="webhook"></a>

* `verify` – Validates `HMAC` header (sha512 of raw body).
* `getData` – Validates `HMAC` header and return webhook data. [More details](https://docs.oxapay.com/webhook)

***

### Exceptions <a href="#exceptions" id="exceptions"></a>

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 <a href="#security-notes" id="security-notes"></a>

* 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) <a href="#testing-safe--offline" id="testing-safe--offline"></a>

This package uses **Pest**, **PHPUnit**, and **Orchestra Testbench** for testing.

Dependencies are already listed under `require-dev` in `composer.json`.

Run tests with composer:

```bash
composer  test
```

Run tests with pest:

```bash
vendor/bin/pest
```

### Compatibility <a href="#compatibility" id="compatibility"></a>

* PHP +8.x

### Security <a href="#security" id="security"></a>

If you discover a security vulnerability, please email <info@oxapay.com>.

Do not disclose publicly until it has been fixed.

### Contributing <a href="#contributing" id="contributing"></a>

Pull requests are welcome. For major changes, open an issue first.

Run coding standards & static analysis before PR:

```bash
composer  cs-fix
composer  phpstan
composer  test
```

### License <a href="#license" id="license"></a>

Apache-2.0 — see [LICENSE](https://github.com/OxaPay/oxapay-php/blob/HEAD/LICENSE).

### Changelog <a href="#changelog" id="changelog"></a>

See [CHANGELOG.md](https://github.com/OxaPay/oxapay-php/blob/HEAD/CHANGELOG.md) for version history.

### To view the OxaPay package on Packagist:

{% embed url="<https://packagist.org/packages/oxapay/oxapay-php>" %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.oxapay.com/welcome-to-oxapay/integrations/sdks/php-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.