Vanilla JS Installation

To set up your website to use Amwal checkout button, follow the following steps:

Sign up with amwal merchant for your country. for KSA, visit https://merchant.sa.amwal.tech to obtain a sandbox key or production key

include the npm package js into your website and instantate amwal-checkout-button web component

in the header tag, include:

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

in the body tag, include:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0" />
    <title>My Cool Store</title>
    <script type="module" src="https://cdn.jsdelivr.net/npm/amwal-checkout-button@latest/dist/checkout/checkout.esm.js"></script>
  </head>
  <body>
    <amwal-checkout-button
      merchant-id="sandbox-amwal-4e876d00-a50e-482c-a6e1-a1a9df400ce5"
      amount="20"
      country-code="SA"
      locale="en"
      dark-mode="off"
      address-required="true"/>
    <script>
      const amwalCheckoutElement = document.querySelector('amwal-checkout-button');
      amwalCheckoutElement.addEventListener('amwalCheckoutSuccess', ev => console.log(ev.detail) )
      amwalCheckoutButtonElement.addEventListener('amwalAddressUpdate', ev => {
        console.log(ev.detail);
        // if address-requried and address-handshake are true,
        // fire this event after updating shipping methods and taxes based on the address
        amwalCheckoutButtonElement.dispatchEvent( new Event('amwalAddressAck') )
      })
    </script>
  </body>
</html>

Properties

Property	Attribute	Description	Type	Default
`addressHandshake`	`address-handshake`	addressHandshake specifies if address event and ack is activated ("true" or "false")	`boolean`	`false`
`addressRequired`	`address-required`	addressRequired specifies if shipping address is required or not ("true" or "false")	`boolean`	`true`
`allowedAddressCities`	--	allowedAddressCities specifies an array of allowed states for the address example {"SA":{"XX1":["Riady","Afif"],"XX2":["Jeddah","Makkah"]},"US":{"US1":["San Jose","San Francisco"],"US2":["New york"]}}	`{ [index: string]: CitySpecs; }`	`undefined`
`allowedAddressCountries`	--	allowedAddressCountries specifies an array of allowed countries for the address	`string[]`	`undefined`
`allowedAddressStates`	--	allowedAddressStates specifies an array of allowed states for the address example {"SA":{"XX1":"State 1","XX2":"State 2"},"US":{"US1":"State 1","US2":"State 2"}}	`{ [index: string]: StateSpecs; }`	`undefined`
`amount`	`amount`	The amount of money to charge the customer	`number`	`undefined`
`countryCode`	`country-code`	The country code of the merchant (e.g. SA)	`string`	`"SA"`
`darkMode`	`dark-mode`	Dark Mode: - on: turns on dark mode - off: turns on light mode - auto: use customer preference for dark mode	`"auto" \| "off" \| "on"`	`"off"`
`debug`	`debug`	debug flag for verbose printing of debug messages	`boolean`	`false`
`disabled`	`disabled`	disables the checkout button	`boolean`	`false`
`discount`	`discount`	discount specifies any discount to be applied	`number`	`0`
`emailRequired`	`email-required`	emailRequired specifies if email address is required or not ("true" or "false"). Can only be true if addressRequired is true.	`boolean`	`false`
`enablePreCheckoutTrigger`	`enable-pre-checkout-trigger`	enable triggering a pre checkout click event to do initial tasks such as adding items to carts	`boolean`	`false`
`enablePrePayTrigger`	`enable-pre-pay-trigger`	enable triggering a pre pay event to do final task such as order creation	`boolean`	`false`
`initialAddress`	--	initialAddress specifies a default address, Country field is country code (two letter ISO country code)	`IAddress`	`undefined`
`initialEmail`	`initial-email`	initialEmail specifies a default email	`string`	`undefined`
`initialPhoneNumber`	`initial-phone-number`	initialPhone specifies a default phone number	`string`	`undefined`
`label`	`label`	the label of the button. Either checkout for final checkout or quicky-buy for per product buy	`"checkout" \| "quick-buy"`	`"checkout"`
`locale`	`locale`	the language of the plugin. supported languages are Arabic ("ar") and English ("en")	`string`	`"en"`
`merchantId`	`merchant-id`	merchantId is the key to use obtained from https://merchant.sa.amwal.tech	`string`	`undefined`
`refId`	`ref-id`	refId a unique identifier to be included in the payment transaction	`string`	`undefined`
`shippingMethods`	--	shippingMethods an array of shipping methods	`IShippingMethod[]`	`[]`
`showContinueShoppingButton`	`show-continue-shopping-button`	debug flag for verbose printing of debug messages	`boolean`	`false`
`taxes`	`taxes`	taxes specifies any additional taxes	`number`	`0`
`testEnvironment`	`test-environment`	this is an internal testing feature. don't specify	`string`	`undefined`

Events

Event	Description	Type
`amwalAddressUpdate`	amwalAddressUpdate is a dom event fired on address selection.	`CustomEvent<IAddress>`
`amwalCheckoutSuccess`	amwalCheckoutSuccess is a dom event fired on success of payment. the event has orderId field which can be used to lookup transaction status at https://backend.sa.amwal.tech	`CustomEvent<AmwalCheckoutStatus>`
`amwalDismissed`	amwalDismissed is a dom event fired when the amwal modal or popup window is dismissed, event.detail indicates if it's successfull or not (boolean)	`CustomEvent<any>`
`amwalPreCheckoutTrigger`	amwalPreCheckoutTrigger is a dom event fired once amwal checkout button is clicked before a transaction is created. It is enabled if enablePreCheckoutTrigger is set. It waits for either amwalPreCheckoutTriggerAck or amwalPreCheckoutTriggerError events to be sent back before proceeding with the normal checkout flow.	`CustomEvent<ITransactionDetails>`
`amwalPrePayTrigger`	amwalPrePayTrigger is a dom event fired once payment button is clicked before payment is processed. It is enabled if enablePrePayTrigger is set. It waits for either amwalPrePayTriggerAck or amwalPrePayTriggerError events to be sent back before proceeding to payment or aborting respectively.	`CustomEvent<ITransactionDetails>`
`updateOrderOnPaymentsuccess`	updateOrderOnPaymentsuccess is a dom event fired on success of payment. the event has orderId field which can be used to lookup transaction status at https://backend.sa.amwal.tech	`CustomEvent<AmwalCheckoutStatus>`

📘
Example
Below is a full example of how to use Amwal Checkout in a vanilla javascript app

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0" />
    <title>My Cool Store</title>
    <script type="module" src="https://cdn.jsdelivr.net/npm/amwal-checkout-button@latest/dist/checkout/checkout.esm.js"></script>
  </head>
  <body>
    <amwal-checkout-button
      merchant-id="sandbox-amwal-4e876d00-a50e-482c-a6e1-a1a9df400ce5"
      amount="20"
      country-code="SA"
      locale="en"
      dark-mode="off"
      address-required="true"/>
    <script>
      const amwalCheckoutElement = document.querySelector('amwal-checkout-button');
      amwalCheckoutElement.addEventListener('amwalCheckoutSuccess', ev => console.log(ev.detail) )
      amwalCheckoutButtonElement.addEventListener('amwalAddressUpdate', ev => {
        console.log(ev.detail);
        // if address-requried and address-handshake are true,
        // fire this event after updating shipping methods and taxes based on the address
        amwalCheckoutButtonElement.dispatchEvent( new Event('amwalAddressAck') )
      })
    </script>
  </body>
</html>

Properties

Events

📘Example

📘
Example