Custom Integration

Overview

This guide provides instructions for implementing a custom integration with the Amwal checkout system. For developers who need more flexibility than the standard Vanilla JS implementation, this custom approach allows for deeper integration with your existing codebase.

Getting Started

To integrate Amwal checkout into your custom application, follow these steps:

1. Sign up with Amwal merchant for your country (for KSA, visit https://merchant.sa.amwal.tech/) to obtain a sandbox key or production key
2. Include the npm package and instantiate the amwal-checkout-button web component in your application
3. Configure the component with the necessary properties
4. Handle the appropriate events for your checkout flow

Example Repository and Demo

For a complete working example of the Amwal custom integration:

• Example Repository: https://github.com/amwal-tech/exmaple
• Live Demo: https://amwal-tech.github.io/exmaple

The example repository demonstrates how to implement and customize the Amwal checkout button in various scenarios.

Basic Implementation

Include the Required Scripts

Add the following script to your HTML header:

<script type="module" src="https://cdn.jsdelivr.net/npm/@amwal-checkout-button@latest/dist/checkout/checkout.esm.js"></script>

Add the Checkout Button Component

Add the component to your HTML body:

<amwal-checkout-button
    merchant-key="sandbox-aaa1-bbbb-cccc-dddd-eeee"
    amount="100"
    country-code="SA"
    locale="en"
    dark-mode="off"
    address-required="true">
</amwal-checkout-button>

Handle Checkout Events

Add event listeners to manage the checkout flow:

const checkoutElement = document.querySelector('amwal-checkout-button');
checkoutElement.addEventListener('amwalCheckoutSuccess', ev => console.log(ev.detail));
checkoutElement.addEventListener('amwalAddressUpdate', ev => console.log(ev.detail));
// If address updated and data missing, this fires
checkoutElement.dispatchEvent(new Event('amwalAddressAck'));

Properties

Events

Methods

dismissModal() => Promise<void>

A method to programmatically dismiss the Amwal modal.

Advanced Integration

For more complex integrations, you may want to:

1. Dynamically update properties based on user interactions
2. Implement custom validation before triggering the checkout
3. Handle various checkout states with custom UI feedback

Refer to the example repository for demonstrations of these advanced patterns.

Troubleshooting

Common issues and their solutions:

• Button not displaying: Ensure you've included the script correctly and the component is properly defined
• Checkout not working: Verify your merchant key is correct and you're handling events properly
• Address validation issues: Check your allowedAddressCities, allowedAddressStates, and allowedAddressCountries configurations

For additional help, contact Amwal support or refer to the full documentation.