Skip to main content
Voice payment collection is available on voice tasks only. Card digits are captured in a PCI-secure zone and are never exposed to GenerativeAgent or written to conversation logs. GenerativeAgent sees only masked outcomes (card brand and last four digits).
A voice payment function lets GenerativeAgent collect a card payment from a caller without leaving the supervised conversation. GenerativeAgent guides the caller through entering their card details on the keypad, confirms a masked summary, and runs the charge or tokenization through the API connections you configure. By using a voice payment function, you can:
  • Collect a one-time card payment during a voice call.
  • Tokenize a card for later or recurring use.
  • Let the caller ask questions or cancel partway through without a partial charge.
  • Send the payment outcome to your systems through success and failure connections.

​
How it works

At a high level, GenerativeAgent runs the payment conversation while card data stays in a PCI-secure zone that GenerativeAgent never sees:
  1. Gather what’s needed from the conversation: GenerativeAgent collects any input parameters from context or by asking the caller.
  2. Start the session: GenerativeAgent calls your start connection, which returns the payment details such as amount, currency, and which fields to collect.
  3. Collect the card: GenerativeAgent guides the caller to enter card digits on the keypad, captured in the PCI-secure zone, then reads back a masked summary to confirm.
  4. Run the payment: once the caller confirms, the charge or tokenization runs through your processor.
  5. Report the outcome: GenerativeAgent calls your success or failure connection and reads the matching message to the caller.
A payment session behaves differently from a normal GenerativeAgent conversation:
  • A payment session is deterministic: Once GenerativeAgent starts a session, collection becomes a fixed, step-by-step loop through each field (card number, expiry, security code, postal code), with validation and per-field retries. GenerativeAgent does not decide what to ask next during collection.
  • GenerativeAgent stays in supervision: The caller can still speak at any point. GenerativeAgent can answer a question and resume, or cancel the payment. Deterministic collection and live supervision run together.
  • Payment details are derived programmatically: The amount, currency, fields to collect, and whether to charge or tokenize all come from the start connection, which is your own logic. GenerativeAgent never sets a charge amount.
  • The LLM never sees the card data: Card digits are collected out of band in the PCI-secure zone, separate from the conversation. GenerativeAgent receives only masked outcomes (brand and last four).
  • ASAPP assists collection; it is not the processor: ASAPP assists the out-of-band collection of card data, then reaches out to your payment provider to run the charge or tokenization. Your provider and the connection you configure remain the system of record for the payment.
GenerativeAgent never sets the amount and never sees raw card data. The start connection is the source of truth for what to charge, card entry happens out of band in the PCI-secure zone, and ASAPP reaches out to your payment provider to process it.
Here’s how a payment collection works in detail:
  1. GenerativeAgent gathers the input parameters you defined, from conversation context or by asking the caller. Input variables and reference variables are already available.
  2. GenerativeAgent calls the start connection with the Set variables. The connection returns the payment details: amount, currency, the fields to collect, and any processor parameters.
  3. GenerativeAgent reads the disclaimer and the amount confirmation, then guides the caller field by field. Card digits are entered on the keypad and captured in the PCI-secure zone; GenerativeAgent never receives raw digits.
  4. GenerativeAgent reads a masked summary (card brand and last four). The caller confirms or cancels.
  5. On confirmation, the charge or tokenization runs through the processor.
  6. On success, the success connection fires with the masked outcome and any transaction or token id, and GenerativeAgent reads the success message. On a terminal failure, the failure connection fires with a failed_reason, and GenerativeAgent reads the failure message and follows the configured fallback.
To set up voice payment collection:
  1. Create the function
  2. Define input parameters
  3. Set variables
  4. Wire up the API connections
  5. Configure messages and collection limits
  6. Write the task prompt

​
Step 1: Create the Function

Navigate to the Functions page and click “Create Function.”
  1. Select the voice payment function type and click “Next: Function details.”
    TODO: screenshot of selecting the voice payment function type
  2. Specify the Name and Purpose of the function.
    • Function Name: Provide a concise, unique name, using underscores (e.g., collect_payment).
    • Function Purpose: Briefly describe when GenerativeAgent should collect a payment (e.g., “Collects a card payment for the caller’s outstanding balance once they agree to pay”).
      • GenerativeAgent uses this description to determine if and when to call the function.

​
Step 2: Define Input Parameters (JSON)

GenerativeAgent already has access to the input variables and reference variables resolved earlier in the conversation, and those are available automatically to the start connection. Use input parameters for anything the payment needs that isn’t already known, for example the cardholder’s name or billing address. For each input parameter you define, GenerativeAgent gets the value from conversation context or asks the caller for it. Under “Input Parameters,” enter a valid JSON schema describing what to collect.
Example Input Schema
{
  "type": "object",
  "required": ["cardholder_name"],
  "properties": {
    "cardholder_name": {
      "type": "string",
      "description": "The name on the card; asked if not already known"
    },
    "billing_address": {
      "type": "string",
      "description": "The billing address for the card"
    }
  }
}

​
Step 3: Set Variables

Set variables map to the actual input fields your start connection expects. Each Set variable can pull from:
  • an input parameter, with params.X
  • a reference variable resolved earlier in the conversation, with refs.X
  • a static value
Jinja2 is fully supported in these fields, so you can rename, combine, or transform values before they reach the connection. 
{{vars.get("order_id")}}

