Frontend Integration

Add the AlyaPay SDK to your checkout page and display payment options.

Step 1: Include SDK

Add the SDK script to your page:

<script src="https://cdn.alyapay.com/alyapay-sdk.min.js"></script>

The SDK will be available as window.AlyaPay.

Step 2: Define Payment Callback

Define PaymentCallback before initializing the SDK:

window.PaymentCallback = function(response) {
  console.log('Payment event:', response.event);
  
  if (response.event === 'payment_flow_completed') {
    // Payment flow finished - verify transaction
    verifyPayment(response.transaction_id);
  } else if (response.event === 'payment_flow_cancelled') {
    // User cancelled - allow retry
    console.log('Payment cancelled by user');
  }
};

⚠️ Important: Define this function before calling init().

Step 3: Initialize SDK

Get a session token from your backend and initialize the SDK:

// Initialize SDK
AlyaPay.Payments.init({
  session_token: SESSION_TOKEN,
  locale: 'en' // Optional: 'en', 'fr', 'ar'
});

// Load payment button
AlyaPay.Payments.load({
  container: '#alyapay-button'
});

SDK Methods

AlyaPay.Payments.init()

Initialize the SDK with configuration.

AlyaPay.Payments.init({
  session_token: SESSION_TOKEN,         // Required
  locale: 'en'                          // Optional: 'en', 'fr', 'ar'
});

Parameters:

• session_token (required) - Session token from your backend
• locale (optional) - UI language, default: 'en'

AlyaPay.Payments.load()

Display the payment button in a container.

AlyaPay.Payments.load({
  container: '#alyapay-button'
});

Parameters:

• container (required) - CSS selector for the container element

The button will be rendered inside the specified container.

AlyaPay.Payments.startFlow()

Start payment flow programmatically (for custom buttons).

try {
  await AlyaPay.Payments.startFlow();
} catch (error) {
  console.error('Payment failed:', error);
}

Returns: Promise<void>

Throws:

• POPUP_BLOCKED - Browser blocked the popup
• TOKEN_EXPIRED - Session token expired
• SDK_NOT_INITIALIZED - SDK not initialized

See Payment Button for custom button examples.

Localization

Change the language with the locale option:

AlyaPay.Payments.init({
  session_token: token,
  locale: 'fr' // 'en', 'fr', or 'ar'
});

Available Locales:

• en - English (default)
• fr - French
• ar - Arabic (with automatic RTL layout)

The button text, popup interface, and all messages will appear in the selected language.

Error Handling

Handle SDK errors gracefully:

try {
  AlyaPay.Payments.init({
    session_token: sessionToken,
    locale: 'en'
  });
  
  AlyaPay.Payments.load({
    container: '#alyapay-button'
  });
} catch (error) {
  console.error('AlyaPay initialization failed:', error);
  
  // Show error message to user
  document.getElementById('alyapay-button').innerHTML = `
    <div class="error">
      <p>Payment method temporarily unavailable.</p>
      <button onclick="location.reload()">Retry</button>
    </div>
  `;
}

See Error Handling for complete error reference.

What Happens During Payment

1. Customer clicks the payment button
2. Popup opens with AlyaPay checkout
3. Customer register a new account
4. Customer completes ID verification
5. Customer selects installment plan (2x, 3x, or 4x)
6. Customer confirms payment
7. Popup closes
8. PaymentCallback is triggered with transaction ID
9. Your code verifies the transaction
10. Order is completed or declined based on status

Common Issues

Button doesn't appear:

• Check that container element exists in DOM
• Verify SDK loaded: typeof window.AlyaPay !== 'undefined'
• Ensure init() was called before load()
• Check browser console for errors

Popup blocked:

• Browser blocked the payment window
• Ask user to enable popups for your site
• See Errors for handling

Events not firing:

• Ensure PaymentCallback is defined before calling init()
• Check it's in global scope: window.PaymentCallback
• Verify function name is exactly PaymentCallback

Next Steps

• Events - Handle payment callbacks in detail
• Payment Button - Customize the button
• Payment Widget - Add installment calculator

Need help? Email support@alyapay.com