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

# Payments overview

> Take card-present payments for appointments with terminals and contactless flows

Use the Payments API when the customer pays in person. You register a terminal, start a contactless payment on an appointment, then capture it when the charge succeeds.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant Terminal

    Client->>API: Register terminal
    API->>Client: Terminal ready
    Client->>API: Create terminal connection token
    API->>Client: Connection token (clientSecret)
    Client->>Terminal: Connect with device SDK
    Client->>API: Create contactless payment (idempotency key)
    API->>Client: Payment created (clientSecret)
    Client->>Terminal: Collect in-person payment
    Terminal->>Client: Charge result
    Client->>API: Capture with processor reference
    API->>Client: Payment captured
```

## What you do first

1. [Register a terminal](/api-reference/payments/register-a-terminal) for the device that will take the card.
2. [Create a terminal connection token](/api-reference/payments/create-a-terminal-connection-token) so the device SDK can talk to the processor.
3. [Create a contactless payment](/api-reference/payments/create-a-contactless-payment) on the appointment you are collecting for.
4. [Capture the contactless payment](/api-reference/payments/capture-a-contactless-payment) after the device confirms the charge.

Every write that moves money needs an [idempotency key](/api-reference/idempotency).

## States that matter

| State                 | What it means for the next call                                                                                  |
| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `created`             | Contactless payment exists; start collection on the terminal                                                     |
| `processing`          | Device or processor is still working; wait, then read the payment                                                |
| `authorized`          | Hold succeeded; [capture](/api-reference/payments/capture-a-contactless-payment) when you mean to take the money |
| `captured`            | Money is recorded on the appointment; do not capture again                                                       |
| `failed` / `canceled` | No appointment payment was recorded; create a new contactless payment to try again                               |

Read the payment when the device finishes so you know which state you got, not which one you hoped for.

## When a call fails

Failures come back as problem documents. Open the `type` link for the cause, the fix, and whether retrying is safe. Common ones on this path include contactless declines, canceled sessions, and a payment processor that is not set up yet.

## Related paths

* Appointment card holds and captures live under [Appointments](/api-reference/Appointments/overview).
* Fee quotes before you show a total live under [Fees](/api-reference/Fees/overview).
* Refunds after a capture live under [Refunds](/api-reference/Refunds/overview).