PHPackages                             liquidafy/liquidafy-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. liquidafy/liquidafy-php

ActiveLibrary[API Development](/categories/api)

liquidafy/liquidafy-php
=======================

Liquidafy PHP SDK — crypto-native checkout for LATAM merchants (charges, withdrawals, refunds, webhooks, FX).

v1.1.0(1mo ago)001[4 PRs](https://github.com/liquidafy/liquidafy-php/pulls)MITPHPPHP >=8.1CI passing

Since Jun 12Pushed 1w agoCompare

[ Source](https://github.com/liquidafy/liquidafy-php)[ Packagist](https://packagist.org/packages/liquidafy/liquidafy-php)[ Docs](https://liquidafy.com)[ RSS](/packages/liquidafy-liquidafy-php/feed)WikiDiscussions main Synced 2w ago

READMEChangelogDependencies (6)Versions (6)Used By (0)

Liquidafy SDK — PHP
===================

[](#liquidafy-sdk--php)

> Hand-crafted PHP SDK for the [Liquidafy](https://liquidafy.com) API — crypto-native checkout for LATAM merchants. Composer: `liquidafy/liquidafy-php`. Base library for the Magento and WooCommerce plugins.

[![CI](https://github.com/liquidafy/liquidafy-php/actions/workflows/ci.yml/badge.svg)](https://github.com/liquidafy/liquidafy-php/actions/workflows/ci.yml)[![Packagist Version](https://camo.githubusercontent.com/bce2ac20673d532c698e236813e2c4cd1a76853e6d3c7f19086270697e58242f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6c69717569646166792f6c69717569646166792d706870)](https://packagist.org/packages/liquidafy/liquidafy-php)[![License: MIT](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)

Installation
------------

[](#installation)

```
composer require liquidafy/liquidafy-php
```

Requirements / support matrix
-----------------------------

[](#requirements--support-matrix)

PHP8.1, 8.2, 8.3 (CI-tested)HTTPGuzzle 7 (only runtime dependency)Liquidafy API version`2026-05-01` (pinned via `Liquidafy-API-Version`)SDK version1.0.0 (SemVer, independent of the API version)Sandbox is selected automatically by the key prefix: `lr_test_...` runs in test mode against your sandbox data; `lr_live_...` is production. Keep keys in environment configuration — never commit them, never use a secret key in a browser.

Quick start
-----------

[](#quick-start)

```
$liquidafy = new \Liquidafy\Client(getenv('LIQUIDAFY_API_KEY')); // lr_live_... or lr_test_...
```

Optional configuration:

```
$liquidafy = new \Liquidafy\Client(getenv('LIQUIDAFY_API_KEY'), [
    'base_url'               => 'https://api.liquidafy.com', // default
    'timeout'                => 30,    // seconds
    'max_retries'            => 3,     // network / 5xx / 429 only — never other 4xx
    'retry_initial_delay_ms' => 1000,  // backoff: 1s, 2s, 4s (+ jitter)
    'telemetry'              => true,  // PHP/OS info in User-Agent
]);
```

### 1. Create a charge (with idempotency)

[](#1-create-a-charge-with-idempotency)

```
use Liquidafy\Exception\LiquidafyAPIError;

try {
    $charge = $liquidafy->charges->create([
        'amount'      => '100.00',          // money is ALWAYS a decimal string — never a float
        'currency'    => 'USDT',
        'description' => 'Pedido #1234',
        'metadata'    => ['order_id' => '1234'],
    ], [
        'idempotency_key' => 'order-1234',  // safe to retry end-to-end
    ]);

    echo $charge->checkout_url;             // hosted pay page
    echo $charge->deposit_address;          // unique on-chain address
} catch (LiquidafyAPIError $e) {
    // $e->getErrorCode(), $e->getHttpStatus(), $e->getRequestId()
    error_log('Liquidafy error: ' . $e->getMessage());
}
```

### 2. Verify a webhook

[](#2-verify-a-webhook)

Always pass the **raw** request body — re-encoding the JSON breaks the HMAC.

```
$payload   = file_get_contents('php://input');
$sigHeader = $_SERVER['HTTP_LIQUIDAFY_SIGNATURE'] ?? '';

try {
    $event = \Liquidafy\Webhook::constructEvent(
        $payload,
        $sigHeader,
        getenv('LIQUIDAFY_WEBHOOK_SECRET'),  // from webhookEndpoints->create() / rotateSecret()
        300                                  // replay tolerance in seconds (default)
    );
} catch (\Liquidafy\Exception\SignatureVerificationException $e) {
    http_response_code(400);
    exit;
}

if ($event->type === 'charge.confirmed') {
    $charge = $event->data->object;
    // mark order $charge->metadata->order_id as paid
}

http_response_code(200);
```

The signature header is `Liquidafy-Signature: t=,v1=`; verification uses constant-time comparison and a ±300s replay window.

### 3. List with auto-pagination

[](#3-list-with-auto-pagination)

```
foreach ($liquidafy->charges->list(['status' => 'confirmed'])->autoPaging() as $charge) {
    echo $charge->id, PHP_EOL;   // fetches next pages lazily via cursor
}
```

API surface
-----------

[](#api-surface)

ResourceMethods`$liquidafy->charges``create`, `get`, `list`, `cancel`, `refund``$liquidafy->withdrawals``create` (crypto/fiat), `get`, `list`, `cancel``$liquidafy->refunds``create($chargeId, …)`, `get`, `list``$liquidafy->webhookEndpoints``create`, `get`, `list`, `update`, `delete`, `rotateSecret`, `disable`, `enable`, `test`, `deliveries``$liquidafy->fx``rates`, `createQuote` / `quote`, `getQuote``$liquidafy->merchants``get('me')`, `update``\Liquidafy\Webhook``constructEvent`, `verifyHeader`, `computeSignature`Errors
------

[](#errors)

All API failures throw `Liquidafy\Exception\LiquidafyAPIError` (or a subclass):

ExceptionWhen`AuthenticationException`401 / 403 — bad key or missing permission`InvalidRequestException`400 / 404 / 409 / 422 — never retried`RateLimitException`429 — `getRetryAfter()` exposes the suggested wait`ApiConnectionException`network failure after retries`SignatureVerificationException`webhook signature failedEvery exception exposes `getErrorCode()`, `getErrorType()`, `getHttpStatus()`, `getRequestId()` and `getErrorBody()`. API keys never appear in messages — only the masked form (`lr_live_***...123`).

Retries
-------

[](#retries)

The SDK automatically retries **network errors, 5xx, and 429** (honoring `Retry-After`) with exponential backoff + jitter — 3 attempts by default. Other 4xx are deterministic and are never retried. Combine with `idempotency_key` so retried mutations are replay-safe server-side.

Telemetry
---------

[](#telemetry)

Requests identify the SDK (`User-Agent: Liquidafy-PHP/1.0.0 (PHP/8.2.x; Linux)`). Identify your app on top of it:

```
$liquidafy->setAppInfo('MeuApp', '1.2.3', 'https://meuapp.com');
```

Disable runtime info with `'telemetry' => false`.

Development
-----------

[](#development)

```
composer install
composer test   # PHPUnit
composer stan   # PHPStan level 8
```

Security
--------

[](#security)

Found a vulnerability? **Never open a public issue.** Report it privately to **** or via GitHub private vulnerability reporting — see [SECURITY.md](SECURITY.md) for scope, supported versions, and response times.

Support
-------

[](#support)

- Bugs and feature requests: [GitHub issues](https://github.com/liquidafy/liquidafy-php/issues)
- Account, API, or integration help:
- API reference: [docs.liquidafy.com](https://docs.liquidafy.com)

License
-------

[](#license)

[MIT](LICENSE) © Liquidafy Labs Ltda

---

[Liquidafy](https://liquidafy.com) — crypto-native checkout gateway for LATAM.

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance95

Actively maintained with recent releases

Popularity1

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

2

Last Release

45d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/885cfad04bb83c59638020511fa44d7d3d656f87b2eaa8787d43b6cbf9815c70?d=identicon)[liquidafy](/maintainers/liquidafy)

---

Top Contributors

[![rafapeixer](https://avatars.githubusercontent.com/u/136999720?v=4)](https://github.com/rafapeixer "rafapeixer (3 commits)")

---

Tags

apisdkcryptopaymentsgatewaycheckouttronUSDTlatamliquidafy

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/liquidafy-liquidafy-php/health.svg)

```
[![Health](https://phpackages.com/badges/liquidafy-liquidafy-php/health.svg)](https://phpackages.com/packages/liquidafy-liquidafy-php)
```

###  Alternatives

[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

293.1k](/packages/eslazarev-wildberries-sdk)[checkout/checkout-sdk-php

Checkout.com SDK for PHP

563.6M14](/packages/checkout-checkout-sdk-php)[resend/resend-php

Resend PHP library.

607.2M47](/packages/resend-resend-php)[files.com/files-php-sdk

Files.com PHP SDK

2481.1k](/packages/filescom-files-php-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)