Taking payments¶

Status: In progress | Last reviewed: 2026-09-10

Payments lets an agent collect a card or bank payment from a caller. When the agent decides it is time to take payment, it steps aside: the AI is paused, the caller enters their details on their phone keypad or a secure on-screen form, and the agent comes back knowing only whether it worked and the last four digits. The card number never reaches the AI, the transcript, or the recording.

Payments is being delivered in stages. A voice agent can take a payment on the keypad today, and refunds and status checks work. The on-screen form is not built yet, so an agent whose only capture option is On-screen form — which is every chat agent — has nowhere for the caller to enter anything, and a card number typed into a chat box is not yet blocked. What works today says exactly how far along it is.

All of it depends on an administrator having deployed the secure payment service. Until they have, every attempt to take a payment reports that payments are not configured and nothing is charged.

Turn it on¶

Two switches, both required:

1. Tenant — Settings → Tenant Settings → Payments → Allow agents to take payments. A tenant admin also picks the payment provider and the limits no agent may exceed. See Payments settings.
2. Agent — in the pipeline editor, open the conversational stage's inspector and flip the Payments switch in the Capabilities section. The configuration form appears under it.

Only one stage in an agent can own Payments. Publishing is blocked if two do.

Payments also works on a speech-to-speech node. When secure collection starts, TrueServe temporarily mutes the realtime model: it receives silence while a fixed, non-AI voice script asks for keypad input. Once payment finishes, the same speech-to-speech session resumes with only the result and masked last four digits.

Configure it¶

Payment provider — which provider this agent charges. Tenant default uses whatever an administrator selected. The provider's keys live on the integration and are read only by the isolated payment service, never by the agent.

What the caller can pay with

You can offer fewer instruments than your tenant allows, never more. The form warns you inline and publishing is blocked if you pick none.

How the caller enters the details

Pick both on a voice call with a screen and the two stay in sync — whichever the caller uses, the other keeps up, and whichever finishes first completes the payment.

Some phone connections cannot pass keypad presses to TrueServe at all (Genesys AudioHook and Five9). On those, choose the on-screen form; the editor warns you.

Currencies and Largest single payment narrow the tenant's limits for this agent. Amounts are in cents, so 50000 is $500.00. Leave them empty to inherit the tenant's.

Refunds are off until you turn them on. When on, Only refund payments taken in this conversation should stay on unless the agent genuinely needs to refund an earlier order — with it off, the agent can refund any payment it is given a reference for. A refund can never exceed the original payment, whatever limit you set.

Keypad capture¶

Shown when Phone keypad is selected.

• Wait for digits (seconds) — how long the agent waits at each step before repeating itself, counted from the moment the caller has finished hearing the request rather than from when it was sent. So this is the caller's thinking time, and a short setting no longer gets used up by the prompt itself. Between 5 and 120.
• Retries per step — how many times a step may be re-attempted after an invalid entry. Up to 5.
• Return to the main agent — the key offered if the caller speaks during secure mode. Star by default; choose any ordinary phone keypad key.
• Read the last four digits back — the caller's only chance to catch a mis-key before the money moves. Only ever the last four, never the whole number, and always spoken digit by digit ("4 4 4 4", never "four thousand four hundred and forty-four"). Keep it on.

The field-entry keys are fixed: hash ends a step, star clears it, and star twice in a row cancels the payment. At the read-back, 1 pays and star starts the card over from the beginning rather than re-doing the last step — the caller has just heard the wrong card read back, so the whole thing is what they want to redo. The configured return key takes over only after speech has been detected and the secure voice has offered it; otherwise its normal meaning is unchanged.

Customize what the agent says reveals the script for each step, including Speech detected in secure mode and Returning to the main agent. The agent speaks these through its configured voice, or a provider-matched secure voice for speech-to-speech agents, while the model is paused. They are wording rather than prompting — the AI is not involved. Leave a box empty to use the default shown in it. Four substitutions are made and nothing else is: {{amount}} (the amount with its currency), {{last4}} (the last four digits), {{instrument}} ("card" or "account") and {{return_key}} (a spoken label such as "star").

Tell the agent when to use it¶

