# Docs

- [Amwal Tech](/): Amwal is a payment solution that provides 0% bank installments up to 24 months, passkey login, and seamless checkout experience.
- Get Started

  - **Overview**
  - [Introduction](/get-started/introduction): Amwal is Saudi Arabia's leading bank installment platform, giving merchants and customers smarter, more flexible ways to pay.

  - **For Merchants**
  - [Merchant Onboarding](/get-started/merchant-onboarding): Step-by-step guide to registering your business, creating stores, and activating Amwal installments.
  - [Dashboard Overview](/get-started/dashboard-overview): Learn how to monitor transactions, create payment links, issue refunds, and download financial statements.
  - [Branches & User Roles](/get-started/branches-and-users): Understand Amwal Merchant Dashboard user roles, permissions, multi-branch hierarchy, and POS workflows.

  - **For Developers**
  - [Developer Quickstart](/get-started/quickstart): Get up and running with Amwal Bank Installments, Promotional Widgets, and Checkout in under 5 minutes.
  - [Integration & API Keys](/get-started/integration-keys): Learn how to access, configure, and authenticate with your Sandbox, Production, and Secret API keys from the Amwal Merchant Dashboard.
  - [Test Cards](/get-started/test-cards): Simulate bank installments and 1-click checkout in sandbox with Amwal partner bank test cards.

  - **Next Steps**
  - [E-Commerce Plugins](/get-started/plugins-overview): Connect Amwal installments to Shopify, WooCommerce, Magento, or Salla with official turnkey plugins.
  - [Webhooks Overview](/get-started/webhooks-overview): Receive real-time payment updates, installment decisions, and refund notifications via Amwal webhooks.
- Merchant Portal
  - [Dashboard Overview](/merchant/dashboard-overview): Comprehensive guide to navigating the Amwal Merchant Portal, monitoring live financial performance, managing multi-store operations, and accessing developer tooling.
  - [Create a Store](/merchant/create-store): Step-by-step guide to provisioning independent online stores, managing isolated API keys, and meeting Saudi regulatory compliance.
  - Users
    - [User Management](/merchant/users/user-management): Comprehensive guide to inviting team members, assigning role-based access permissions, managing branch staff, and auditing portal activity.
    - [User Roles and Permissions](/merchant/users/user-roles): In-depth reference for Amwal Merchant Dashboard role-based access controls (RBAC), permission tiers, operational boundaries, and security restrictions.
  - Branches
    - [Branch Management](/merchant/branches/branch-management): Configure physical retail locations, assign in-store supervisors and cashiers, and manage location-based sales tracking in the Amwal Merchant Portal.
    - [Branch Users](/merchant/branches/branch-users): Guide to onboarding retail cashiers and supervisors, assigning them to physical branches, and managing staff rotation across store locations.
  - [Create Payment Link](/merchant/create-payment-link): Complete operational guide to generating dynamic SMS payment links, social commerce URLs, and in-store checkout QR codes in the Amwal Merchant Dashboard.
  - Transactions
    - [Transactions](/merchant/transactions/transaction-history): In-depth guide to auditing real-time transaction feeds, inspecting payment drilldown metadata, monitoring authorization statuses, and searching order records.
    - [Refund a Payment](/merchant/transactions/processing-refunds): Comprehensive operational guide to issuing payment refunds, understanding SAMA card scheme timeframes, fee reconciliations, and installment reversals.
  - [Statements & Reports](/merchant/statements-and-reports): Access, filter, and export daily settlement payout statements, SARIE interbank reconciliations, and ZATCA-compliant electronic VAT tax invoices.
- E-Commerce Plugins
  - [Plugins Overview](/plugins/overview): Turnkey e-commerce plugins for Shopify, WooCommerce, and Adobe Magento with 0% Bank Installments and 1-Click Checkout.
  - Shopify
    - [Shopify Installation](/plugins/shopify/installation): Step-by-step guide to installing and activating the official Amwal Payment app on Shopify to enable 0% bank installments.
    - [Shopify Installment Widget](/plugins/shopify/installment-widget): Step-by-step guide to embedding and customizing the Amwal 0% bank installment promotional widget on Shopify Product & Cart pages using Online Store 2.0 Theme App Extensions.
  - WooCommerce
    - [WooCommerce Installation](/plugins/woocommerce/installation): Step-by-step guide to installing and activating the official Amwal Checkout plugin on WordPress WooCommerce.
    - [WooCommerce Configuration](/plugins/woocommerce/configuration): Complete configuration guide for the Amwal WooCommerce plugin, covering API credentials, webhooks, 0% installments, address mapping, and custom styles.
  - Magento
    - [Magento 2 Installation](/plugins/magento/installation): Step-by-step installation guide for the Amwal Payments extension on Adobe Commerce (Magento 2) via Composer and CLI.
    - [Magento 2 Plugin Configuration](/plugins/magento/configuration): Complete step-by-step configuration guide for the Amwal Payments extension on Adobe Commerce (Magento 2), covering 0% bank installments, Apple Pay, webhooks, and cron synchronization.
    - [Magento 2 Online Refunds](/plugins/magento/refunds): Step-by-step guide to issuing online refunds and credit memos in Adobe Commerce (Magento 2) with automated Amwal payment reversals.
