PHP SDK

composer require qasimha/php-sdk

require __DIR__ . '/vendor/autoload.php';   // frameworks load this for you

use Qasimha\Client;
use Qasimha\Config;

QASIMHA_API_KEY=sk_test_...
QASIMHA_PUBLISHABLE_KEY=pk_test_...
QASIMHA_WEBHOOK_SECRET=whsec_...

use Qasimha\Client;
use Qasimha\Config;

$qasimha = new Client(Config::fromApiKey((string) getenv('QASIMHA_API_KEY'), [
    'webhookSecret'   => getenv('QASIMHA_WEBHOOK_SECRET') ?: null,
    'publishableKey'  => getenv('QASIMHA_PUBLISHABLE_KEY') ?: null,
    'language'        => 'ar',                 // "en" (default) or "ar"
    'userAgentSuffix' => 'my-store/2.4.0',
]));

// Shortcut with the same options:
$qasimha = Client::create((string) getenv('QASIMHA_API_KEY'), ['language' => 'ar']);

// Guzzle 7
$config = Config::fromApiKey($key, [
    'httpClient'     => new \GuzzleHttp\Client(['timeout' => 30, 'connect_timeout' => 10, 'allow_redirects' => false]),
    'requestFactory' => new \GuzzleHttp\Psr7\HttpFactory(),
    'streamFactory'  => new \GuzzleHttp\Psr7\HttpFactory(),
]);

// Symfony HttpClient: Psr18Client is the client and both factories
$config = Config::fromApiKey($key, [
    'httpClient' => new \Symfony\Component\HttpClient\Psr18Client(
        \Symfony\Component\HttpClient\HttpClient::create(['timeout' => 30, 'max_redirects' => 0])
    ),
]);

use Qasimha\Exception\DuplicateOrderReferenceException;
use Qasimha\Exception\OrderDeclinedException;
use Qasimha\Exception\ValidationException;

try {
    $session = $qasimha->checkout()->createSession([
        'orderReferenceId' => 'ORDER-12345',       // your own id, unique per order, ≤ 255 chars
        'totalAmount'      => 1302.10,
        'taxAmount'        => 173.10,
        'shippingAmount'   => 25.00,
        'discountAmount'   => 50.00,
        'description'      => 'Order #12345',
        'items' => [
            ['referenceId' => 'SKU-1', 'name' => 'Wireless Headphones', 'type' => 'physical',
             'sku' => 'SKU-1', 'quantity' => 1, 'unitPrice' => 899.00, 'totalAmount' => 899.00],
            ['referenceId' => 'SKU-2', 'name' => 'USB-C Cable', 'type' => 'physical',
             'sku' => 'SKU-2', 'quantity' => 3, 'unitPrice' => 45.00, 'totalAmount' => 135.00],
            ['referenceId' => 'SKU-3', 'name' => 'Extended Warranty', 'type' => 'digital',
             'sku' => 'SKU-3', 'quantity' => 1, 'unitPrice' => 120.00, 'totalAmount' => 120.00],
        ],
        'consumer' => ['firstName' => 'Noura', 'lastName' => 'Al-Shammari',
                       'phoneNumber' => '+9665XXXXXXXX', 'email' => '[email protected]'],
        'shippingAddress' => ['firstName' => 'Noura', 'lastName' => 'Al-Shammari', 'line1' => 'King Fahd Rd',
                              'city' => 'Riyadh', 'postalCode' => '12345', 'countryCode' => 'SA'],
        'merchantUrl' => [
            'success' => 'https://shop.example/checkout/qasimha/return?order=ORDER-12345',
            'failure' => 'https://shop.example/checkout/qasimha/return?order=ORDER-12345',
            'cancel'  => 'https://shop.example/cart',
        ],
    ]);

    saveQasimhaOrderId('ORDER-12345', $session->orderId);   // every later call uses this id
    header('Location: ' . $session->paymentUrl, true, 303);
    exit;
} catch (ValidationException $e) {
    // $e->errors: list of FieldError with ->field ("Items[1].TotalAmount") and ->message
} catch (DuplicateOrderReferenceException $e) {
    // already open: $e->existingOrderId, $e->existingPaymentUrl (may be null)
} catch (OrderDeclinedException $e) {
    // $e->orderId exists but was not approved: offer another payment method
}

use Qasimha\Request\CreateSessionRequest;

