Payment Callbacks

The SDK communicates with your page through the PaymentCallback function.

Basic Usage

// Define BEFORE initializing SDK
window.PaymentCallback = function(response) {
  if (response.event === 'payment_flow_completed') {
    console.log('Payment flow completed!');
    console.log('Transaction ID:', response.transaction_id);
    console.log('Flow event:', response.flow_event);
    
    // TODO: Verify payment status with your backend
    
  } else if (response.event === 'payment_flow_cancelled') {
    console.log('Payment cancelled!');
    console.log('Reason:', response.reason);
  }
};

// Then initialize SDK
AlyaPay.Payments.init({ 
  session_token: SESSION_TOKEN,
  locale: 'en'
});

Important: Define PaymentCallback before calling init().

Events

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:

Property	Type	Description
`event`	string	Always `'payment_flow_completed'`
`transaction_id`	string \| null	Transaction ID to verify, or `null` if no transaction
`flow_event`	string	Either `'payment_success'` or `'payment_failed'`
`reason`	null	Always `null` for completed events

What to do:

Get transaction_id from response
Verify transaction status with your backend (Step 6 in Quick Start)
Check if status is APPROVED
Complete order only if approved

Important: This event does NOT guarantee payment success. Always verify the transaction status with your backend!

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:

Property	Type	Description
`event`	string	Always `'payment_flow_cancelled'`
`reason`	string	Why payment was cancelled

Cancellation Reasons:

Reason	Description
`overlay_close`	User clicked outside popup overlay
`popup_closed`	User closed popup window
`user_cancelled`	User clicked cancel button

What to do:

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

Complete Example

Here's a complete implementation with backend verification:

window.PaymentCallback = async function(response) {
  if (response.event === 'payment_flow_completed') {
    console.log('Payment flow completed!');
    console.log('Transaction ID:', response.transaction_id);
    console.log('Flow event:', response.flow_event);
    
    if (!response.transaction_id) {
      alert('No transaction was created');
      return;
    }
    
    // Verify with your backend
    try {
      const result = await fetch(`/api/verify-payment?transaction_id=${response.transaction_id}`);
      const data = await result.json();
      
      if (data.status === 'APPROVED') {
        // Payment successful!
        alert('Payment successful! Redirecting...');
        window.location.href = '/success';
      } else {
        // Payment not approved (PENDING or CANCELED)
        alert('Payment was not approved. Please try again.');
      }
    } catch (error) {
      console.error('Verification error:', error);
      alert('Failed to verify payment. Please contact support.');
    }
    
  } else if (response.event === 'payment_flow_cancelled') {
    console.log('Payment cancelled!');
    console.log('Reason:', response.reason);
    alert('Payment cancelled. You can try again.');
  }
};

Verification

Always verify transaction status on your backend before fulfilling orders.

Your backend should:

Receive the transaction_id from your frontend
Call AlyaPay's transaction status endpoint
Return the status to your frontend

See the Backend Integration guide for detailed implementation.

Transaction Statuses

Status	Meaning	Action
`APPROVED`	Payment successful	Complete order
`PENDING`	Payment not approved	Don't fulfill order
`CANCELED`	Payment not approved	Don't fulfill order

Best Practices

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

Payment Callbacks

On this page