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

# Secure payment capture: take card numbers in a live call

> Guide to agent-assisted secure payment on the Orbit live softphone. Masked-DTMF card entry descopes agents from card data while recording pauses for the capture window.

# Secure payment capture on the live softphone

An agent mid-conversation often needs to take payment: a deposit, an
invoice balance, a booking. Reciting a card number over the line puts
the agent in scope for PCI DSS, and letting the card number land in a
call recording puts you out of compliance. Orbit's **secure payment
capture** removes both problems: the caller types the card number on
their keypad, the agent never hears the digits, and recording pauses
for the capture window.

## How it works

1. The agent clicks **Secure payment** on the live softphone (or your
   integration calls the start endpoint below).
2. Orbit pauses recording for that window and masks the caller's
   keypad tones. The agent cannot hear the digits and the digits never
   appear in the stored media or the live transcript.
3. The caller enters each field (card number, expiry, CVV) by keypad.
   Your payment service provider (PSP) tokenizes the card off the
   voice path.
4. Once the PSP confirms tokenization, the session completes and
   recording resumes. If the caller bails or the agent backs out, the
   agent cancels the session instead. Either way, Orbit stores only a
   masked summary: the card's last four digits and brand.

The full card number never passes through Orbit. Send a full card
number to the complete endpoint and the request is rejected.

## Start a capture session

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/voice/calls/call_9f2c4a/secure-payment/start \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fields": ["pan", "expiry", "cvv"] }'
```

`fields` accepts any of `pan`, `expiry`, `cvv`, `postal_code`, and
defaults to `["pan", "expiry", "cvv"]` when omitted. The response
returns a `session_id`; hold on to it for complete or cancel.

A session starts only on a live, bridged call leg. Calls routed purely
through the SIP trunk or an AI-agent pipeline without a bridged leg
return `422 SECURE_PAYMENT_UNSUPPORTED`. If a capture is already in
progress on the call, start returns `409 SECURE_PAYMENT_ALREADY_ACTIVE`
— complete or cancel the active session first.

## Complete the session

After the PSP tokenizes the card, confirm the capture. Orbit resumes
recording, unmasks the keypad, and stores the masked summary.

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/voice/calls/call_9f2c4a/secure-payment/complete \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sp_call_9f2c4a_1",
    "card_last4": "4242",
    "card_brand": "visa"
  }'
```

`card_last4` must be exactly four digits. `card_brand` and an opaque
`psp_token_ref` string from your PSP are optional; both are stored so
your reconciliation job can pull them together later. Never send the
full card number — the request is rejected with
`422 SECURE_PAYMENT_INVALID_MASK`.

## Cancel the session

Caller changes their mind, or the PSP is unreachable — cancel instead.
Recording resumes and no card summary is stored.

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/voice/calls/call_9f2c4a/secure-payment/cancel \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "sp_call_9f2c4a_1" }'
```

Completing or cancelling a session that is already finished returns
`409 SECURE_PAYMENT_NOT_ACTIVE`. An unknown `session_id` returns
`404 SECURE_PAYMENT_SESSION_NOT_FOUND`.

From the dashboard, the agent triggers all three steps from the
**Secure payment** control on the live softphone, and a past call's
detail page shows the masked summary and the capture timeline for each
session.

## Webhooks

Subscribe to `call.secure_payment.started`,
`call.secure_payment.completed`, and `call.secure_payment.cancelled`
to drive your PSP tokenization flow. The completed event carries the
`card_last4` and `card_brand`, so a listener can post the masked
summary straight into your order system. See
[Webhook Events](/webhooks/events).

## Compliance notes

* **Recording** resumes automatically on complete or cancel. If your
  tenant requires a recording-consent receipt on resume, pass the
  receipt id in the request — Orbit returns a validation error rather
  than resume without consent. See
  [Recording library](/voice/recording-library).
* **Manual pause is not enough:** a capture that still uses manual
  recording pause leaves the agent able to hear the card digits.
* **PCI scope:** masked-DTMF capture follows the same widely accepted
  descoping pattern used by PCI Pal and Sycurio. Confirm your PCI scope
  with your PSP and qualified security assessor.

## Cross-references

* [Recording library](/voice/recording-library) — start, pause, and
  resume recording and how paused segments appear on the call record
* [Voice quickstart](/voice/quickstart) — place your first live call
* [Webhook events](/webhooks/events) — subscribe to
  `call.secure_payment.*`
* [Consent management](/compliance/consent-management) — recording-consent receipts and manual pause