React Installation

This is a react wrapper for the amwal-checkout-button package allowing it to be used directly in react projects

Installation

npm i amwal-checkout-button-react

Usage

import { AmwalCheckoutButton } from 'amwal-checkout-button-react'
import React, { useEffect, useRef, useState } from 'react';

const ReactPage= () => {
    const amwalRef = useRef<any>();
    const [shippment, setShippment] = useState<any>([{ "id": "1", "label": "Free shipping", "price": 0 }]);
    ...
    <AmwalCheckoutButton merchantId="sandbox-amwal-4e876d00-a50e-482c-a6e1-a1a9df400ce5" amount="20" countryCode="SA"
    locale="ar" darkMode="auto"
    addressRequired={true}
    emailRequired={false}
    shippingMethods={shippment}
    addressHandshake
    onAmwalAddressUpdate={(event) => {
        setShippment([{ "id": "1", "label": "Free shipping", "price": 0 }])
        setTimeout(() => {
        amwalRef.current.dispatchEvent(new Event('amwalAddressAck'))
        }, 1000)

    }}/>
    ...
}

Properties

PropertyAttributeDescriptionTypeDefault
addressHandshakeaddress-handshakeaddressHandshake specifies if address event and ack is activated ("true" or "false")booleanfalse
addressRequiredaddress-requiredaddressRequired specifies if shipping address is required or not ("true" or "false")booleantrue
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 addressstring[]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
amountamountThe amount of money to charge the customernumberundefined
countryCodecountry-codeThe country code of the merchant (e.g. SA)string"SA"
darkModedark-modeDark Mode: - on: turns on dark mode - off: turns on light mode - auto: use customer preference for dark mode"auto" | "off" | "on""off"
debugdebugdebug flag for verbose printing of debug messagesbooleanfalse
disableddisableddisables the checkout buttonbooleanfalse
discountdiscountdiscount specifies any discount to be appliednumber0
discountDescriptiondiscount-descriptiondiscountDescription provides description for the discountstringundefined
feesfeesfees specifies any fees to be appliednumber0
feesDescriptionfees-descriptionfeesDescription provides description for the feesstringundefined
emailRequiredemail-requiredemailRequired specifies if email address is required or not ("true" or "false"). Can only be true if addressRequired is true.booleanfalse
enablePreCheckoutTriggerenable-pre-checkout-triggerenable triggering a pre checkout click event to do initial tasks such as adding items to cartsbooleanfalse
enablePrePayTriggerenable-pre-pay-triggerenable triggering a pre pay event to do final task such as order creationbooleanfalse
initialAddress--initialAddress specifies a default address, Country field is country code (two letter ISO country code)IAddressundefined
initialEmailinitial-emailinitialEmail specifies a default emailstringundefined
initialPhoneNumberinitial-phone-numberinitialPhone specifies a default phone numberstringundefined
initialFirstNameinitial-first-nameinitialFirstName specifies a default first namestringundefined
initial-first-nameinitial-last-nameinitialLastName specifies a default last namestringundefined
labellabelthe label of the button. Either checkout for final checkout or quicky-buy for per product buy"checkout" | "quick-buy""checkout"
localelocalethe language of the plugin. supported languages are Arabic ("ar") and English ("en")string"en"
merchantIdmerchant-idmerchantId is the key to use obtained from https://merchant.sa.amwal.techstringundefined
refIdref-idrefId a unique identifier to be included in the payment transactionstringundefined
uniqueRefunique-refuniqueRef a boolean to enforce the uniqueness of refIdbooleanfalse
shippingMethods--shippingMethods an array of shipping methodsIShippingMethod[][]
showContinueShoppingButtonshow-continue-shopping-buttondebug flag for verbose printing of debug messagesbooleanfalse
taxestaxestaxes specifies any additional taxesnumber0
testEnvironmenttest-environmentthis is an internal testing feature. don't specifystringundefined
installmentOptionsUrlinstallment-options-urlThe installment options url is URL for the checkout page in the merchant websitestringundefined
postcodeOptionalCountriesinstallment-options-urlenable postal code required optionstring[]undefined

Events

EventDescriptionType
amwalAddressUpdateamwalAddressUpdate is a dom event fired on address selection. It waits for either amwalAddressAck or amwalAddressTriggerError events to be sent back before proceeding to address update or aborting respectively.CustomEvent<IAddress>
amwalCheckoutSuccessamwalCheckoutSuccess 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.techCustomEvent<AmwalCheckoutStatus>
amwalDismissedamwalDismissed 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>
amwalPreCheckoutTriggeramwalPreCheckoutTrigger 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>
amwalPrePayTriggeramwalPrePayTrigger 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>
updateOrderOnPaymentsuccessupdateOrderOnPaymentsuccess 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.techCustomEvent<AmwalCheckoutStatus>

📘

References

You can find references regarding attributes and events Vanilla JS Installation Page