Enabling Payments makes the payment tools available to the model; your prompt decides when it reaches for them. Insert them with @ or {{:

• {{TOOL:collect_payment}} — take a payment.
• {{TOOL:process_refund}} — refund one (only offered when you enable refunds).
• {{TOOL:get_payment_status}} — check what happened to one.

A prompt that works:

Tell the customer the exact total and what it is for, ask whether they want to
pay it now, and wait for their answer. Only after they say yes, use
{{TOOL:collect_payment}} with that amount and the order number as the reference.
Do not ask for card details yourself and never repeat any number the customer
gives you — the secure payment step collects them. When it finishes, tell the
customer whether it succeeded and read back only the last four digits.

TrueServe enforces this ordering before secure capture starts. An unrelated or old “yes” does not count, a deliberate payment-button click does, and each approval can start only one capture.

Extra instructions (optional) on the form adds guidance the model sees alongside the tools — use it for policy ("only take payment once the order total is confirmed"), never for card details.

What the caller experiences¶

On a voice call: the agent says it is transferring them to a secure step, then a fixed, scripted voice asks for each number in turn — the AI is no longer listening. If the caller speaks, voice activity is detected without transcribing or understanding the words. The secure voice explains that it cannot answer questions there and offers the configured key to return to the main agent. Pressing it discards the unfinished payment, returns to the conversation, and the main agent asks the caller to repeat what it could not hear; if payment is still needed, it starts a fresh secure payment afterwards. The caller can instead continue using the keypad. The caller hears "ending 1234" confirmations, never their whole number read back.

On chat or a screen: a secure payment form appears. If the caller types a card number into the chat box instead, it is blocked before it goes anywhere and they are pointed at the form. Neither of those is built yet — see What works today.

What works today¶

Payment capture currently requires a linear pipeline. A parallel or swimlane agent cannot be published with Payments because every model branch would need to be gated before collection begins.

Two consequences worth planning around while the form is in development:

• An agent that offers only the on-screen form has no working way to take a payment. On a voice call, select Phone keypad as well; a chat agent cannot take a payment yet at all.
• A caller who types their card number into a chat box is not yet stopped. Until that lands, do not point chat customers at the message box for card details.

All of this also needs the secure payment service deployed. Where it is not, every payment attempt — capture, refund or status — reports that payments are not configured, and nothing is charged.

Troubleshooting¶

• The Payments switch is missing — a tenant admin has not enabled it under Settings → Tenant Settings → Payments, or no payment provider integration exists yet.
• Publishing is blocked: "no payment method is selected" — pick Card, Bank account, or both.
• Publishing is blocked: "there is no way for the caller to enter their details" — pick Phone keypad, On-screen form, or both.
• A speech-to-speech payment says the secure step could not start — the runtime could not create its private scripted voice lane from the agent's voice integration. Check that integration is active and has permission to use its text-to-speech service.
• The agent says payments are not configured — the secure payment service is not reachable from your environment. Ask an administrator to check it; nothing was charged.
• On a voice call the agent never asks for the card — check the caller's phone connection can pass keypad presses (Genesys AudioHook and Five9 cannot), and that Phone keypad is selected. An agent with only On-screen form cannot take a payment yet.
• The digits appear on the keypad but the agent doesn't react — the keypad shows what you pressed whether or not the presses reached the call, so the display is not confirmation. In the emulator, use the on-screen Keypad rather than your computer keyboard, which is not wired to the call. If the agent read back the last four digits and then went quiet, it is waiting for 1 to authorise the charge (see the key list under Keypad capture); hash does not confirm, and the capture will eventually time out and announce itself cancelled.
• The scripted voice sounds slow or deep, but the agent's normal voice is fine — the secure prompts are spoken by a separate scripted voice, so a problem there affects only the collection step. This was a bug fixed on 11 August 2026; if you still hear it, report the agent id and the provider on its voice node.
• The scripted voice sounds like a different, flatter reading of the same voice — the secure prompts now ask for the same high-quality voice engine the agent itself speaks with, and fall back to the standard one only where that voice is not offered in the integration's region. This was improved on 12 August 2026. If the two still do not match, the region on the agent's voice integration is the thing to check.
• The agent said "I didn't catch that" and repeated itself just as I started typing, and kept talking over my keypresses — fixed on 13 August 2026. The wait at each step was being counted from when the request was sent rather than when the caller finished hearing it, so a long request could use up the whole wait; and the agent stopped listening for a barge-in a moment before its own audio had finished playing, so a key pressed right at the end of the request did not stop it. Nothing was mis-collected — the digits were still received. If you see it again, report the conversation id and the Wait for digits value on the node.
• The agent promises to check on the payment and never comes back — fixed on 12 August 2026. The result of a completed collection was not reaching the model, so the agent had nothing to report and waited for you to speak first. If you see it again, report the conversation id.