# amwal-checkout ## 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` | | `apiUrl` | `api-url` | Custom api URL (optional). If not provided, uses process.env.BACKEND_URL Example: 'https://qa.amwal.dev' | `string` | `undefined` | | `countryCode` | `country-code` | The country code of the merchant (e.g. SA) | `"SA" \| "AE" \| "GA" \| "US" \| "ES" \| "EG" \| "AC" \| "AD" \| "AF" \| "AG" \| "AI" \| "AL" \| "AM" \| "AO" \| "AR" \| "AS" \| "AT" \| "AU" \| "AW" \| "AX" \| "AZ" \| "BA" \| "BB" \| "BD" \| "BE" \| "BF" \| "BG" \| "BH" \| "BI" \| "BJ" \| "BL" \| "BM" \| "BN" \| "BO" \| "BQ" \| "BR" \| "BS" \| "BT" \| "BW" \| "BY" \| "BZ" \| "CA" \| "CC" \| "CD" \| "CF" \| "CG" \| "CH" \| "CI" \| "CK" \| "CL" \| "CM" \| "CN" \| "CO" \| "CR" \| "CU" \| "CV" \| "CW" \| "CX" \| "CY" \| "CZ" \| "DE" \| "DJ" \| "DK" \| "DM" \| "DO" \| "DZ" \| "EC" \| "EE" \| "EH" \| "ER" \| "ET" \| "FI" \| "FJ" \| "FK" \| "FM" \| "FO" \| "FR" \| "GB" \| "GD" \| "GE" \| "GF" \| "GG" \| "GH" \| "GI" \| "GL" \| "GM" \| "GN" \| "GP" \| "GQ" \| "GR" \| "GT" \| "GU" \| "GW" \| "GY" \| "HK" \| "HN" \| "HR" \| "HT" \| "HU" \| "ID" \| "IE" \| "IL" \| "IM" \| "IN" \| "IO" \| "IQ" \| "IR" \| "IS" \| "IT" \| "JE" \| "JM" \| "JO" \| "JP" \| "KE" \| "KG" \| "KH" \| "KI" \| "KM" \| "KN" \| "KP" \| "KR" \| "KW" \| "KY" \| "KZ" \| "LA" \| "LB" \| "LC" \| "LI" \| "LK" \| "LR" \| "LS" \| "LT" \| "LU" \| "LV" \| "LY" \| "MA" \| "MC" \| "MD" \| "ME" \| "MF" \| "MG" \| "MH" \| "MK" \| "ML" \| "MM" \| "MN" \| "MO" \| "MP" \| "MQ" \| "MR" \| "MS" \| "MT" \| "MU" \| "MV" \| "MW" \| "MX" \| "MY" \| "MZ" \| "NA" \| "NC" \| "NE" \| "NF" \| "NG" \| "NI" \| "NL" \| "NO" \| "NP" \| "NR" \| "NU" \| "NZ" \| "OM" \| "PA" \| "PE" \| "PF" \| "PG" \| "PH" \| "PK" \| "PL" \| "PM" \| "PR" \| "PS" \| "PT" \| "PW" \| "PY" \| "QA" \| "RE" \| "RO" \| "RS" \| "RU" \| "RW" \| "SB" \| "SC" \| "SD" \| "SE" \| "SG" \| "SH" \| "SI" \| "SJ" \| "SK" \| "SL" \| "SM" \| "SN" \| "SO" \| "SR" \| "SS" \| "ST" \| "SV" \| "SX" \| "SY" \| "SZ" \| "TA" \| "TC" \| "TD" \| "TG" \| "TH" \| "TJ" \| "TK" \| "TL" \| "TM" \| "TN" \| "TO" \| "TR" \| "TT" \| "TV" \| "TW" \| "TZ" \| "UA" \| "UG" \| "UY" \| "UZ" \| "VA" \| "VC" \| "VE" \| "VG" \| "VI" \| "VN" \| "VU" \| "WF" \| "WS" \| "XK" \| "YE" \| "YT" \| "ZA" \| "ZM" \| "ZW"` | `"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` | | `discountDescription` | `discount-description` | discountDescription provides description for the discount | `string` | `undefined` | | `emailRequired` | `email-required` | emailRequired specifies if email address is required or not ("true" or "false"). Can only be true if addressRequired is true. | `boolean` | `true` | | `enableAppleCheckout` | `enable-apple-checkout` | enableAppleCheckout specifies if Apple Checkout is enabled | `boolean` | `false` | | `enableDynamicShippingDetails` | `enable-dynamic-shipping-details` | enableDynamicShippingDetails specifies if shipping countries, states and cities will load dynamically or prefilled in the parameters | `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` | | `fees` | `fees` | fees specifies any fees to be applied | `number` | `0` | | `feesDescription` | `fees-description` | feesDescription provides description for the fees | `string` | `undefined` | | `footerMessage` | `footer-message` | * timelineFooterText specifies the text to be displayed in the footer of the timeline in the checkout modal. | `string` | `''` | | `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` | | `initialFirstName` | `initial-first-name` | initialFirstName specifies a default first name | `string` | `undefined` | | `initialLastName` | `initial-last-name` | initialLastName specifies a default last name | `string` | `undefined` | | `initialPhoneNumber` | `initial-phone-number` | initialPhone specifies a default phone number | `string` | `undefined` | | `installmentOptionsUrl` | `installment-options-url` | The installment options url is URL for the checkout page in the merchant website | `string` | `undefined` | | `installmentsCount` | `installments-count` | Number of installments | `number` | `6` | | `label` | `label` | the label of the button. Either checkout for final checkout or quicky-buy for per product buy | `"Bank Installments" \| "Pay with Apple Pay" \| "Quick Checkout"` | `"Quick 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` | | `onlyShowBankInstallment` | `only-show-bank-installment` | onlyShowBankInstallment specifies if only bank installments should be shown | `boolean` | `false` | | `payUrl` | `pay-url` | Custom payment page URL (optional). If not provided, uses process.env.PAY_URL Example: 'https://pay.amwal.dev' | `string` | `undefined` | | `postcodeOptionalCountries` | -- | enable postal code required option | `string[]` | `undefined` | | `refId` | `ref-id` | refId an identifier to be included in the payment transaction | `string` | `undefined` | | `sendExtraAddressFields` | `send-extra-address-fields` | sendExtraAddressFields specifies if extra address fields are sent in amwalAddressUpdate event | `boolean` | `false` | | `shippingMethods` | -- | shippingMethods an array of shipping methods | `IShippingMethod[]` | `[]` | | `showContinueShoppingButton` | `show-continue-shopping-button` | debug flag for verbose printing of debug messages | `boolean` | `false` | | `showDiscountRibbon` | `show-discount-ribbon` | showDiscountRibbon to show discount ribbon values are ("true" or "false") | `boolean` | `false` | | `showPaymentBrands` | `show-payment-brands` | showPaymentBrands to show supporeted brands under button values are ("true" or "false") | `boolean` | `false` | | `street2Required` | `street2-required` | street2Required specifies if street 2 is required or not ("true" or "false"). Can only be true if addressRequired is true. | `boolean` | `false` | | `taxes` | `taxes` | taxes specifies any additional taxes | `number` | `0` | | `timelineStyle` | `timeline-style` | * timelineStyle specifies the style of the timeline in the checkout modal. | `"default" \| "simple"` | `'default'` | | `uniqueRef` | `unique-ref` | uniqueRef a boolean to enforce the uniqueness of refId | `boolean` | `false` | ## Events | Event | Description | Type | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | `amwalAddressCountryUpdate` | amwalAddressCountryUpdate is a dom event fired on address country selection. | `CustomEvent` | | `amwalAddressStateUpdate` | amwalAddressStateUpdate is a dom event fired on address country selection. | `CustomEvent` | | `amwalAddressUpdate` | amwalAddressUpdate is a dom event fired on address selection. | `CustomEvent` | | `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` | | `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` | | `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` | | `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` | | `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` | ## Methods ### `dismissModal() => Promise` #### Returns Type: `Promise` ## Dependencies ### Depends on - ion-text - [amwal-installments-timeline](../amwal-installments-timeline) - ion-button ### Graph ```mermaid graph TD; amwal-checkout-button --> ion-text amwal-checkout-button --> amwal-installments-timeline amwal-checkout-button --> ion-button ion-button --> ion-ripple-effect style amwal-checkout-button fill:#f9f,stroke:#333,stroke-width:4px ``` ---------------------------------------------- *Built with [StencilJS](https://stenciljs.com/)*