# `Teya.PayByLink`
[🔗](https://github.com/sgerrand/ex_teya/blob/v0.4.0/lib/teya/pay_by_link.ex#L1)

Pay By Link — generate and manage shareable payment links.

Payment links can be sent to customers via email, SMS, or any channel. Each link
is single-use by default and expires at a configurable time.

Required OAuth scopes: `payment-links/create`, `payment-links/id/get`,
`payment-links/id/update`.

# `create`

```elixir
@spec create(
  map(),
  keyword()
) :: {:ok, map()} | {:error, Teya.Error.t()}
```

Creates a payment link.

Returns `{:ok, %{"payment_link_id" => id, "payment_link" => url}}` on success.

## Required params

- `amount` — `%{"currency" => "GBP", "value" => 1000}`

## Optional params

- `billing_address`, `cancel_url` (HTTPS), `customer`, `customer_success_email`,
  `delivery_info`, `expires_at` (ISO 8601 datetime), `language` (IETF BCP 47),
  `line_items`, `merchant_reference` (max 60 chars), `merchant_success_email`,
  `metadata` (max 10 keys), `post_success_payment`, `required_customer_fields`,
  `store_id` (UUID), `success_url` (HTTPS),
  `supported_card_brands` (`"AMEX"`, `"MASTERCARD"`, `"VISA"`, ...),
  `supported_payment_methods` (`"CARD"`, `"TOKEN"`, `"APPLE_PAY"`),
  `transaction_type` (`"SALE"`, `"PRE_AUTHORISATION"`, `"ACCOUNT_VERIFICATION"`),
  `type` (`"SINGLE_USE"`)

## Options

- `idempotency_key` — override the auto-generated idempotency key

## Examples

    {:ok, %{"payment_link" => url}} =
      Teya.PayByLink.create(%{
        "amount" => %{"currency" => "GBP", "value" => 5000},
        "expires_at" => "2024-12-31T23:59:59Z"
      })

# `get`

```elixir
@spec get(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Teya.Error.t()}
```

Retrieves a payment link by its ID.

The response includes `status`: `"VALID"`, `"COMPLETED"`, `"MANUALLY_EXPIRED"`,
`"DISABLED"`, or `"EXPIRED"`.

## Examples

    {:ok, link} = Teya.PayByLink.get(payment_link_id)
    link["status"]  # "VALID" | "COMPLETED" | "EXPIRED"

# `update`

```elixir
@spec update(String.t(), map(), keyword()) :: {:ok, map()} | {:error, Teya.Error.t()}
```

Updates a payment link.

Currently supports updating `expires_at` (ISO 8601 datetime string) to extend
or shorten the link's validity.

## Options

- `idempotency_key` — override the auto-generated idempotency key

## Examples

    {:ok, _} = Teya.PayByLink.update(payment_link_id, %{"expires_at" => "2025-06-30T23:59:59Z"})

---

*Consult [api-reference.md](api-reference.md) for complete listing*