$request = CreateSessionRequest::fromArray($input);   // validates now
$session = $qasimha->checkout()->createSession($request);

// In store: the customer opens the link on their phone. consumer.email is required.
$pos = $qasimha->checkout()->createPosSession([
    'orderReferenceId' => 'POS-0001',
    'totalAmount'      => 899.00,                 // = Σ items[].totalAmount
    'items' => [
        ['referenceId' => 'SKU-1', 'name' => 'Wireless Headphones', 'type' => 'physical',
         'quantity' => 1, 'unitPrice' => 899.00, 'totalAmount' => 899.00],
    ],
    'consumer' => ['firstName' => 'Noura', 'lastName' => 'Al-Shammari',
                   'phoneNumber' => '+9665XXXXXXXX', 'email' => '[email protected]'],
]);
$pos->checkoutUrl;   // hosted page; $pos->status is AwaitingCheckout

// Scan to pay: render the URL as a QR code.
$qr = $qasimha->checkout()->createQrSession([
    'orderReferenceId' => 'QR-0001',
    'totalAmount'      => 899.00,
    'items' => [
        ['referenceId' => 'SKU-1', 'name' => 'Wireless Headphones', 'type' => 'physical',
         'quantity' => 1, 'unitPrice' => 899.00, 'totalAmount' => 899.00],
    ],
]);
$qr->qrCodeUrl;

use Qasimha\Model\Enum\OrderStatus;

$orderId = (string) ($_GET['orderId'] ?? '');     // or the id you stored at creation
$order = $qasimha->orders()->get($orderId);

if ($order->orderReferenceId === $expectedReference && $order->status === OrderStatus::CONFIRMED) {
    // Paid its first instalment: mark your order paid. Call fulfill() when you ship.
}

use Qasimha\Exception\WebhookSignatureException;
use Qasimha\Webhook\EventType;

$rawBody = file_get_contents('php://input');
$headers = function_exists('getallheaders') ? getallheaders() : $_SERVER;

try {
    $event = $qasimha->webhooks()->constructEvent($rawBody, $headers);
} catch (WebhookSignatureException $e) {
    http_response_code(400);   // $e->reason names the failure
    exit;
}

if (alreadyProcessed($event->id)) {          // retries repeat the event id
    http_response_code(204);
    exit;
}

if ($event->type !== EventType::PING) {
    $order = $event->orderId !== null
        ? $qasimha->orders()->get($event->orderId)
        : $qasimha->orders()->getByReference((string) $event->orderReferenceId);
    // update your order from $order->status
}
http_response_code(204);

$qasimha->webhooks()->constructEvent(
    string $rawBody,
    array $headers,
    ?string $secret = null,
    array $options = [],          // ['tolerance' => 300, 'now' => time()]
): WebhookEvent;

$qasimha->webhooks()->verifySignature(
    string $rawBody,
    ?string $signatureHeader,
    ?string $secret = null,
    array $options = [],          // ['timestampHeader' => ..., 'tolerance' => 300, 'now' => time()]
): void;                          // throws on failure

'qasimha' => [
    'key'             => env('QASIMHA_API_KEY'),
    'webhook_secret'  => env('QASIMHA_WEBHOOK_SECRET'),
    'publishable_key' => env('QASIMHA_PUBLISHABLE_KEY'),
],

use Illuminate\Support\Facades\Log;
use Qasimha\Client;
use Qasimha\Config;

public function register(): void
{
    $this->app->singleton(Client::class, function (): Client {
        $secrets = array_filter([                       // drops unset (null) and empty values
            'webhookSecret'  => config('services.qasimha.webhook_secret'),
            'publishableKey' => config('services.qasimha.publishable_key'),
        ]);

        return new Client(Config::fromApiKey((string) config('services.qasimha.key'), $secrets + [
            'language'        => 'ar',
            'userAgentSuffix' => 'my-store/1.0.0',
            'logger'          => static function (string $level, string $message, array $fields): void {
                Log::log($level === 'warn' ? 'warning' : $level, 'qasimha: ' . $message, $fields);
            },
        ]));
    });
}

use Illuminate\Http\Request;
use Qasimha\Client;
use Qasimha\Exception\WebhookSignatureException;

Route::post('/webhooks/qasimha', function (Request $request, Client $qasimha) {
    try {
        $event = $qasimha->webhooks()->constructEvent($request->getContent(), $request->headers->all());
    } catch (WebhookSignatureException $e) {
        return response('', 400);
    }
    // de-duplicate on $event->id, then queue the work
    return response()->noContent();
});

