Call Transfer

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.

The two destinations

Every create_checkout 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:

Authorization: Bearer <CHECKOUT_TOKEN>

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.

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.

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.

Offer the saved card, or text a link

If cards is non-empty, offer the newest one and charge it. If it is empty, send a link: a first-time caller pays on the web and the card is saved for next time.

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.

Read the session

curl https://api.ringup.dev/v1/checkout_sessions/cs_test_7f21ab \
  -H "Authorization: Bearer <CHECKOUT_TOKEN>"

Response

{
  "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

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

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, 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

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.

Next steps

Build your own payment line

The Custom Platform guide: recognize, create the checkout, transfer, hear the result.

Charge

The recognized-caller path: run a saved card directly.

Get started

Concepts

Developer integrations

Merchant integrations

The two destinations

What rides the transfer: the checkout token

What the payment line does

Read the session

Charge the saved card

Text a link for a first-time caller

Scope and lifetime

Next steps

Build your own payment line

Charge

​The two destinations

​What rides the transfer: the checkout token

​What the payment line does

​Read the session

​Charge the saved card

​Text a link for a first-time caller

​Scope and lifetime

​Next steps

Build your own payment line

Charge

The two destinations

What rides the transfer: the checkout token

What the payment line does

Read the session

Charge the saved card

Text a link for a first-time caller

Scope and lifetime

Next steps