Communication Protocol

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
  }
}

{
  type: 'ORDER_CREATED',
  data: {
    order_id: 'a8gWRVzSiNfu5PQjRpt1k7',      // Unique identifier for the order
    created_at: '2024-03-21T12:00:00Z',      // Timestamp of order creation
    buyer_address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e', // Buyer's wallet address
    seller_address: '0x02dE16F094c472862513fa67M21Eab73o18c47E8', // Seller's wallet address
    send_amount: '10.10',                    // Amount to be sent in USD
    receive_amount: '10.03',                 // Amount of tokens received (after fees)
    uniqueness_amount: '0.03',               // Amount of cents added for uniqueness
    receiving_chain_id: '8453',              // Chain ID where payment will be received
    zelle_address: 'user@example.com'        // Zelle address for payment
  }
}

{
  type: 'CANCEL'
}

{
  type: 'OPEN_EXPLORER_URL',
  data: {
    url: 'https://basescan.org/tx/0x123abc...' // URL to open in a new tab/window
  }
}

{
  type: 'USER_DONE'
}

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

Parameter	Description	Example
`address`	The Ethereum wallet address where USDC will be sent	`0x742d35Cc6634C0532925a3b844Bc454e4438f44e`
`amount`	The amount in USD that the user wants to convert to USDC	`100`

Optional Parameters

Parameter	Description	Example
`theme`	The 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:

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

Getting Started

Phoenix Payment

Overview

Messages from Phoenix to Your Application

Handling Messages

Parameters from Your Application to Phoenix

Required Parameters

Optional Parameters

Security Considerations

​Overview

​Messages from Phoenix to Your Application

​Handling Messages

​Parameters from Your Application to Phoenix

​Required Parameters

​Optional Parameters

​Security Considerations

Overview

Messages from Phoenix to Your Application

Handling Messages

Parameters from Your Application to Phoenix

Required Parameters

Optional Parameters

Security Considerations