PHP - Composer SDK
Integrate Amwal Bank Installments and payment link creation into any PHP application or framework (Laravel, Symfony, WordPress) using the official Amwal PHP Composer package.
1. Installation
Install the package via Composer in your project root:
composer require amwal/amwal-php2. Initialization
Initialize the Amwal client with your API credentials:
<?php
require_once __DIR__ . '/vendor/autoload.php';
use Amwal\AmwalClient;
$amwal = new AmwalClient([
'api_key' => 'YOUR_SECRET_KEY',
'merchant_id' => 'YOUR_MERCHANT_ID',
'environment' => 'sandbox', // Use 'production' for live stores
]);3. Create Installment Payment Link
Generate a hosted payment URL to send to customers via email, SMS, or redirect:
<?php
$paymentData = [
'amount' => 1200.00,
'currency' => 'SAR',
'order_id' => 'ORD-98231',
'client_first_name' => 'Ahmed',
'client_last_name' => 'Al-Rashid',
'client_email' => 'ahmed@example.com',
'client_phone_number'=> '+966501234567',
'callback_url' => 'https://mystore.sa/checkout/callback',
'single_use' => true,
'description' => 'iPhone 15 Pro (6 Months Installment Plan)',
];
try {
$payment = $amwal->createPaymentLink($paymentData);
// Redirect customer to the secure Amwal payment URL
header('Location: ' . $payment['payment_url']);
exit;
} catch (\Exception $e) {
echo 'Error creating payment link: ' . $e->getMessage();
}4. Query Transaction Details
Retrieve complete transaction status, fee breakdown, and installment tenure:
<?php
$transactionId = 'amwal-trx-98421';
try {
$transactionDetails = $amwal->getPaymentDetails($transactionId);
if ($transactionDetails['status'] === 'success') {
echo 'Order Paid Successfully. Installment Plan: ' . $transactionDetails['installment_plan'];
}
} catch (\Exception $e) {
echo 'Error: ' . $e->getMessage();
}5. Refund a Transaction
Process full or partial refunds for an installment transaction:
<?php
$transactionId = 'txn_894120';
$refundData = [
'refund_amount' => 300.00,
'reason' => 'Customer returned item #2',
];
try {
// transaction_id is passed separately, not inside $refundData — the API
// takes it as a URL path parameter (POST /transactions/refund/{transaction_id}/).
$refundResult = $amwal->refundPayment($transactionId, $refundData);
echo 'Refund reference: ' . $refundResult['key'];
} catch (\Exception $e) {
echo 'Refund error: ' . $e->getMessage();
}Reading the updated balance
The refund response only confirms status and returns a key (the
gateway's refund reference number) — it does not include the transaction's
new status or remaining balance. Call $amwal->getPaymentDetails($transactionId)
afterward to read the updated status (partially refunded or refunded)
and refunded amount. See Refund an Installment
for the full response and error shapes.