​
Overview

The Phoenix payment iframe communicates with your application through the window.postMessage API. This page explains the messages exchanged between your application and the Phoenix payment iframe.

​
Messages from Phoenix to Your Application

The Phoenix payment iframe will send messages to your application to indicate the status of different processes:

{
  type: 'TRANSACTION_SUCCESS',
  data: {
    amount: '100',                           // USD amount
    token: 'USDC',                           // Token type
    chain: 'Base',                           // Blockchain network
    walletAddress: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e', // Recipient address
    sendAmount: '99.5',                      // Amount of tokens sent (after fees)
    transactionHash: '0x123abc...',          // Blockchain transaction hash
    basescanLink: 'https://basescan.org/tx/0x123abc...' // Explorer link
  }
}

​
Handling Messages

Your application should listen for these messages and take appropriate actions:

window.addEventListener('message', function(event) {
  // IMPORTANT: Verify origin for security
  if (event.origin !== 'https://app-partner.phoenix.market') return;
  
  // Handle transaction success message
  if (event.data?.type === 'TRANSACTION_SUCCESS') {
    const { amount, token, chain, walletAddress, sendAmount, transactionHash, basescanLink } = event.data.data;
    
    console.log('Transaction successful:', transactionHash);
    console.log(`Amount: $${amount} ${token} on ${chain}`);
    console.log(`Transaction link: ${basescanLink}`);
    
    // Update your UI or redirect user to a success page
  }
  // Handle order created message
  else if (event.data?.type === 'ORDER_CREATED') {
    const { order_id, ...data } = event.data.data;
    
    console.log('Order created:', event.data.data);
    // You should store order details in your database, especially the order_id
  }
  // Handle cancel message
  else if (event.data?.type === 'CANCEL') {
    console.log('Payment canceled by user');
    
    // Close the iframe or update UI accordingly
    // Example: document.getElementById('phoenix-iframe').style.display = 'none';
  }
  // Handle open explorer URL message
  else if (event.data?.type === 'OPEN_EXPLORER_URL') {
    const url = event.data.url;
    
    console.log('Opening explorer URL:', url);
    
    // Open the URL in a new tab
    window.open(url, '_blank');
  }
  // Handle done message
  else if (event.data?.type === 'USER_DONE') {
    console.log('Payment process completed');
    
    // Close the iframe or update UI accordingly, similar to CANCEL
    // Example: document.getElementById('phoenix-iframe').style.display = 'none';
  }
});

​
Parameters from Your Application to Phoenix

Parameters are passed from your application to the Phoenix payment iframe via URL query string:

https://app-partner.phoenix.market/?address=0xWALLET_ADDRESS&amount=AMOUNT_IN_USD&theme=THEME

​
Required Parameters

ParameterDescriptionExample
addressThe Ethereum wallet address where USDC will be sent0x742d35Cc6634C0532925a3b844Bc454e4438f44e
amountThe amount in USD that the user wants to convert to USDC100

​
Optional Parameters

ParameterDescriptionExample
themeThe UI theme to use. Can
be either ‘light’ or ‘dark’		dark

​
Security Considerations

To ensure secure communication between your application and the Phoenix payment iframe:

  1. Always verify the origin of incoming messages to prevent cross-site scripting attacks
  2. Use HTTPS for all communication
  3. Validate input parameters before passing them to the iframe
  4. Clean up event listeners when the payment process is complete to prevent memory leaks