Popup Flow (Deprecated)

The popup flow opens payment in a popup window and communicates results through JavaScript callbacks.

Implementation

Step 1: Include SDK

Add the SDK script to your page:

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

The SDK will be available as window.AlyaPay.

Step 2: Define PaymentCallback

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');
  }
};

Step 3: Initialize SDK

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

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

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

Parameters:

• session_token (required) - Session token from your backend
• locale (optional) - UI language, default: 'en'
• redirect_url (not used) - Omit this to enable popup mode

Handling Events

The SDK communicates with your page through the PaymentCallback function.

payment_flow_completed

Triggered when customer completes the payment flow (success or failure).

Response Object:

{
  event: 'payment_flow_completed',
  transaction_id: 'tx_123...', // null if no transaction was created
  flow_event: 'payment_success' | 'payment_failed',
  reason: null
}

Properties:

What to do:

1. Get transaction_id from response
2. Verify transaction status with your backend
3. Check if status is APPROVED
4. Complete order only if approved

payment_flow_cancelled

Triggered when customer closes popup or cancels payment.

Response Object:

{
  event: 'payment_flow_cancelled',
  reason: 'overlay_close' | 'popup_closed' | 'user_cancelled'
}

Properties:

Cancellation Reasons:

What to do:

• Show "Payment cancelled" message
• Allow customer to retry payment
• Keep payment button visible

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.

Backend Verification

Always verify transaction status on your backend before fulfilling orders.

Your backend should:

1. Receive the transaction_id from your frontend
2. Call AlyaPay's transaction status endpoint
3. Return the status to your frontend

See the Backend Integration guide for detailed implementation.

Transaction Statuses

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.

Best Practices

1. Always verify - Don't trust events alone, always verify with backend
2. Define callback first - Before calling init()
3. Show loading states - During backend verification
4. Handle all events - Both payment_flow_completed and payment_flow_cancelled
5. Error handling - Network issues can happen, handle them gracefully
6. Check transaction_id - It can be null in some cases

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
• Consider using Redirect Flow instead

Events not firing:

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

What Happens During Payment

1. Customer clicks the payment button
2. Popup opens with AlyaPay checkout
3. Customer registers 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

Next Steps

• Redirect Flow - Mobile-friendly alternative
• Payment Button - Customize the button
• Payment Widget - Add installment calculator
• Backend Integration - Session creation and verification

Need help? Email support@alyapay.com