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

Online transactions for embedded payment flows.

Use this when you control the payment UI (embedded card form, Apple Pay, or
stored tokens). For a Teya-hosted UI, see `Teya.Checkout`.

The API supports 3DS flows: a `"REDIRECT_TRANSACTION_RESPONSE"` type in the
response means the customer must complete a 3DS challenge at the returned URL
before the transaction is finalised.

Required OAuth scopes: `transactions/online/create`, `transactions/online/id/get`.

# `create`

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

Processes an online transaction.

Returns `{:ok, response}` where `response["type"]` is one of:
- `"ONLINE_TRANSACTION"` — transaction completed; check `response["online_transaction"]["status"]`
- `"REDIRECT_TRANSACTION_RESPONSE"` — 3DS challenge required; redirect the customer

Transaction statuses: `"SUCCESS"`, `"FAILURE"`, `"PENDING"`.

## Required params

- `amount` — `%{"currency" => "GBP", "value" => 1000}`
- `initiator` — `"CUSTOMER"` or `"MERCHANT"`
- `payment_method` — `%{"type" => "CARD", "card" => %{...}}` (see below)
- `store_id` — UUID
- `type` — `"SALE"`, `"PRE_AUTHORISATION"`, or `"ACCOUNT_VERIFICATION"`

## Payment method types

Card: `%{"type" => "CARD", "card" => %{"number" => "...", "expiry_month" => "12",
"expiry_year" => "2028", "cvc" => "123"}}`

Token: `%{"type" => "TOKEN", "token" => %{"token_id" => uuid,
"recurring_payment_type" => "CARD_ON_FILE"}}`

Apple Pay: `%{"type" => "APPLE_PAY", "apple_pay_authentication_data" => %{...}}`

## Optional params

- `billing_address`, `browser_data` (required for 3DS; must include `ip_address`,
  `screen_height`, `screen_width`), `cardholder`, `customer_contact`, `line_items`,
  `merchant_reference_id` (max 60 chars), `redirect_url`, `shipping_address`,
  `store_payment_method`

## Options

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

## Examples

    params = %{
      "amount" => %{"currency" => "GBP", "value" => 1000},
      "type" => "SALE",
      "initiator" => "CUSTOMER",
      "store_id" => store_id,
      "payment_method" => %{
        "type" => "CARD",
        "card" => %{"number" => "4111111111111111", "expiry_month" => "12",
                    "expiry_year" => "2028", "cvc" => "123"}
      }
    }

    case Teya.Transaction.create(params) do
      {:ok, %{"type" => "ONLINE_TRANSACTION", "online_transaction" => txn}} ->
        txn["status"]  # "SUCCESS" | "FAILURE" | "PENDING"
      {:ok, %{"type" => "REDIRECT_TRANSACTION_RESPONSE"} = resp} ->
        resp["redirect_transaction_response"]["redirect_url"]
    end

# `get`

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

Retrieves an online transaction by its authentication ID.

`authentication_id` is returned in the `create/2` response.

## Examples

    {:ok, txn} = Teya.Transaction.get(authentication_id)
    txn["status"]  # "SUCCESS" | "FAILURE" | "PENDING"

---

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