- Custom Integration
  - [PHP Composer SDK](/custom-integration/php-composer-sdk): Integrate Amwal Bank Installments into PHP backend applications using the official Composer package.
  - [Web-View Integration](/custom-integration/web-view-integration): Embed Amwal Bank Installments in iOS, Android, and React Native mobile applications using WebViews.
  - [React Installation](/custom-integration/react-installation): Integrate Amwal Web Components and Checkout Button in React, Next.js, and modern TypeScript frontends.
  - [Point of Sale (POS)](/custom-integration/pos): Integrate in-store point of sale terminals, cash registers, and dynamic QR bank installment flows using the Amwal POS component.
  - [Google Analytics Integration](/custom-integration/google-analytics): Track Amwal Quick Checkout button clicks, conversion rates, and e-commerce events in Google Analytics 4 (GA4).
- Marketing Toolkit
  - [Marketing Toolkit Overview](/marketing-toolkit/overview): Highlight Amwal Bank Installments throughout your customer touchpoints to improve conversion rates and increase Average Order Value (AOV).
  - [Button Positioning Guidelines](/marketing-toolkit/button-positioning-guidelines): Best practices and recommended placements for Amwal Quick Checkout and Installment widgets across your store.
  - [Promotional Widget Integration](/marketing-toolkit/installment-widget): Embed and configure the dynamic Amwal Promotional Installment Widget on your store.
  - [HTML Content Approach](/marketing-toolkit/installment-html): Build custom promotional messaging, banners, and modal triggers using standard HTML and CSS.
- API Reference
  - Overview
    - [API Quickstart Overview](/api-reference/overview): Brief introduction to Amwal Online Checkout and In-Store POS APIs, authorization headers, and environment keys.
    - [Online Checkout](/api-reference/overview/online-checkout): Complete step-by-step developer flow for web e-commerce bank installment links, callbacks, and webhooks.
    - [In-Store Checkout (POS)](/api-reference/overview/pos-in-store): Create and confirm Amwal bank installment payments for in-store physical retail POS systems and cash registers.
  - [Create Installment Link](/api-reference/create-installment-link): Comprehensive API reference for generating online and in-store bank installment payment links.
  - [Installment Link Listings](/api-reference/list-installment-links): Retrieve, filter, and paginate through created payment links and check their settlement status.
  - [Transaction Status](/api-reference/transaction-status): Complete overview of Amwal payment link statuses, transaction lifecycle stages, and state transition workflows.
  - [Transaction Failed Reasons](/api-reference/transaction-failed-reasons): Reference list of error messages and decline codes returned by issuing bank gateways for unsuccessful transactions.
  - [Get Payment Link Details](/api-reference/payment-link-details): Retrieve complete details, customer data, and current payment status for a specific payment link.
  - [Get Transaction Details](/api-reference/transaction-details): Retrieve transaction-level settlement details, bank approvals, card brand, and fee breakdown.
  - [Refund an Installment](/api-reference/refund-installment): Process full and partial refunds for completed installment transactions using the Amwal Refund API.
  - [Resolve Installment Link](/api-reference/resolve-installment-link): Resolve online installment payment links when customers access payment URLs via mobile apps or direct browser sessions.
  - Webhook
    - [Webhook Overview](/api-reference/webhooks/overview): Overview of Amwal real-time webhook architecture, HTTP delivery lifecycle, error handling, and retry mechanisms.
    - [Webhook Setup](/api-reference/webhooks/setup): Register your webhook endpoint and obtain your RSA public verification key via the Amwal Registration API.
    - [Webhook Signature Verification](/api-reference/webhooks/signature-verification): Cryptographic specification and multi-language implementation for validating Amwal RSA-PSS SHA-256 webhook signatures.
    - [Webhook Implementation Examples](/api-reference/webhooks/implementation-examples): Complete, production-ready backend webhook receiver examples with RSA-PSS SHA-256 signature verification and event routing in Node.js, Python, PHP, and Go.
    - [Webhook Event Types](/api-reference/webhooks/events): Complete JSON payload schemas, parameters breakdown, and event definitions for all supported Amwal webhook events.
  - [Statement Report API](/api-reference/statement-report): Export merchant settlement reports and payout data programmatically by date range using the Reports API.
