Redirect Flow (Recommended)

The redirect flow provides a full-page checkout experience that works seamlessly on mobile browsers, in-app browsers, and all platforms.

Recommended Integration Method
This flow is recommended for all new integrations, especially if you need mobile browser support.

How It Works

User clicks "Pay with AlyaPay" button
User is redirected to AlyaPay checkout page
Customer completes payment
User is redirected back to your site with payment status
Your site verifies the payment with your backend

Implementation

Step 1: Include SDK

Add the AlyaPay SDK 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: Initialize with redirect_url

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

AlyaPay.Payments.init({
  session_token: SESSION_TOKEN,
  redirect_url: 'https://yoursite.com/payment-callback',
  locale: 'en' // Optional: 'en', 'fr', 'ar'
});

Parameters:

session_token (required) - Session token from your backend
redirect_url (required) - URL where users return after payment
locale (optional) - UI language, default: 'en'

Step 3: Load Payment Button

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.

Handling Callbacks

After payment completion, the user is redirected to your redirect_url with query parameters containing the payment status.

URL Parameters

Parameter	Type	Description
`status`	string	`SUCCESS` or `FAILURE`
`transaction_id`	string	Transaction ID (only present when status is SUCCESS)

Callback Page Implementation

Create a page at your redirect_url to handle the payment result:

// On your callback page (e.g., /payment-callback)
const urlParams = new URLSearchParams(window.location.search);
const status = urlParams.get('status');
const transactionId = urlParams.get('transaction_id');

if (status === 'SUCCESS' && transactionId) {
  // Payment successful - verify with backend
  verifyPayment(transactionId);
} else if (status === 'FAILURE') {
  // Payment failed
  showError('Payment failed. Please try again.');
  // Optionally redirect back to checkout
}

Backend Verification

Always verify the transaction status with your backend before fulfilling orders.

async function verifyPayment(transactionId) {
  try {
    const response = await fetch(`/api/verify-payment?transaction_id=${transactionId}`, {
      headers: {
        'X-Session-Token': SESSION_TOKEN
      }
    });
    
    const data = await response.json();
    
    if (data.status === 'APPROVED') {
      // Payment approved - show success and fulfill order
      showSuccess('Payment successful!');
      window.location.href = '/order-complete';
    } else {
      // Payment not approved (PENDING or CANCELED)
      showError('Payment was not approved. Please try again.');
    }
  } catch (error) {
    console.error('Verification error:', error);
    showError('Failed to verify payment. Please contact support.');
  }
}

Security Important: Never trust URL parameters alone. Always verify the transaction status with your backend using the transaction verification endpoint.

Best Practices

1. Use HTTPS for redirect_url

Always use HTTPS URLs in production:

// ✅ Good
redirect_url: 'https://yoursite.com/payment-callback'

// ❌ Bad (only for local testing)
redirect_url: 'http://localhost:3000/payment-callback'

2. Handle Both SUCCESS and FAILURE

Always handle both success and failure cases:

if (status === 'SUCCESS' && transactionId) {
  // Handle success
} else if (status === 'FAILURE') {
  // Handle failure
} else {
  // Handle unexpected cases
}

3. Always Verify on Backend

Never fulfill orders based on URL parameters alone:

// ❌ Bad - Don't do this
if (status === 'SUCCESS') {
  fulfillOrder(); // UNSAFE!
}

// ✅ Good - Always verify
if (status === 'SUCCESS' && transactionId) {
  const verified = await verifyWithBackend(transactionId);
  if (verified.status === 'APPROVED') {
    fulfillOrder(); // SAFE
  }
}

4. Handle Errors Gracefully

Implement proper error handling:

try {
  const result = await verifyPayment(transactionId);
  handleSuccess(result);
} catch (error) {
  console.error('Verification failed:', error);
  showError('Please contact support with transaction ID: ' + transactionId);
}

Transaction Statuses

After backend verification, you'll receive one of these statuses:

Status	Meaning	Action
`APPROVED`	Payment successful	✅ Complete and ship order
`PENDING`	Payment not approved yet	❌ Don't fulfill order
`CANCELED`	Payment was canceled	❌ Don't fulfill order

Next Steps

Backend Integration - Session creation and verification
Components - Customize payment button
Error Handling - Handle common errors

Redirect Flow

On this page