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

# Call Transfer

> At payment time the live call moves to a payment line, and a checkout token rides the transfer carrying all the authorization that line needs to finish the one payment.

Call transfer is how payment happens when your agent does not run it itself: at payment time the
live call moves from your order agent to a **payment line**, the caller pays there in the same
phone call, and the confirmation is spoken before the call ends. By default that line is Ringup's
hosted one, so you write no payment logic; the same mechanism also lets you
[build a line of your own](/integrations/custom/transfer).

## The two destinations

Every [`create_checkout`](/concepts/checkout-session) response carries both ways to move the call,
and you always receive both:

* **`transfer_to`** is a SIP URI. Its user part is the **checkout token**, so the session rides
  the transfer itself. Platforms that dial SIP use this lane.
* **`transfer_to_number`** is a plain phone number, for platforms that can only transfer to a
  number. It routes to Ringup's hosted payment line, which resolves the session server-side by
  the caller's number. No configuration: a platform that cannot dial SIP just uses the number.

Either lane lands the caller on the payment line mid-call. When the merchant configured a
hand-back, the session's `return_to` carries where to send the caller after payment.

## What rides the transfer: the checkout token

The line that answers a `transfer_to` leg holds no account key and needs none: the token in the
URI is all the authorization it gets. It is a **session-scoped credential**: a valid, unexpired
token authorizes acting on exactly the one session it names, whatever account owns that session.
The token carries the checkout session id as its `k` claim and nothing else; the amount, the
caller, and the cards all come from reading the session it names. The line reads the token off
the leg and presents it as a bearer credential:

```bash theme={null}
Authorization: Bearer <CHECKOUT_TOKEN>
```

<Note>
  Ringup's own hosted payment line is built on nothing but this. It reads the session, offers the
  card, sends the link, and charges with the token: exactly the four calls below. Any developer can
  build the same line the same way; the number lane's session lookup is internal to Ringup, so a
  line you build completes transfers through `transfer_to` only.
</Note>

## What the payment line does

The token is accepted on exactly four operations, each pinned to its own session. It can touch no
other session and cannot create, list, or read anything else.

<Steps>
  <Step title="Read the session">
    Get the amount, the caller's name if known, the transfer-back destination, and the cards
    chargeable at this merchant: everything you need to decide what to say next.
  </Step>

  <Step title="Offer the saved card, or text a link">
    If `cards` is non-empty, offer the newest one and [charge](/concepts/charge) it. If it is empty,
    [send a link](/concepts/send-link): a first-time caller pays on the web and the card is saved for
    next time.
  </Step>

  <Step title="Confirm">
    The session read also carries the charge status, so you learn the outcome from the same object.
    Your server still receives a `checkout.succeeded` [webhook](/concepts/webhooks).
  </Step>
</Steps>

## Read the session

```bash theme={null}
curl https://api.ringup.dev/v1/checkout_sessions/cs_test_7f21ab \
  -H "Authorization: Bearer <CHECKOUT_TOKEN>"
```

```json Response theme={null}
{
  "session_status": "open",
  "payment_required": "required",
  "amount_cents": 1850,
  "currency": "USD",
  "caller_first_name": "Sam",
  "cards": [
    { "instrument_id": "inst_a1", "brand": "visa", "last_four": "1111", "expiry": "2029-01" }
  ],
  "default_card_id": "inst_a1",
  "return_to": "sip:agent@your-number",
  "charge": null
}
```

`caller_first_name` lets you greet a returning caller by name before you know whether they have a
card. `cards` is already narrowed to what is chargeable at this merchant, so the newest card is
safe to offer as is.

## Charge the saved card

```bash theme={null}
curl -X POST https://api.ringup.dev/v1/charge \
  -H "Authorization: Bearer <CHECKOUT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "instrument_id": "inst_a1" }'
```

The token pins the charge to its session, so you do not pass a session id: the amount, merchant, and
caller all come from the session the token names.

## Text a link for a first-time caller

```bash theme={null}
curl -X POST https://api.ringup.dev/v1/send_link \
  -H "Authorization: Bearer <CHECKOUT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

The caller taps the link and pays on the [pay page](/concepts/send-link), which enrolls and charges
the card with the same token. In test mode the card to type is `4111 1111 1111 1111`. Hold the call
if you like: the payment lands as a webhook whether the caller pays now or after they hang up.

## Scope and lifetime

<Warning>
  The token authorizes completing **one** payment, and only for its short lifetime (30 minutes). It
  belongs to the payment line that took the transfer, not in a log, a URL you share, or client-side
  storage beyond the pay page it was minted for.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Build your own payment line" icon="code" href="/integrations/custom/transfer">
    The Custom Platform guide: recognize, create the checkout, transfer, hear the result.
  </Card>

  <Card title="Charge" icon="credit-card" href="/concepts/charge">
    The recognized-caller path: run a saved card directly.
  </Card>
</CardGroup>
