Popup window

Using popup window allows your users to complete escrow-related actions without leaving your application.

How It Works

1. Request Link: Get a redirect URL from Portafino's API

2. Open Popup: Open the URL in a popup window

3. User Action: User completes the action in the popup

4. Message Communication: Popup communicates back via postMessage

5. Handle Response: Your app handles the response and updates accordingly

Opening a Popup

After receiving a redirect URL from Portafino's API, open it in a popup.

function openPopupWindow(url: string, options: {
  name?: string;
  width?: number;
  height?: number;
  centered?: boolean;
} = {}): Window | null {
  const { 
    name = '_blank', 
    width = 500, 
    height = 600, 
    centered = true 
  } = options;
  
  let left = 0;
  let top = 0;
  
  if (centered) {
    left = window.innerWidth / 2 - width / 2;
    top = window.innerHeight / 2 - height / 2;
  }
  
  return window.open(
    url,
    name,
    `width=${width},height=${height},left=${left},top=${top},resizable=yes,scrollbars=yes,status=yes`
  );
}

// Usage
const popupRef = openPopupWindow(redirectUrl, {
  name: 'PortafinoPopup',
  width: 500,
  height: 650
});

Listening for Events

Set up a message listener to handle communication from the popup

interface PopupMessage {
  name: 'popup_closed' | 'kyc_completed' | 'action_completed';
  source: 'portafino-portal';
}

function listenToChildMessage(
  callback: (data: PopupMessage) => void,
  options: { 
    targetOrigin?: string;
    sourceWindow?: Window | null;
  } = {}
): () => void {
  const { targetOrigin = '*', sourceWindow = null } = options;
  
  const handleMessage = (event: MessageEvent) => {
    if (event.data.source !== 'portafino-portal') {
      return;
    }
    
    // Validate origin if specified
    if (targetOrigin !== '*' && event.origin !== targetOrigin) {
      return;
    }
    
    // Validate source window if specified
    if (sourceWindow !== null && event.source !== sourceWindow) {
      return;
    }
    
    callback(event.data);
  };

  window.addEventListener('message', handleMessage);
  
  return () => window.removeEventListener('message', handleMessage);
}

// Usage
const cleanup = listenToChildMessage((data) => {
  handlePopupMessage(data);
}, {
  sourceWindow: popupRef
});

Available Events

Event	Description
popup_closed	Popup window was closed by the user (popup no longer exists)
kyc_completed	User has finished KYC verification process, it could still be under review, so make sure to check user status by calling user endpoint.
action_completed	The requested agreement action was completed successfully

Handling Events

When you receive an event from the popup, you should:

1. Handle popup closure (if popup_closed)

2. Refetch user status through your API to get the latest state

3. Update your UI based on the new status

function handlePopupMessage(data: PopupMessage) {
  switch (data.name) {
    case 'popup_closed':
      // Popup no longer exists, clean up reference
      popupRef = null;
      break;
      
    case 'kyc_completed':
    case 'action_completed':
      // Clean up popup reference
      popupRef = null;
      
      // Refetch user status to get latest state
      await refetchUserStatus();
      
      // Update your UI based on new status
      updateUI();
      break;
  }
}

Default success behaviour

By default popup will self close in 5 seconds after successful action completion.

Security Considerations

• Origin Validation: Validate the origin of incoming messages

• Source Window: Use the sourceWindow option to ensure messages come from the expected popup

• API Key Security: Keep your API keys secure

Error Handling

• Popup Blocked: Check if openPopupWindow returns null

• Network Errors: Handle API request failures gracefully

• Message Errors: Validate incoming messages before processing

Best Practices

1. Fallback Options: Provide alternatives if popups are blocked

2. Loading States: Show loading indicators while popup is open

3. Cleanup: Always clean up message listeners when done

4. User Feedback: Inform users about the popup process

This integration approach provides a seamless user experience while maintaining security and reliability for escrow operations.