> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phoenix.market/llms.txt
> Use this file to discover all available pages before exploring further.

# Communication Protocol

> Learn how the Phoenix payment iframe communicates with your application

## 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:

<CodeGroup>
  ```javascript Transaction Success theme={null}
  {
    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
    }
  }
  ```

  ```javascript Order Created theme={null}
  {
    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
    }
  }
  ```

  ```javascript Cancel theme={null}
  {
    type: 'CANCEL'
  }
  ```

  ```javascript Open Explorer URL theme={null}
  {
    type: 'OPEN_EXPLORER_URL',
    data: {
      url: 'https://basescan.org/tx/0x123abc...' // URL to open in a new tab/window
    }
  }
  ```

  ```javascript Done theme={null}
  {
    type: 'USER_DONE'
  }
  ```
</CodeGroup>

### Handling Messages

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

```javascript theme={null}
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 <br />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