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

Agent triggers collect_payment

During a call, your Retell agent calls the collect_payment custom function with the amount and caller’s phone number.

Maven creates a session

Maven creates a payment session and returns a phone number to transfer the caller to.

Agent transfers the caller

Your agent uses a Retell Transfer Call node to send the caller to Maven’s payment line.

Payment collected

Maven collects the card details, processes the payment, and sends a webhook with the result. The caller is optionally transferred back to your agent via the callback number.

Setup

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

Get your webhook token

In the Maven Dashboard, 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

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

{
  "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"]
}

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)

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.

{
  "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.

{
  "type": "object",
  "properties": {
    "session_id": {
      "type": "string",
      "description": "The session ID returned by collect_payment"
    }
  },
  "required": ["session_id"]
}

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.

​Retell Integration

​How It Works

​Setup

​Example System Prompt

Retell Integration

How It Works

Setup

Example System Prompt