README

Support us

Compatibility

Requires PHP 8.3 or newer, Laravel 11–13, AdaPayments core 1.1.2 or newer in the 1.x series, and Saloon 4. Composer installs the core dependency automatically. Use a supported, security-patched Laravel release.

Installation and Configuration

(i) Package and dependencies installation

You can install the package via composer:

composer require lido-nation/laravel-adapayments

The AdaPayments core package is installed automatically as a dependency.

(ii) Publishing config and service provides

Publish configurations and service providers via artisan command:

php artisan adapayments:install

php artisan adapayments:install command will create the following files within laravel root directory;

config/adapayments.php
app/Providers/AdapaymentsServiceProvider.php

Register the published App\Providers\AdapaymentsServiceProvider in bootstrap/providers.php on Laravel 11–13. On applications that retain config/app.php provider registration, add it to that file instead:

// bootstrap/providers.php
return [
    App\Providers\AppServiceProvider::class,
    App\Providers\AdapaymentsServiceProvider::class,
];

(iii) configuration (.env)

The published config/adapayments.php will make use of certain environment variables that we will need to configure. Below is a list of variables we will need to configure in our .env file.

//  Ada wallet address to receive payments
PAYMENT_ADDRESS=
PAYMENT_ADDRESS_QR_IMAGE=

// Blockfrost service url and project_id
BLOCKFROST_URL=
BLOCKFROST_PROJECT_ID=
ADAPAYMENTS_NETWORK=Mainnet   # Mainnet, Preview or Preprod; must match Blockfrost

// API Keys for coinapi, coinbase and coinmarketcap
COINAPI_API_KEY=             // optional
COINBASE_API_KEY=            // optional
COINMARKETCAP_API_KEY=       // optional

Usage

Here are a few short examples of what you can do:

(i) Converting currencies

Note that all the functions presented below will take a parameter of amounts being converted. By default the value is set to 1, hence equates represents live exchange rate.

from global helpers

$usdAmount = ada_to_usd(7);
$adaAmount = usd_to_ada(7);

from class instance

use Lidonation\AdapaymentsLaravel\Adapayments;

$adaPayments = new Adapayments();

$usdAmount = $adaPayments->adaToUsd(10); $adaAmount = $adaPayments->usdToAda(10);


- #### from the serivce container

$adaPayments = app()->adapayments;

$usdAmount = $adaPayments->adaToUsd(5); $adaAmount = $adaPayments->usdToAda(5);



## Testing

Test via composer command;

composer test


## Credits

- [Michael Teddy Ochara](https://github.com/michaelteddy008)
- [All Contributors](../../contributors)

The optional browser-asset regression test requires Node.js and runs with
`node --test tests/js/wallet-storage.test.cjs`.

## Browser checkout and release safety

Published assets are under `public/vendor/adapayments`. Load `js/app.js` as an ES module only on a checkout page with the core wallet partial, `#popup`, and `#itemDetails` containing `#total`, `#currency` and `#submitButton`. The wallet library is pinned to Lucid 0.10.7 on unpkg; browsers need access to that CDN and its transitive module/WASM URLs. Review that third-party dependency and your CSP before release.

- `ADA` totals are ADA, not USD. `USD` totals fetch a fresh USD-to-ADA quote at submission and round up to a lovelace. Both accept positive decimals with at most six places. Native currencies must be the full policy id plus asset-name hex, with a positive integer total in base units; Lucid adds any required minimum ADA to token outputs.
- Wallet enable is requested once. Mainnet/testnet mismatches are rejected, but CIP-30 network id 0 cannot distinguish Preview from Preprod. The operator and wallet user must select the same test network. Configure `ADAPAYMENTS_NETWORK` and the matching Blockfrost URL/project before publishing the checkout.
- The installed application provider opts into public routes. The Blockfrost proxy is GET-only, allowlisted to the read paths used by Lucid, and limited to 60 requests/minute per IP. Quotes are limited to 30/minute per IP. Configure a shared Laravel cache and trusted proxies correctly; apply application authentication or tighter perimeter limits where needed. The proxy uses Laravel configuration, including after `config:cache`, and preserves upstream error status codes. It does not forward browser credentials or accept arbitrary destinations.
- Signed transactions are submitted with CIP-30 `submitTx`, not through the proxy. A returned transaction hash means submitted, not confirmed or an order paid. Verify the transaction, destination, asset, amount and confirmations server-side before fulfilling an order. This package does not implement that fulfillment contract.
- Publishing with `--force` can overwrite an application's customized checkout. Back up and reconcile published files instead. Previously published config must add the network key; absent configuration defaults to Mainnet.
- This drops PHP 8.1/8.2, Laravel 10 and Saloon 3 support. Release as a new major version. A real wallet/provider/on-chain acceptance test remains required before production use.

Run all browser regression contracts with `node --test tests/js/*.cjs`.

lido-nation / laravel-adapayments

Package info

Security

Statistics