services:
    _defaults:
        autowire: true
        autoconfigure: true

    Qasimha\Config:
        factory: ['Qasimha\Config', 'fromApiKey']
        arguments:
            - '%env(QASIMHA_API_KEY)%'
            - { webhookSecret: '%env(QASIMHA_WEBHOOK_SECRET)%', language: 'ar' }

    Qasimha\Client: ~

namespace App\Qasimha;

use Psr\Log\LoggerInterface;
use Qasimha\Client;

final class QasimhaClientFactory
{
    public function __construct(private readonly LoggerInterface $logger)
    {
    }

    public function create(string $apiKey, string $webhookSecret): Client
    {
        return Client::create($apiKey, [
            'webhookSecret' => $webhookSecret,
            'logger' => function (string $level, string $message, array $fields): void {
                $this->logger->log($level === 'warn' ? 'warning' : $level, 'qasimha: ' . $message, $fields);
            },
        ]);
    }
}

services:
    # replaces the Qasimha\Config and Qasimha\Client entries above
    Qasimha\Client:
        factory: ['@App\Qasimha\QasimhaClientFactory', 'create']
        arguments: ['%env(QASIMHA_API_KEY)%', '%env(QASIMHA_WEBHOOK_SECRET)%']

namespace App\Controller;

use Qasimha\Client;
use Qasimha\Exception\WebhookSignatureException;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;   // Symfony 6.4+; older: Annotation\Route

final class QasimhaWebhookController
{
    public function __construct(private readonly Client $qasimha)
    {
    }

    #[Route('/webhooks/qasimha', methods: ['POST'])]
    public function __invoke(Request $request): Response
    {
        try {
            $event = $this->qasimha->webhooks()->constructEvent($request->getContent(), $request->headers->all());
        } catch (WebhookSignatureException $e) {
            return new Response('', 400);
        }
        // de-duplicate on $event->id, then dispatch the work (for example with Messenger)
        return new Response('', 204);
    }
}

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

$qasimha = Qasimha\Client::create((string) getenv('QASIMHA_API_KEY'), [
    'webhookSecret' => getenv('QASIMHA_WEBHOOK_SECRET') ?: null,
]);

$rawBody = file_get_contents('php://input');
$headers = function_exists('getallheaders') ? getallheaders() : $_SERVER;
$event = $qasimha->webhooks()->constructEvent($rawBody, $headers);

$orders = $qasimha->orders();

$orders->fulfill($orderId);                                          // ship everything outstanding
$orders->fulfill($orderId, ['shippedAmount' => 1200.00, 'shippingCompany' => 'Aramex',
                            'trackingNumber' => 'ARX123', 'trackingUrl' => 'https://shop.example/track/ARX123']);
$orders->refund($orderId, ['amount' => 300.00, 'reason' => 'Customer return']);
$orders->cancel($orderId);                                           // voids an unfulfilled order
$orders->capture($orderId);                                          // New / Approved orders only

use Qasimha\Model\Enum\OrderStatus;

$order = $qasimha->orders()->get($orderId);
$order = $qasimha->orders()->getByReference('ORDER-12345');   // same Order

$page = $qasimha->orders()->list(['status' => OrderStatus::CONFIRMED, 'search' => 'Noura', 'page' => 1, 'pageSize' => 20]);
foreach ($page->items as $row) {          // OrderSummary
    echo $row->orderReferenceId, ' ', $row->status, ' ', $row->totalAmount, PHP_EOL;
}
$page->pagination->totalPages;

$counts = $qasimha->orders()->counts();   // $counts->all, ->approved, ->authorised, ->captured, ->refunded, ->cancelled

$contract = $qasimha->orders()->contract($orderId);
file_put_contents('/tmp/' . ($contract->fileName ?? 'contract.pdf'), $contract->bytes);