- [API Playground](/api-playground): Execute real-time and simulated cURL requests against Amwal installment endpoints, import requests, and generate client SDK snippets.
- Troubleshooting
  - [Overview](/troubleshoot): Diagnostic guides, common error codes, and step-by-step resolution playbooks for Amwal payments, bank installment approvals, APIs, and e-commerce plugins.
  - Payments & Checkout
    - [Troubleshooting Declined Installments](/troubleshoot/payments-and-checkout/declined-installments): How to diagnose and resolve bank installment plan declines during checkout on Amwal Tech.
    - [Troubleshooting Card Eligibility Issues](/troubleshoot/payments-and-checkout/card-not-eligible): Resolving card eligibility errors, distinguishing Mada debit cards from credit cards, and handling SAMA compliance rules.
    - [Troubleshooting Passkey & Biometric Authentication](/troubleshoot/payments-and-checkout/passkey-and-biometrics): Resolving biometric FaceID/TouchID passkey login failures and configuring SMS OTP fallbacks.
    - [Troubleshooting Payment Link & QR Code Errors](/troubleshoot/payments-and-checkout/payment-link-errors): Diagnosing expired payment links, single-use restrictions, and dynamic in-store POS QR resolution issues.
  - API & Webhooks
    - [Troubleshooting API Authentication & Key Errors](/troubleshoot/api-and-webhooks/authentication-errors): Diagnosing 401 Unauthorized, 403 Forbidden, and Sandbox/Production credential mismatches on Amwal REST APIs.
    - [Troubleshooting Webhook Signature Verification Failures](/troubleshoot/api-and-webhooks/webhook-signature-failures): Resolving RSA-PSS SHA-256 signature verification mismatches when receiving webhook events from Amwal Tech.
    - [Troubleshooting Webhook Delivery & Timeout Failures](/troubleshoot/api-and-webhooks/webhook-delivery-issues): Diagnosing webhook delivery retries, timeout thresholds, SSL certificate requirements, and firewall IP whitelisting.
    - [Troubleshooting Rate Limits & Duplicate Transactions](/troubleshoot/api-and-webhooks/rate-limits-and-idempotency): Handling HTTP 429 Too Many Requests, implementing exponential backoffs, and preventing duplicate charges with idempotency guards.
  - E-Commerce Plugins
    - [Troubleshooting Shopify Integration](/troubleshoot/plugins/shopify-troubleshooting): Comprehensive diagnostic playbook for resolving Shopify payment gateway activation errors, currency mismatches, and Theme App Extension widget rendering.
    - [Troubleshooting WooCommerce Integration](/troubleshoot/plugins/woocommerce-troubleshooting): Diagnostic guide for resolving WooCommerce order status synchronization, cURL SSL errors on shared hosting, refund API secret requirements, and WordPress caching conflicts.
    - [Troubleshooting Magento 2 Integration](/troubleshoot/plugins/magento-troubleshooting): Comprehensive diagnostic playbook for resolving Magento 2 DI compilation errors, missing secret key credit memo failures, cron job pending order synchronization, and Apple Pay visibility issues.
  - Merchant Portal & Payouts
    - [Troubleshooting Settlement & Payout Delays](/troubleshoot/merchant-portal/settlement-payout-delays): Understanding the T+2/T+3 settlement cycle, SARIE interbank transfer schedules, SAMA compliance verifications, and ZATCA VAT tax invoice downloads.
    - [Troubleshooting Refund Failures & Partial Adjustments](/troubleshoot/merchant-portal/refund-issues): Diagnosing insufficient merchant balance errors, SAMA card scheme refund processing windows, and partial installment schedule recalculations.
    - [Troubleshooting User Roles, Permissions & 2FA](/troubleshoot/merchant-portal/access-and-permissions): Resolving Merchant Portal permission errors, cashier restrictions, branch isolation, and Two-Factor Authentication (2FA) recovery.