Skip to main content

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

1

Agent triggers collect_payment

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

Maven creates a session

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

Agent transfers the caller

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

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

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
2

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

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

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.