Bill payment API integration with PHP and Laravel

<?php
// PHP 8.2+ with cURL. Keep this class on your server.
declare(strict_types=1);

final class RizPayRequestError extends RuntimeException
{
    public function __construct(public readonly string $apiCode, public readonly int $httpStatus)
    {
        parent::__construct('Request not confirmed. Reconcile the stored order before retrying.');
    }
}

final class RizPaySandbox
{
    private const BASE_URL = 'https://my.rizpay.app/api/partners/sandbox/v1';
    private string $key;

    public function __construct(?string $key = null)
    {
        $this->key = $key ?? (getenv('RIZPAY_API_KEY') ?: '');
        if (!str_starts_with($this->key, 'sk_test_')) {
            throw new InvalidArgumentException('A sandbox key is required.');
        }
    }

    public function listAirtime(string $network = 'MTN', int $page = 1): array
    {
        if (!in_array($network, ['MTN', 'AIRTEL', 'GLO', '9MOBILE'], true) || $page < 1) {
            throw new InvalidArgumentException('Check the network and page.');
        }
        return $this->request('/products/airtimes?' . http_build_query(['network' => $network, 'page' => $page]));
    }

    public function purchaseAirtime(string $productId, string $network, string $phoneNumber, string $amount, string $externalReference): array
    {
        if (!preg_match('/\A\d{10}[A-Za-z0-9]{6}\z/', $externalReference) ||
            !preg_match('/\Aprd_\d+\z/', $productId) ||
            !in_array($network, ['MTN', 'AIRTEL', 'GLO', '9MOBILE'], true) ||
            !preg_match('/\A0[789]\d{9}\z/', $phoneNumber) ||
            !preg_match('/\A\d+\.\d{2}\z/', $amount)) {
            throw new InvalidArgumentException('Check the stored order fields.');
        }
        return $this->request('/purchases', [
            'product_id' => $productId, 'network' => $network,
            'phone_number' => $phoneNumber, 'amount' => $amount,
            'external_reference' => $externalReference,
        ]);
    }

    public function findOrder(string $reference): array
    {
        if (!preg_match('/\A\d{10}[A-Za-z0-9]{6}\z/', $reference)) {
            throw new InvalidArgumentException('Invalid reference.');
        }
        return $this->request('/account/transactions/' . $reference);
    }

    public function purchaseStatus(string $id): array
    {
        if (!preg_match('/\Atxn_[A-Za-z0-9-]+\z/', $id)) {
            throw new InvalidArgumentException('Invalid transaction.');
        }
        return $this->request('/purchases/' . $id);
    }

    private function request(string $path, ?array $body = null): array
    {
        $curl = curl_init(self::BASE_URL . $path);
        curl_setopt_array($curl, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_FOLLOWLOCATION => false,
            CURLOPT_CONNECTTIMEOUT => 5,
            CURLOPT_TIMEOUT => 20,
            CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $this->key, 'Content-Type: application/json'],
        ]);
        if ($body !== null) {
            curl_setopt($curl, CURLOPT_POST, true);
            curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($body, JSON_THROW_ON_ERROR));
        }
        $raw = curl_exec($curl);
        $status = (int) curl_getinfo($curl, CURLINFO_HTTP_CODE);
        curl_close($curl);
        if ($raw === false) {
            throw new RizPayRequestError('UNCONFIRMED_RESPONSE', 0);
        }
        try {
            $json = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
        } catch (JsonException) {
            throw new RizPayRequestError('UNRECOGNIZED_RESPONSE', $status);
        }
        if (!is_array($json)) {
            throw new RizPayRequestError('UNRECOGNIZED_RESPONSE', $status);
        }
        if ($status < 200 || $status >= 300) {
            $code = $json['error']['code'] ?? 'API_ERROR';
            if (!is_string($code) || !preg_match('/\A[A-Z_]{3,60}\z/', $code)) {
                $code = 'API_ERROR';
            }
            throw new RizPayRequestError($code, $status);
        }
        return $json;
    }
}