Order
  id, orderReferenceId, status, paymentType, channel, checkoutChannel,
  totalAmount, taxAmount, shippingAmount, discountAmount, currencyCode, countryCode, description,
  instalments, downPaymentAmount, approvedAmount,
  capturedAmount, fulfilledAmount, refundedAmount, refundableAmount, collectedAmount, voidedAmount, reversedAmount,
  paymentUrl, providerSessionId, providerOrderId,
  createdAt, confirmedAt, fulfilledAt, voidedAt, reversedAt, settledAt, checkoutExpiresAt, expiresAt,
  ejarContractNumber, notificationLanguage, contractNumber,
  customer       ?Customer        id, name, email, phone, nationalId (always null: the API does not return it)
  items          OrderItem[]      referenceId, name, type, sku, quantity, unitPrice, totalAmount, taxAmount, discountAmount, imageUrl
  installments   Installment[]    sequence, dueDate, amount, principal, profit, status, paidAmount, paidAt, providerRef
  fulfillments   Fulfillment[]    id, amount, currencyCode, shippingCompany, trackingNumber, trackingUrl, providerCaptureId, createdAt
  reversals      Reversal[]       id, amount, currencyCode, comment, fulfillmentId, providerRefundId, createdAt
  voids          OrderVoid[]      id, amount, currencyCode, reason, providerCancelId, createdAt
  statusHistory  StatusChange[]   fromStatus, toStatus, trigger, metadata, createdAt
  raw, requestId, replayed

OrderSummary
  id, orderReferenceId, status, policyCode, policyType, totalAmount, currencyCode, createdAt,
  customerId, customerName, customerEmail, customerPhone, instalments, channel,
  capturedAmount, refundedAmount, ejarContractNumber, raw

$links = $qasimha->checkoutLinks();

$link = $links->create([
    'amount'           => 250.00,
    'channel'          => 'Link',               // default; the customer gets the link by SMS
    'phone'            => '+9665XXXXXXXX',
    'language'         => 'ar',
    'orderReferenceId' => 'ORDER-12346',
]);
$link->url;          // hosted page
$link->expiresAt;    // two hours from now

$qr = $links->create(['amount' => 250.00, 'channel' => 'Qr']);   // render $qr->url as a QR code

$links->get($link->id);        // status, completed, declined, decisionStatus, expiresAt
$links->list();                // the 50 most recent, each with a waiting flag
$links->cancel($link->id);

$page = $qasimha->settlements()->list(['page' => 1, 'pageSize' => 20]);
foreach ($page->items as $settlement) {
    // id, providerSettlementId, amount, currencyCode, settledAt, status, orderCount, raw
}

$overview = $qasimha->settlements()->overview();
// totalSettled, count, lastSettlement (array), settlementCycle, settlementModel,
// minimumSettlementAmount, remainingForNextSettlement, raw

use Qasimha\Webhook\EventType;

$endpoints = $qasimha->webhookEndpoints();

$created = $endpoints->create([
    'url'         => 'https://shop.example/webhooks/qasimha',
    'description' => 'Production store',
    'events'      => [EventType::ORDER_CONFIRMED, EventType::ORDER_REFUNDED],   // omit for every event
]);
storeSecret($created->secret);   // whsec_..., returned once; this is your webhookSecret
$created->secretHint;            // its last characters, to tell secrets apart later

$endpoints->list();
$endpoints->get($created->id);
$endpoints->update($created->id, ['isActive' => false]);
$endpoints->delete($created->id);

$rotated = $endpoints->rotateSecret($created->id);   // new ->secret; old one valid until ->previousSecretExpiresAt
$ping = $endpoints->ping($created->id);              // queues a signed "ping"; $ping->eventId
$page = $endpoints->listDeliveries($created->id, ['status' => 'Failed', 'pageSize' => 20]);
$endpoints->replayDelivery($created->id, $page->items[0]->id);

$quote = $qasimha->checkout()->getPlans(1200.00, ['lang' => 'ar']);

if ($quote->plans === []) {
    // outside [minAmount, maxAmount], or no active policy: show nothing
}
foreach ($quote->plans as $plan) {
    // $plan->instalments, $plan->frequency, $plan->instalmentAmount,
    // $plan->firstInstalmentAmount, $plan->lastInstalmentAmount,
    // $plan->feesIncludingVat, $plan->totalPayable, $plan->shariaCompliant
}

$qasimha->checkout()->getPlans('1200.00', ['publishableKey' => 'pk_test_...']);   // key per call

use Qasimha\Exception\QasimhaException;
use Qasimha\Exception\ValidationException;

