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

Hosted Checkout sessions.

Redirects customers to a Teya-hosted payment page. Your server creates a session
and receives the `session_url` to redirect the customer to. Teya handles the
payment UI and redirects back to your `success_url` or `failure_url` when done.

Required OAuth scopes: `checkout/sessions/create`, `checkout/sessions/id/get`.

# `create_session`

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

Creates a hosted checkout session.

Returns `{:ok, %{"session_id" => id, "session_url" => url}}` on success.
Redirect the customer to `session_url` to complete payment.

## Required params

- `amount` — `%{"currency" => "GBP", "value" => 1000}` (value in minor units, max 9_223_372_036_854)
- `type` — `"SALE"` or `"PRE_AUTHORISATION"`

## Optional params

- `billing_address`, `cancel_url`, `customer`, `customer_success_email`,
  `failure_url`, `language` (IETF BCP 47, e.g. `"en-GB"`), `line_items`,
  `merchant_reference` (max 60 chars), `merchant_success_email`, `metadata`
  (max 10 keys), `post_success_payment` (`"SHOW_SUCCESS_PAGE"` or `"REDIRECT"`),
  `required_customer_fields`, `store_id` (UUID), `success_url`

## Options

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

## Examples

    params = %{
      "amount" => %{"currency" => "GBP", "value" => 1000},
      "type" => "SALE",
      "success_url" => "https://example.com/success",
      "failure_url" => "https://example.com/failure"
    }

    {:ok, %{"session_url" => url}} = Teya.Checkout.create_session(params)

# `get_session`

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

Retrieves a checkout session by its ID.

The response includes `session_status` (`"ACTIVE"`, `"PROCESSING"`, `"COMPLETED"`,
`"EXPIRED"`) and `payment_status` (`"NONE"`, `"SUCCESS"`, `"FAILED"`).

## Examples

    {:ok, session} = Teya.Checkout.get_session(session_id)
    session["payment_status"]  # "SUCCESS"

---

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