Developer Quickstart
Integrate Amwal Bank Installments into your storefront using our official HTML web components or direct server-to-server REST API.
1. Get Your Sandbox Key
Before writing code, retrieve your Sandbox Key from the Amwal Merchant Dashboard:
- Select your Store and open the Integration tab.
- Copy your Sandbox Key to use as your
merchant-idorX-Amwal-Key.
2. Drop-in HTML Widget Integration
Include the official Amwal web component bundle from jsDelivr in your page <head> and embed the <amwal-widget> or <amwal-checkout-button> element:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Amwal Drop-in Integration</title>
<!-- 1. Load the official Amwal SDK Module -->
<script
type="module"
src="https://cdn.jsdelivr.net/npm/@amwaljs/checkout-button@latest/dist/checkout/checkout.esm.js"
></script>
</head>
<body>
<!-- 2. Product / Cart Page: Amwal Promotional Widget -->
<div class="product-pricing">
<h3>iPhone 15 Pro - 4,200.00 SAR</h3>
<amwal-widget id="amwal-widget"></amwal-widget>
</div>
<!-- 3. Checkout Page: Drop-in Checkout Button -->
<div class="checkout-actions">
<amwal-checkout-button
amount="4200.00"
currency="SAR"
country-code="SA"
merchant-id="YOUR_SANDBOX_KEY"
locale="en"
enable-installments="true"
></amwal-checkout-button>
</div>
<script>
// A. Configure the Promotional Widget
const widget = document.getElementById("amwal-widget");
if (widget) {
widget.config = {
price: 4200,
installmentsCount: 6,
currency: "SAR"
};
widget.locale = "en";
widget.showMonthlyPayment = true;
widget.showGreenBorder = true;
widget.showPopularBadge = true;
}
// B. Listen for Payment Events on the Checkout Button
const checkoutBtn = document.querySelector('amwal-checkout-button');
if (checkoutBtn) {
checkoutBtn.addEventListener('amwal-success', (event) => {
console.log('Payment Successful:', event.detail);
// event.detail includes transaction_id, status, installment details
window.location.href = `/order-confirmation?tx_id=${event.detail.transaction_id}`;
});
checkoutBtn.addEventListener('amwal-error', (event) => {
console.error('Payment Error:', event.detail);
});
}
</script>
</body>
</html>Key Widget Options
| Property | Type | Description |
|---|---|---|
price | Number | Transaction amount shown in monthly breakdowns (e.g. 4200). |
installmentsCount | Number | Default installment tenure (e.g. 3, 6, 12, 24). |
currency | String | ISO currency code (SAR). |
locale | String | Language display ("en" or "ar"). |
showMonthlyPayment | Boolean | Displays the calculated monthly payment badge. |
showGreenBorder | Boolean | Renders the distinctive Amwal green highlight border. |
3. Server-Side Payment Links (REST API)
If you prefer generating hosted payment URLs from your backend server:
curl -X POST https://backend.sa.amwal.tech/payment_links/YOUR_STORE_ID/create \
-H "Authorization: YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 4200.00,
"phoneNumber": "+966501234567",
"title": "Order #98231",
"singleUse": true
}'Sample Response:
{
"status": "success",
"payment_link_id": "9493559e-xxxx-xxxx-xxxx-yyyyyyyyyyyy",
"url": "https://pay.amwal.tech/i/9493559e-xxxx-xxxx",
"amount": 4200.00,
"currency": "SAR"
}4. Test in Sandbox
Use our simulated Test Cards to test successful installment plans (3, 6, 12, 24 months) and verify authorization webhook events.