try {
    $qasimha->orders()->refund($orderId, ['amount' => 300.00]);
} catch (ValidationException $e) {
    if ($e->errorCode === 'AMOUNT_EXCEEDED') {
        // more than refundableAmount
    }
} catch (QasimhaException $e) {
    error_log(sprintf('Qasimha %s %s request %s', $e->httpStatus ?? '-', $e->errorCode ?? '-', $e->requestId ?? '-'));
    throw $e;
}

'logger' => function (string $level, string $message, array $fields): void {
    // The SDK uses "info" and "warn". PSR-3 loggers (Monolog, Laravel, Symfony) call it "warning".
    $psrLogger->log($level === 'warn' ? 'warning' : $level, 'qasimha: ' . $message, $fields);
},

use App\Http\Controllers\QasimhaController;
use Illuminate\Support\Facades\Route;

Route::post('/checkout/qasimha/{reference}', [QasimhaController::class, 'checkout'])->name('qasimha.checkout');
Route::get('/checkout/qasimha/return', [QasimhaController::class, 'handleReturn'])->name('qasimha.return');
Route::post('/webhooks/qasimha', [QasimhaController::class, 'webhook']);

Route::middleware('auth')->prefix('admin/orders/{reference}')->group(function () {
    Route::post('ship', [QasimhaController::class, 'ship']);
    Route::post('refund', [QasimhaController::class, 'refund']);
    Route::post('cancel', [QasimhaController::class, 'cancel']);
});

<?php

namespace App\Http\Controllers;

use App\Models\Order;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Log;
use Qasimha\Client;
use Qasimha\Exception\DuplicateOrderReferenceException;
use Qasimha\Exception\OrderDeclinedException;
use Qasimha\Exception\QasimhaException;
use Qasimha\Exception\ValidationException;
use Qasimha\Exception\WebhookSignatureException;
use Qasimha\Model\Enum\OrderStatus;
use Qasimha\Webhook\EventType;

class QasimhaController extends Controller
{
    private const PAID = [OrderStatus::CONFIRMED, OrderStatus::PARTIALLY_FULFILLED, OrderStatus::FULLY_FULFILLED];

    public function __construct(private readonly Client $qasimha)
    {
    }

    // 1. Create the session and send the shopper to the hosted checkout.
    public function checkout(string $reference): RedirectResponse
    {
        $order = Order::where('reference', $reference)->firstOrFail();
        $returnUrl = route('qasimha.return', ['order' => $order->reference]);

        try {
            $session = $this->qasimha->checkout()->createSession([
                'orderReferenceId' => $order->reference,
                // Build these from your cart. Strings avoid float rounding.
                'totalAmount'    => '1302.10',   // 1154.00 + 173.10 + 25.00 − 50.00
                'taxAmount'      => '173.10',
                'shippingAmount' => '25.00',
                'discountAmount' => '50.00',
                'items' => [
                    ['referenceId' => 'SKU-1', 'name' => 'Wireless Headphones', 'type' => 'physical',
                     'quantity' => 1, 'unitPrice' => '899.00', 'totalAmount' => '899.00'],
                    ['referenceId' => 'SKU-2', 'name' => 'USB-C Cable', 'type' => 'physical',
                     'quantity' => 3, 'unitPrice' => '45.00', 'totalAmount' => '135.00'],
                    ['referenceId' => 'SKU-3', 'name' => 'Extended Warranty', 'type' => 'digital',
                     'quantity' => 1, 'unitPrice' => '120.00', 'totalAmount' => '120.00'],
                ],
                'consumer' => ['firstName' => 'Noura', 'lastName' => 'Al-Shammari',
                               'phoneNumber' => '+9665XXXXXXXX', 'email' => '[email protected]'],
                'shippingAddress' => ['firstName' => 'Noura', 'lastName' => 'Al-Shammari',
                                      'line1' => 'King Fahd Rd', 'city' => 'Riyadh', 'countryCode' => 'SA'],
                'merchantUrl' => ['success' => $returnUrl, 'failure' => $returnUrl, 'cancel' => url('/cart')],
            ]);
        } catch (DuplicateOrderReferenceException $e) {
            if ($e->existingPaymentUrl !== null) {
                return redirect()->away($e->existingPaymentUrl);   // checkout already open
            }
            return redirect('/cart')->withErrors(['payment' => 'This order already has a Qasimha checkout.']);
        } catch (OrderDeclinedException) {
            return redirect('/cart')->withErrors(['payment' => 'Please choose another payment method.']);
        } catch (ValidationException $e) {
            Log::error('QASIMHA_SESSION_REFUSED', [
                'reference' => $order->reference,
                'code' => $e->errorCode,
                'fields' => array_map(fn ($f) => $f->field . ': ' . $f->message, $e->errors),
                'requestId' => $e->requestId,
            ]);
            return redirect('/cart')->withErrors(['payment' => 'Qasimha is unavailable for this basket.']);
        }

        $order->update(['qasimha_order_id' => $session->orderId, 'status' => 'awaiting_payment']);

        return redirect()->away((string) $session->paymentUrl);
    }

