Amwal Checkout - React

Amwal payment components library for React applications. This library provides a complete set of components for integrating Amwal payment solutions into your React application.

Installation

npm install @amwaljs/checkout-button-react
# or
yarn add @amwaljs/checkout-button-react

Setup

React Configuration

import React from 'react';
import { defineCustomElements } from '@amwaljs/checkout-button-react/dist/loader';

// Call this once in your app to register the components
defineCustomElements();

Components

AmwalCheckoutButton

A comprehensive checkout button component that handles payment processing with support for installments, shipping, and various payment methods.

Basic Usage

<AmwalCheckoutButton
  merchantId="your-merchant-id"
  amount={2400}
  countryCode="SA"
  locale="en"
  addressRequired={true}
  onAmwalCheckoutSuccess={handlePaymentSuccess}
  onAmwalDismissed={handlePaymentDismissed}
/>

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) | "AC" \ | "AD" \ | | darkMode | dark-mode | Dark Mode: - on: turns on dark mode - off: turns on light mode - auto: use customer preference for dark mode | "auto" \ | "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" \ | | 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" | | 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<ICountry> | | amwalAddressStateUpdate | amwalAddressStateUpdate is a dom event fired on address country selection. | CustomEvent<IState> | | 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<AmwalDismissalStatus> | | 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> |

Event Usage in React

<AmwalCheckoutButton
  onEvent={(event) => {
    console.log('Event data:', event.detail);
  }}
/>

AmwalInstallmentsGuide

A guide component that displays installment payment information to help customers understand their payment options.

Basic Usage

<AmwalInstallmentsGuide
  locale="en"
/>

Properties

| Property | Attribute | Description | Type | Default | |----------|-----------|-------------|------|---------| | locale | locale | Language locale: 'en' for English, 'ar' for Arabic | "ar" \ | "en" |

AmwalInstallmentsTimeline

A timeline component that visualizes installment payment schedules with customizable styles and layouts.

Basic Usage

<AmwalInstallmentsTimeline
  amount={2400}
  installmentsCount={12}
  locale="en"
  border={true}
  timelineStyle="default"
/>

Properties

| Property | Attribute | Description | Type | Default | |----------|-----------|-------------|------|---------| | amount | amount | The total amount to be paid in installments | number | 0 | | border | border | Enable or disable border around the timeline | boolean | false | | debug | debug | Enable debug mode for additional console logs | boolean | false | | decimalPlaces | decimal-places | Number of decimal places for amount formatting | number | 2 | | enableInstallments | enable-installments | Enable or disable installments feature | boolean | false | | footerMessage | footer-message | Footer message for simple timeline style | string | undefined | | installmentData | installment-data | The installment payments (optional - will be calculated if not provided) | string | '[]' | | installmentsCount | installments-count | Number of installments | number | 6 | | intervalMonths | interval-months | number | 1 | undefined | | labelFormat | label-format | "date" \ | "simple"|'simple'| |locale|locale| the language of the plugin. supported languages are Arabic ("ar") and English ("en") |string|"en"| |maxVisibleInstallments|max-visible-installments| Maximum number of installments to display (for UI clarity) |number|3| |startDate|start-date|string|undefined|undefined| |timelineStyle|timeline-style| Timeline display style: 'default' for circular timeline, 'simple' for modern dots with lines |"default" ` | "simple" |

AmwalPOS

A Point of Sale (POS) component for in-person transactions with customer information capture and payment processing.

Basic Usage

<AmwalPOS
  amount=""
  currency="SAR"
  locale="en"
  minAmount={1}
  maxAmount={999999}
  authToken="your-auth-token"
  storeId="your-store-id"
  apiBaseUrl="https://backend.sa.amwal.tech"
/>

AmwalWidget

A flexible widget component for displaying Amwal payment options with modal support and customizable layouts.

Basic Usage

<AmwalWidget
  config={widgetConfig}
  isActive={true}
  locale="en"
/>

// Define config object
const widgetConfig = {
  installmentsCount: 12,
  price: 10000,
  currency: 'SAR',
  locale: 'en'
};

Properties

| Property | Attribute | Description | Type | Default | |----------|-----------|-------------|------|---------| | animationType | animation-type | Animation type for modal entrance | "default" \ | "fade" \ | | config | -- | Widget configuration including price, installments, and URL | WidgetConfig | undefined | | debug | debug | Enable debug mode for additional console logs | boolean | false | | disableAnimations | disable-animations | Disable animations (useful for testing or accessibility) | boolean | false | | layoutTheme | layout-theme | "desktop" \ | "mobile"|'mobile'| |locale|locale| The language of the plugin. Supported languages are Arabic ("ar") and English ("en") |string|"en"` |

Common Configuration

Merchant Setup

Before using any Amwal components, you'll need:

1. Merchant ID: Obtain from Amwal Merchant Portal
2. API Configuration: Set up your backend integration
3. Environment URLs: Configure for development/production

Basic Example

import React, { useState } from 'react';
import { AmwalCheckoutButton } from '@amwaljs/checkout-button-react';

const PaymentComponent = () => {
  const [amount] = useState(2400);

  const handlePaymentSuccess = (event) => {
    console.log('Payment successful:', event.detail);
    // Handle successful payment
  };

  const handlePaymentDismissed = (event) => {
    console.log('Payment dismissed:', event.detail);
    // Handle payment dismissal
  };

  return (
    <AmwalCheckoutButton
      merchantId="your-merchant-id-here"
      amount={amount}
      countryCode="SA"
      locale="en"
      addressRequired={true}
      onAmwalCheckoutSuccess={handlePaymentSuccess}
      onAmwalDismissed={handlePaymentDismissed}
    />
  );
};

export default PaymentComponent;

TypeScript Support

This library includes TypeScript definitions. For optimal development experience:

// Event type definitions
interface AmwalCheckoutStatus {
  orderId: string;
}

interface AmwalDismissalStatus {
  orderId: string;
  paymentSuccessful: boolean;
}

// Usage with proper typing
const handleSuccess = (event: CustomEvent<AmwalCheckoutStatus>) => {
  const { orderId } = event.detail;
  // orderId is properly typed
};

Styling and Customization

CSS Custom Properties

The components support CSS custom properties for theming:

/* Global theme customization */
:root {
  --amwal-primary-color: #your-color;
  --amwal-border-radius: 8px;
  --amwal-font-family: 'Your Font', sans-serif;
}

/* Component-specific styling */
amwal-checkout-button {
  --button-background: #custom-color;
  --button-text-color: #ffffff;
}

Dark Mode Support

Components automatically support dark mode when enabled:

<AmwalCheckoutButton
  darkMode="auto"  // auto | on | off
  // other props
/>

Troubleshooting

Common Issues

1. Components not rendering: Ensure the library is properly imported and initialized
2. TypeScript errors: Make sure you have the latest version and proper type definitions
3. Styling issues: Check CSS custom properties and ensure proper cascading

Debug Mode

Enable debug mode for detailed logging:

<AmwalCheckoutButton
  debug={true}
  // other props
/>

Support

• Documentation: Amwal Developer Docs
• Merchant Portal: https://merchant.sa.amwal.tech
• Support: Contact Amwal technical support

License

This library is licensed under the terms specified by Amwal. See the LICENSE file for details.