​
Step 4: Wire Up the API Connections

A voice payment function uses three API connections. Tag each connection with the matching Application so it appears in the correct slot. Each slot’s picker shows only connections carrying that tag.
  • Payment session start (required): resolves the payment details for this call.
  • Payment session success (optional): receives the outcome after a successful charge or tokenization.
  • Payment session failure (optional): receives a reason after a terminal failure.

​
Start connection

GenerativeAgent calls the start connection with the flat Set variables as input. Your connection returns the details for this payment session.
Start connection response
{
  "amount": 4200,
  "currency": "USD",
  "description": "Order #10482",
  "processor_parameters": 
  { 
  "invoice_id": "INV-10482",
  "min_postal_code_length": 5,
  "is_postal_code_required": true,
  "is_security_code_required": true,
  "valid_card_types": ["visa", "amex"],
  "allowed_payment_types": ["credit-card"],
  "token_type": "one-time"
  }
}
  • amount: amount to charge. 0 indicates tokenization or subscription setup.
  • currency: ISO 4217 currency code.
  • description: free text passed through with the payment.
  • processor_parameters: an arbitrary object passed through to your payment processor. Use it for reconciliation IDs and processor-specific fields. It is echoed back on the success and failure connections.
  • min_postal_code_length, is_postal_code_required, is_security_code_required: control which fields GenerativeAgent collects.
  • valid_card_types: card brands accepted for this session.
  • allowed_payment_types: payment types accepted for this session.
  • token_type: only meaningful when amount is 0. One of one-time, reusable, payment-method.

​
Success connection

GenerativeAgent calls the success connection once on a successful charge or tokenization. The request carries your Set variables as flat fields plus the payment result. Your endpoint returns any 2xx response as an acknowledgment.
Success connection request
{
  "session_reference_id": "ps_8f21c0",
  "order_id": "10482",
  "email": "caller@example.com",
  "transaction_id": "ch_9aa312",
  "token_id": null,
  "processor_parameters": { "invoice_id": "INV-10482" }
}
transaction_id and token_id appear at the root level when your connector exposes them. Some connectors return one, the other, or neither, depending on whether the charge or token is handled in your integration.

​
Failure connection

GenerativeAgent calls the failure connection once on a terminal failure. Branch on failed_reason to drive your recovery logic.
Failure connection request
{
  "session_reference_id": "ps_8f21c0",
  "order_id": "10482",
  "email": "caller@example.com",
  "processor_parameters": { "invoice_id": "INV-10482" }
}

​
Step 5: Configure Messages and Collection Limits

Configure the prompts GenerativeAgent reads to the caller during collection, along with the collection limits. Messages:
  • disclaimer: read once before collection starts.
  • before_starting_session: read after the start connection resolves, before collection begins. Can reference values from the start connection response (e.g., “You will be charged $42.00 for order 10482, is that okay?”).
  • credit_card: read when collecting the card number.
  • security_code: read when collecting the security code.
  • confirmation_message: read as the masked summary before the caller confirms.
  • collection_error: read when a field fails and the caller is asked to retry.
  • payment_error: read when the payment is unsuccessful.
  • payment_success: read when the payment completes successfully.
Collection limits:
  • Per-field retry limit: the maximum number of retries per field before the session ends as a failure.
  • Inter-digit timeout: the seconds allowed between keypad presses before the entry is treated as stalled.

​
Step 6: Write the Task Prompt

Add the function to the task’s list of available functions so GenerativeAgent can use it. GenerativeAgent reads each configured message to the caller and listens for caller speech throughout collection, so the caller can ask questions or change course at any point. Write prompt instructions for the escape paths you want to support:
  • Answer a question about the order or amount, then resume collection.
  • Switch to a different card.
  • Cancel the payment.
A companion cancel function is available to GenerativeAgent automatically whenever a payment session is active. When the caller cancels, GenerativeAgent ends the session without a charge. 
# Objective
Collect payment for the caller's outstanding order once they agree to pay.

# Instructions
1. Confirm the caller wants to pay for order {{ refs.order_id }}.
2. Call the `collect_payment` function to start collection.
3. If the caller asks a question mid-payment, answer it, then continue collection.
4. If the caller wants to stop, cancel the payment without charging.
5. On success, confirm the payment and offer further help.
6. On failure, read the failure message and offer to retry or transfer to an agent.

​
Best Practices

Callers hear these messages read aloud. Keep prompts short and unambiguous, and state amounts and order details plainly in before_starting_session and confirmation_message.
Pass invoice or order IDs through processor_parameters from the start connection. They are echoed back on the success and failure connections, so you can match an outcome to the original request.
A failure connection gives you a single signal to branch on for declines, abandonment, and timeouts. Without it, your systems learn about failures only through your own reconciliation.
Decide what happens after a failed payment: offer a retry, transfer to a live agent, or end the call gracefully. Spell this out in the task prompt so GenerativeAgent handles it consistently.

​
Payment Providers

Reach out to ASAPP to set up your preferred payment provider. ASAPP works with you to connect it and determine how collected card data is sent for processing. The function setup described here is the same regardless of which provider you use.

​
Next Steps

Task Best Practices

Learn more about best practices for task and function configuration.

Connecting Your APIs

Create and tag the API connections used for the payment session slots.

Handling Events

See how GenerativeAgent communicates with your backend systems.

Previewer

Test your functions in real time with the Previewer tool.