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

# Retell

> Integrate Maven voice payments with your Retell AI agent

# Retell Integration

Add PCI-compliant voice payments to your Retell AI agent. When your agent needs to collect a payment, it calls Maven to create a session and transfers the caller to Maven's secure payment line.

## How It Works

<Steps>
  <Step title="Agent triggers collect_payment">
    During a call, your Retell agent calls the `collect_payment` custom function with the amount and caller's phone number.
  </Step>

  <Step title="Maven creates a session">
    Maven creates a payment session and returns a phone number to transfer the caller to.
  </Step>

  <Step title="Agent transfers the caller">
    Your agent uses a Retell Transfer Call node to send the caller to Maven's payment line.
  </Step>

  <Step title="Payment collected">
    Maven collects the card details, processes the payment, and sends a [webhook](/integrations/webhooks) with the result. The caller is optionally transferred back to your agent via the `callback` number.
  </Step>
</Steps>

## Setup

Retell requires manual configuration of custom functions. Here's how to set it up:

<Steps>
  <Step title="Get your webhook token">
    In the [Maven Dashboard](https://app.trymaven.com), go to your app's **Integrations** tab and generate a Retell webhook token. This gives you a URL like:

    ```
    https://api.trymaven.com/integrations/retell/webhook?token=whk_xxx
    ```
  </Step>

  <Step title="Create the collect_payment function in Retell">
    In your Retell agent, add a **Custom Function** with:

    * **Name**: `collect_payment`
    * **URL**: Your server URL from step 1
    * **Description**: `Create a secure payment session. Returns a transfer_number to transfer the caller to.`
    * **Parameters** (paste this JSON):

    ```json theme={"dark"}
    {
      "type": "object",
      "properties": {
        "amount": {
          "type": "number",
          "description": "Payment amount in dollars (e.g. 150.00)"
        },
        "caller": {
          "type": "string",
          "description": "Customer phone number in E.164 format (e.g. +14155551234)"
        },
        "description": {
          "type": "string",
          "description": "What the payment is for"
        },
        "callback": {
          "type": "string",
          "description": "Phone number to transfer the caller back to after payment"
        },
        "memory": {
          "type": "string",
          "description": "Summary of the call context to carry across the transfer"
        }
      },
      "required": ["amount", "caller"]
    }
    ```
  </Step>

  <Step title="Add a Transfer Call node in Retell">
    This is a **Transfer Call node**, not a custom function. In your Retell agent's conversation flow, add a Transfer Call node with:

    * **Routing**: Dynamic — prompt the agent: *"Transfer to the transfer\_number returned by collect\_payment."*
    * **Transfer type**: Cold Transfer
    * **Displayed Caller ID**: **User's Number** *(required — Maven matches sessions by caller ID, so this must be the caller's number, not the agent's)*
  </Step>

  <Step title="Add get_session and cancel_session (optional)">
    You can also add these as custom functions using the same server URL:

    **get\_session** — Look up the most recent payment session by phone number. Use after the caller returns from the payment line.

    ```json theme={"dark"}
    {
      "type": "object",
      "properties": {
        "phone_number": {
          "type": "string",
          "description": "Customer phone number in E.164 format (e.g. +14155551234)"
        }
      },
      "required": ["phone_number"]
    }
    ```

    **cancel\_session** — Cancel a pending payment session.

    ```json theme={"dark"}
    {
      "type": "object",
      "properties": {
        "session_id": {
          "type": "string",
          "description": "The session ID returned by collect_payment"
        }
      },
      "required": ["session_id"]
    }
    ```
  </Step>
</Steps>

## Example System Prompt

Add something like this to your Retell agent's system prompt. Retell provides `{{user_number}}` and `{{agent_number}}` as dynamic variables.

```
When a caller needs to make a payment, use the following flow:

1. Confirm the caller wants to pay their balance
2. Call collect_payment with:
   - amount: the payment amount
   - caller: {{user_number}}
   - description: a short description of the payment
   - callback: {{agent_number}}
3. Tell the caller you're transferring them to our secure payment line
4. Transfer the call to the transfer_number returned by collect_payment

After the caller returns from the payment line:
1. Call get_session with {{user_number}} to check the payment status
2. If status is "payment-success" — confirm the payment was successful and thank them
3. If status is "payment-failed" or "expired" — let them know and offer to try again

Keep responses short and conversational. Do not ask for card details — the
secure payment line handles that.
```