# Amwal Documentation

> Documentation for Amwal

## Guides
- [👋 Introduction](https://docs.amwal.tech/docs/introduction.md): Amwal is Saudi Arabia’s leading platform for seamless bank installment, empowering merchants and customers with smarter, more flexible ways to pay.
- [🏦 Merchant Integration](https://docs.amwal.tech/docs/integration-keys.md): Learn how to access your Amwal Sandbox and Production API keys from the Merchant Dashboard.
- [🗝️ Sandbox Key](https://docs.amwal.tech/docs/sandbox-integration-keys.md): Learn how to find and use your Amwal Sandbox Key to test services, simulate transactions, and preview checkout flows.
- [ 🔐 Production Key](https://docs.amwal.tech/docs/production-integration-keys.md): Learn how to request, receive, and configure your Amwal Production Key for live installment transactions.
- [🔑 Secret Key](https://docs.amwal.tech/docs/secret-key.md): Learn where to find your Amwal Secret API Key and how to use it securely for server-side integrations.
- [💳 Test Cards](https://docs.amwal.tech/docs/test-cards.md): Use Amwal test cards to simulate installment and Pay in Full transactions in sandbox environments.
- [Overview](https://docs.amwal.tech/docs/plugins-overview.md): Amwal supports a variety of platforms and integration types. To help users find the most relevant documentation, we've organized our docs into main categories
- [Configuration](https://docs.amwal.tech/docs/magento-plugin-configuration.md)
- [Apple pay](https://docs.amwal.tech/docs/apple-pay.md): Amwal Apple Pay offers a seamless, secure, and lightning-fast Installment solution, designed to enhance customer satisfaction and boost your conversion rates. With just a tap, your customers can complete their purchases effortlessly, making checkout smoother than ever.
- [Bank Installments](https://docs.amwal.tech/docs/bank-installment.md): Amwal Bank Installments provide a flexible, secure, and convenient Installment solution, designed to boost customer satisfaction and increase your sales. With easy monthly installments, your customers can enjoy more purchasing power, breaking down large purchases into manageable Installment, making checkout smoother and more affordable.
- [Shopify](https://docs.amwal.tech/docs/shopify-installation-guide.md): Installation Guide
- [Installment Widget](https://docs.amwal.tech/docs/shopify-installment-widget.md): Embed the Amwal Installment Widget on Shopify Product and Cart pages for enhanced customer experience.
- [WooCommerce](https://docs.amwal.tech/docs/woocommerce-installation-guide.md): Installation Guide
- [Configurations](https://docs.amwal.tech/docs/basic-configurations.md)
- [Webhook](https://docs.amwal.tech/docs/woo-webhook.md)
- [Installments Options](https://docs.amwal.tech/docs/installments-options.md)
- [Address Options](https://docs.amwal.tech/docs/address-options.md)
- [Shipping Options](https://docs.amwal.tech/docs/shipping-options.md)
- [Button Options](https://docs.amwal.tech/docs/button-options.md)
- [Styles](https://docs.amwal.tech/docs/styles.md)
- [Offers](https://docs.amwal.tech/docs/offers.md)
- [In-Store Checkout (POS)](https://docs.amwal.tech/docs/pos-in-store.md): Create and confirm Amwal installment payments for in-store POS sales.
- [Transaction Failed Reasons](https://docs.amwal.tech/docs/transaction-failed-reasons.md)
- [Refund an Installment](https://docs.amwal.tech/docs/refund-installment.md): Learn how to process partial and full refunds for installment transactions using the transaction ID with Amwal's API.
- [Idempotency Refunds](https://docs.amwal.tech/docs/idempotency-refunds.md)
- [Webhook](https://docs.amwal.tech/docs/webhook-overview.md): A concise guide for integrating Amwal webhooks into any platform or technology stack.
- [Event Types](https://docs.amwal.tech/docs/webhook-events.md): Overview of supported event types
- [Authentication & Security](https://docs.amwal.tech/docs/webhook-authentication-security.md): Learn about the required headers and security validation steps for Amwal webhook requests.
- [Webhook and API Key Setup](https://docs.amwal.tech/docs/webhook-setup.md): Efficiently set up webhooks and API keys with concise instructions.
- [Receiving Webhook Events](https://docs.amwal.tech/docs/webhooks-receiving.md): Set up and verify webhook endpoints, including payload structure and signature verification.
- [Order Success](https://docs.amwal.tech/docs/webhook-order-success.md): Process order.success webhooks and identify completed payment details.
- [Order Failed](https://docs.amwal.tech/docs/webhook-order-failed.md): Process order.failed webhooks and record failed payment details.
- [Installment Tracker](https://docs.amwal.tech/docs/webhook-installment-tracker.md): Handle the installment_tracker object in webhook events and process approved, pending, and rejected installment decisions.
- [Refund Tracker](https://docs.amwal.tech/docs/webhook-refund-tracker.md): Track refund and partial refund decisions from the order.updated webhook event.
- [ChargeBack](https://docs.amwal.tech/docs/chargeback-dispute.md): Handle chargeback dispute webhook events and use disputed_status to identify the order dispute status.
- [Expired Payment Link](https://docs.amwal.tech/docs/webhook-payment-link-expired.md): Process payment_link.expired webhooks and update expired payment links.
- [Modal Closed](https://docs.amwal.tech/docs/webhook-modal-closed.md): Process modal.closed webhooks and record when a customer closes the payment modal.
- [Event Handling](https://docs.amwal.tech/docs/webhook-handling-events.md): Guide for handling webhook events with concise processing logic and synchronization tips.
- [Verify Signature](https://docs.amwal.tech/docs/verify-signature.md)
- [Implementation Guide](https://docs.amwal.tech/docs/webhook-implementation-example.md): A concise guide to implementing webhooks, including setup, testing, and monitoring.
- [Statement Report](https://docs.amwal.tech/docs/statement-report.md): Export merchant statement reports by date range using the Merchant Statement API.
- [PHP - Composer SDK](https://docs.amwal.tech/docs/php-composer-sdk.md): Integrating Amwal's installment into PHP applications using Composer package.
- [Web-View Integration](https://docs.amwal.tech/docs/web-view-integration.md)
- [Button Positioning Guidelines](https://docs.amwal.tech/docs/button-positioning-guidelines.md)
- [POS](https://docs.amwal.tech/docs/pos.md)
- [Google Analytics](https://docs.amwal.tech/docs/google-analytics-integration.md)
- [Dashboard Overview](https://docs.amwal.tech/docs/merchant-dashboard.md): Explore the Amwal Merchant Platform's dashboard for managing transactions, payouts, and financial activities efficiently.
- [Create a Store](https://docs.amwal.tech/docs/merchant-create-store.md): Learn how to create a store in your Amwal merchant account and use sandbox or production integration keys.
- [Create User](https://docs.amwal.tech/docs/merchant-user-managment.md): Learn how to create users in your Amwal merchant account, assign roles, and manage access permissions.
- [User Roles and Permissions](https://docs.amwal.tech/docs/merchant-user-role.md): Understand Amwal Merchant Dashboard user roles, permissions, and access restrictions.
- [Branch Management Guide](https://docs.amwal.tech/docs/branches-management.md): Learn how to add, edit, activate, deactivate, and search branches in the Amwal Merchant Dashboard.
- [Branch User Management](https://docs.amwal.tech/docs/branch-users-management.md): Learn how to add branch users, assign Supervisor or Cashier roles, and link users to existing or new branches.
- [Create Payment Link](https://docs.amwal.tech/docs/merchant-payment-link.md): Create a production payment link from the Amwal Merchant Dashboard, optionally assign it to a branch, and share the generated link with the customer.
- [Transactions](https://docs.amwal.tech/docs/transactions.md): Learn how to view transaction lists, open transaction details, search payments, and manage refunds in the Amwal Merchant Dashboard.
- [Refund a payment](https://docs.amwal.tech/docs/processing-a-refund.md): Learn how to refund a payment from the Transactions page and review refund limits for Mada and other cards.
- [Statements & Reports](https://docs.amwal.tech/docs/merchant-reports.md): Learn how to access production statements, payout reports, and VAT invoices from the Amwal Merchant Dashboard.
- [Marketing Toolkit](https://docs.amwal.tech/docs/marketting-toolkit.md): Highlight Amwal throughout your main customer touch-points to improve conversion rates and support higher-value transactions
- [Promotional Widget](https://docs.amwal.tech/docs/installment-widget.md): Instructions for integrating Amwal Installments user-Guideline using Amwal Promotional widget.
- [Amwal Installment HTML Integration Guide](https://docs.amwal.tech/docs/installment-html.md): A concise guide for integrating Amwal Installments using HTML, with visual aids.

## API Reference
- [Create Installment link](https://docs.amwal.tech/reference/post_create-installment-links-store-id.md)
- [List Installment links](https://docs.amwal.tech/reference/post_list-installment-links-store-id.md): Retrieve and analyze your online payment transactions including e-commerce orders, invoices, subscriptions, and remote payments. Essential for business reporting, customer management, and financial analysis.  **Environment Selection:** Use the optional `X-Amwal-Key` header to specify environment for filtering transactions.  **Online Specific Features:** - E-commerce order tracking and fulfillment - Invoice management and payment status - Subscription billing and renewal monitoring - Customer payment history and preferences - Revenue analysis and financial reporting  **Common Use Cases:** - Monthly revenue reporting and analysis - Customer payment behavior tracking - Invoice follow-up and collections - Subscription churn and retention analysis - E-commerce performance monitoring - Payment method preference analysis
- [Get Payment Link details](https://docs.amwal.tech/reference/post_installment-link-id-details.md): Get comprehensive information about online payment transactions including customer data, order details, and payment history. Perfect for customer service, order management, and business reporting.  **Online Specific Use Cases:** - Verify order completion for customer inquiries - Generate detailed invoices and receipts - Track subscription payment history - Process online refunds and exchanges - Customer service and dispute resolution - E-commerce order fulfillment tracking - Financial reporting and reconciliation
- [Get transaction details](https://docs.amwal.tech/reference/get_installment-transaction-transaction-id-details.md): Retrieve comprehensive details for a specific online transaction including fees, customer information, payment method details, and merchant information. Essential for customer service, financial reporting, and transaction analysis.  **Online Transaction Features:** - Complete fee breakdown and merchant payout details - Customer address and contact information - Payment method and card issuer details - Transaction status and refund eligibility - Store and merchant business information - Payment link context and callback URLs  **Common Use Cases:** - Customer service inquiries and dispute resolution - Financial reconciliation and reporting - Transaction audit and compliance - Refund processing and eligibility verification - Payment method analysis and reporting
- [Resolve Installment link](https://docs.amwal.tech/reference/post_installment-link-id-resolve.md): Resolve online payment links when customers access payment URLs via email, SMS, or direct sharing. Optimized for web browsers, mobile apps, and online checkout experiences.  **Online Resolution Features:** - Web-optimized payment interface - Mobile-responsive design - Email and SMS confirmation - Digital receipt generation - Customer account creation options - Seamless redirect after payment
- [Refund a transaction](https://docs.amwal.tech/reference/post_installment-refund-transaction-id.md): Process refunds for online transactions including e-commerce orders, invoices, subscriptions, and remote payments. Essential for customer service, order management, and financial reconciliation.  **Online Refund Use Cases:** - Process product returns and exchanges - Handle subscription cancellations and prorations - Resolve customer disputes and chargebacks - Correct billing errors and overcharges - Process goodwill refunds for customer satisfaction - Handle failed deliveries and shipping issues  **Important Notes:** - Online refunds may take 3-5 business days to process depending on payment method - Customers receive email notification with refund reference - Refunds are tracked for financial reporting and reconciliation - Some payment methods (bank transfers) may have longer processing times - Partial refunds are supported for order modifications

## Recipes
- [Process an Installment with Amwal](https://docs.amwal.tech/recipes/process-a-payment-with-amwal.md)