# Payments

## Create a payment (agent pays on a customer's behalf)

`payments.create(PaymentCreateParams**kwargs)  -> Payment`

**post** `/v3/payments`

Advances the pay flow for a connected customer handle and returns a
`status` describing where it is (`needs_connection`, `awaiting_user_action`,
`ready`, ...). A payment `id` appears once a card is minted. Idempotent on
the `Idempotency-Key` header.

### Parameters

- `amount_cents: int`

- `currency: str`

- `handle: str`

  Customer phone (E.164) or email.

- `description: Optional[str]`

- `merchant: Optional[Merchant]`

  - `name: Optional[str]`

  - `url: Optional[str]`

- `metadata: Optional[Dict[str, str]]`

### Returns

- `class Payment: …`

  - `id: Optional[str]`

  - `amount_cents: Optional[int]`

  - `approval_url: Optional[str]`

    Present when the customer must approve with a passkey.

  - `attach_url: Optional[str]`

    Present when the customer must attach a card.

  - `currency: Optional[str]`

  - `description: Optional[str]`

  - `handle: Optional[str]`

  - `status: Optional[Literal["needs_connection", "connecting", "awaiting_user_action", 6 more]]`

    - `"needs_connection"`

    - `"connecting"`

    - `"awaiting_user_action"`

    - `"ready"`

    - `"authorized"`

    - `"succeeded"`

    - `"declined"`

    - `"canceled"`

    - `"expired"`

### Example

```python
import os
from linq import LinqAPIV3

client = LinqAPIV3(
    api_key=os.environ.get("LINQ_API_V3_API_KEY"),  # This is the default and can be omitted
)
payment = client.payments.create(
    amount_cents=2500,
    currency="usd",
    handle="+14155550123",
)
print(payment.id)
```

#### Response

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount_cents": 2500,
  "approval_url": "approval_url",
  "attach_url": "attach_url",
  "currency": "usd",
  "description": "description",
  "handle": "+14155550123",
  "status": "ready"
}
```

## Get a payment

`payments.retrieve(strpayment_id)  -> Payment`

**get** `/v3/payments/{paymentId}`

Get a payment

### Parameters

- `payment_id: str`

### Returns

- `class Payment: …`

  - `id: Optional[str]`

  - `amount_cents: Optional[int]`

  - `approval_url: Optional[str]`

    Present when the customer must approve with a passkey.

  - `attach_url: Optional[str]`

    Present when the customer must attach a card.

  - `currency: Optional[str]`

  - `description: Optional[str]`

  - `handle: Optional[str]`

  - `status: Optional[Literal["needs_connection", "connecting", "awaiting_user_action", 6 more]]`

    - `"needs_connection"`

    - `"connecting"`

    - `"awaiting_user_action"`

    - `"ready"`

    - `"authorized"`

    - `"succeeded"`

    - `"declined"`

    - `"canceled"`

    - `"expired"`

### Example

```python
import os
from linq import LinqAPIV3

client = LinqAPIV3(
    api_key=os.environ.get("LINQ_API_V3_API_KEY"),  # This is the default and can be omitted
)
payment = client.payments.retrieve(
    "paymentId",
)
print(payment.id)
```

#### Response

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount_cents": 2500,
  "approval_url": "approval_url",
  "attach_url": "attach_url",
  "currency": "usd",
  "description": "description",
  "handle": "+14155550123",
  "status": "ready"
}
```

## Cancel a payment

`payments.cancel(strpayment_id)  -> Payment`

**post** `/v3/payments/{paymentId}/cancel`

Closes the virtual card and cancels the payment.

### Parameters

- `payment_id: str`

### Returns

- `class Payment: …`

  - `id: Optional[str]`

  - `amount_cents: Optional[int]`

  - `approval_url: Optional[str]`

    Present when the customer must approve with a passkey.

  - `attach_url: Optional[str]`

    Present when the customer must attach a card.

  - `currency: Optional[str]`

  - `description: Optional[str]`

  - `handle: Optional[str]`

  - `status: Optional[Literal["needs_connection", "connecting", "awaiting_user_action", 6 more]]`

    - `"needs_connection"`

    - `"connecting"`

    - `"awaiting_user_action"`

    - `"ready"`

    - `"authorized"`

    - `"succeeded"`

    - `"declined"`

    - `"canceled"`

    - `"expired"`

### Example

```python
import os
from linq import LinqAPIV3

client = LinqAPIV3(
    api_key=os.environ.get("LINQ_API_V3_API_KEY"),  # This is the default and can be omitted
)
payment = client.payments.cancel(
    "paymentId",
)
print(payment.id)
```

#### Response

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount_cents": 2500,
  "approval_url": "approval_url",
  "attach_url": "attach_url",
  "currency": "usd",
  "description": "description",
  "handle": "+14155550123",
  "status": "ready"
}
```

## Get a payment's card-reveal handoff

`payments.credentials(strpayment_id)  -> PaymentCredentialsResponse`

**get** `/v3/payments/{paymentId}/credentials`

Returns a short-lived handoff for a `ready` payment. Fetch the card
credentials **directly from the provider** with the returned `user_token`
at `fetch_url` — the card number never passes through Linq. Do not persist
PAN/CVC.

### Parameters

- `payment_id: str`

### Returns

- `class PaymentCredentialsResponse: …`

  - `handoff: Optional[Handoff]`

    Fetch the card directly from the provider with these — never through Linq.

    - `card_ref: Optional[str]`

    - `fetch_url: Optional[str]`

    - `provider: Optional[str]`

    - `user_token: Optional[str]`

      Short-lived bearer to fetch the card from the provider.

### Example

```python
import os
from linq import LinqAPIV3

client = LinqAPIV3(
    api_key=os.environ.get("LINQ_API_V3_API_KEY"),  # This is the default and can be omitted
)
response = client.payments.credentials(
    "paymentId",
)
print(response.handoff)
```

#### Response

```json
{
  "handoff": {
    "card_ref": "card_7h2k",
    "fetch_url": "https://api.agentcard.sh/api/v2/cards/card_7h2k",
    "provider": "agentcard",
    "user_token": "user_token"
  }
}
```

## Domain Types

### Payment

- `class Payment: …`

  - `id: Optional[str]`

  - `amount_cents: Optional[int]`

  - `approval_url: Optional[str]`

    Present when the customer must approve with a passkey.

  - `attach_url: Optional[str]`

    Present when the customer must attach a card.

  - `currency: Optional[str]`

  - `description: Optional[str]`

  - `handle: Optional[str]`

  - `status: Optional[Literal["needs_connection", "connecting", "awaiting_user_action", 6 more]]`

    - `"needs_connection"`

    - `"connecting"`

    - `"awaiting_user_action"`

    - `"ready"`

    - `"authorized"`

    - `"succeeded"`

    - `"declined"`

    - `"canceled"`

    - `"expired"`

### Payment Credentials Response

- `class PaymentCredentialsResponse: …`

  - `handoff: Optional[Handoff]`

    Fetch the card directly from the provider with these — never through Linq.

    - `card_ref: Optional[str]`

    - `fetch_url: Optional[str]`

    - `provider: Optional[str]`

    - `user_token: Optional[str]`

      Short-lived bearer to fetch the card from the provider.