# Voice payments

Take a card payment during a phone call with an AI agent or a person. The caller types the card on their keypad into Twilio `<Pay>`; the digits go straight to the gateway, and neither PayLynks nor the agent hears them.

## Requirements

The call must be on a Twilio account (or sub-account) with **PCI Mode** on and a **Stripe Pay Connector**. Name the connector per session (`pay_connector`) or in the merchant's gateway settings.

## Flow

```bash
curl -X POST https://paylynks.io/api/v1/voice_sessions -H "Authorization: Bearer $PAYLYNKS_SECRET_KEY" \
  -H "Content-Type: application/json" -d '{
    "amount": 4250, "description": "Order 1042", "caller_phone": "+19135550142",
    "return_url": "https://agent.example.com/twiml/after-payment"
  }'
```

Return the response's `twiml` from your call webhook (it redirects the call to PayLynks). Then:

1. The caller hears the amount and any surcharge policy, and keys in the card.
2. PayLynks prices that card and says: "Your Visa credit card ending in 4 2 4 2. The total is $43.78, which includes a $1.28 credit card surcharge. Press 1 to pay, 2 for a different card, 3 for a text with a payment link."
3. On 1 it charges, reads a confirmation code, texts a receipt, and redirects to `return_url` (or hangs up).
4. After three failed card entries, or on 3, it texts a payment link instead.

Session statuses: `created`, `collecting`, `awaiting_confirmation`, `succeeded`, `link_sent`, `failed`, `expired` (sessions last an hour). Events: `voice_session.created`, `voice_session.succeeded`.

## Returning callers

- `GET /api/v1/voice_sessions/:id/saved_cards` — the caller's saved cards (matched by customer or phone).
- `POST /api/v1/voice_sessions/:id/charge_saved` `{payment_method}` — returns a quote for the agent to read out; send it again with `expected_total` once the caller agrees.

`POST /:id/send_link` texts a link on request. `save_card: true` at creation keeps the card for next time (the caller must agree).