    // 2. The shopper comes back. The query string is not proof: read the order.
    public function handleReturn(Request $request): RedirectResponse
    {
        $order = Order::where('reference', (string) $request->query('order'))
            ->whereNotNull('qasimha_order_id')
            ->firstOrFail();

        $remote = $this->qasimha->orders()->get($order->qasimha_order_id);

        if ($remote->orderReferenceId === $order->reference && in_array($remote->status, self::PAID, true)) {
            $order->update(['status' => 'paid']);
            return redirect('/orders/' . $order->reference);
        }

        return redirect('/cart')->withErrors(['payment' => 'The payment was not completed.']);
    }

    // 3. Webhooks: verify the raw body, answer fast, de-duplicate, then read the order.
    public function webhook(Request $request): Response
    {
        try {
            $event = $this->qasimha->webhooks()->constructEvent($request->getContent(), $request->headers->all());
        } catch (WebhookSignatureException $e) {
            Log::warning('QASIMHA_WEBHOOK_REJECTED', ['reason' => $e->reason]);
            return response('', 400);
        }

        if ($event->type === EventType::PING || $event->id === null) {
            return response()->noContent();
        }
        if (!Cache::add('qasimha:event:' . $event->id, true, now()->addDays(3))) {
            return response()->noContent();   // a retry of an event already handled
        }

        $orderId = $event->orderId;
        $reference = $event->orderReferenceId;

        dispatch(static function () use ($orderId, $reference): void {
            $qasimha = app(Client::class);
            $remote = $orderId !== null
                ? $qasimha->orders()->get($orderId)
                : $qasimha->orders()->getByReference((string) $reference);

            $local = Order::where('reference', $remote->orderReferenceId)->first();
            if ($local !== null && $local->status !== 'paid' && in_array($remote->status, self::PAID, true)) {
                $local->update(['status' => 'paid']);
            }
            if ($local !== null && in_array($remote->status, [OrderStatus::DECLINED, OrderStatus::EXPIRED], true)) {
                $local->update(['status' => 'payment_failed']);
            }
        })->afterResponse();

        return response()->noContent();
    }

    // 4. Staff actions.
    public function ship(Request $request, string $reference): JsonResponse
    {
        $options = array_filter([
            'shippedAmount'   => $request->input('amount'),     // omit to ship everything outstanding
            'shippingCompany' => $request->input('carrier'),
            'trackingNumber'  => $request->input('tracking'),
        ], fn ($value) => $value !== null && $value !== '');

        return $this->act(fn (string $id) => $this->qasimha->orders()->fulfill($id, $options), $reference);
    }

    public function refund(Request $request, string $reference): JsonResponse
    {
        $body = ['amount' => $request->input('amount'), 'reason' => $request->input('reason')];

        return $this->act(fn (string $id) => $this->qasimha->orders()->refund($id, array_filter($body)), $reference);
    }

    public function cancel(string $reference): JsonResponse
    {
        return $this->act(fn (string $id) => $this->qasimha->orders()->cancel($id), $reference);
    }

    private function act(callable $call, string $reference): JsonResponse
    {
        $order = Order::where('reference', $reference)->whereNotNull('qasimha_order_id')->firstOrFail();

        try {
            $result = $call($order->qasimha_order_id);
        } catch (ValidationException $e) {        // INVALID_STATUS, AMOUNT_EXCEEDED, local checks ...
            return response()->json(['error' => $e->errorCode, 'message' => $e->getMessage()], 422);
        } catch (QasimhaException $e) {
            return response()->json(['error' => $e->errorCode, 'requestId' => $e->requestId], 502);
        }

        Log::info('QASIMHA_ORDER_ACTION', ['reference' => $reference, 'status' => $result->status,
                                           'requestId' => $result->requestId, 'actor' => auth()->id()]);

        return response()->json(['status' => $result->status]);
    }
}