# `MishkaPay.Providers.PayPal.Mapper`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/lib/mishka_pay/providers/__paypal/mapper.ex#L5)

Mishka Pay's structs to PayPal's request bodies, and PayPal's answers (Orders v2, captures,
refunds, catalog products, billing plans, subscriptions and their transactions, webhook events)
back to Mishka Pay's structs. Pure: no request is made here.

# `capture`

```elixir
@spec capture(map()) :: map() | nil
```

The Order's capture, the payment PayPal took, or nil before it is captured.

# `checkout`

```elixir
@spec checkout(map()) :: MishkaPay.Checkout.t()
```

An Order read back on its own, as a checkout: what PayPal filled in and the reference.

# `checkout`

```elixir
@spec checkout(map(), MishkaPay.Checkout.t()) :: MishkaPay.Checkout.t()
```

The checkout with PayPal's answer: the Order's id, its approval page and status.

# `custom_id`

```elixir
@spec custom_id(MishkaPay.Checkout.t()) :: String.t() | nil
```

PayPal keeps one caller field, `custom_id` (127 characters at most): the reference alone, or,
when the checkout names its owner, both as `r=<reference>&o=<owner>`, read back by
`reference/1` and `owner/1`. Nil when the checkout has neither.

# `event`

```elixir
@spec event(map(), boolean()) ::
  {:ok, MishkaPay.Event.t()} | {:error, Splode.Error.t()}
```

A PayPal webhook event as a `MishkaPay.Event`, naming the Order it concerns (the Order itself,
or the Order a capture or refund belongs to) or the subscription. `live?` says whose keys checked it.

# `invoice`

```elixir
@spec invoice(map(), String.t()) ::
  {:ok, MishkaPay.Invoice.t()} | {:error, Splode.Error.t()}
```

One of a subscription's transactions (`GET /v1/billing/subscriptions/{id}/transactions`) as a
`MishkaPay.Invoice`: what one bill took, when.

# `order_params`

```elixir
@spec order_params(MishkaPay.Checkout.t()) :: map()
```

The body of `POST /v2/checkout/orders`: one purchase unit with the items and their total, the
reference as `custom_id`, and the return and cancel URLs for the buyer.

# `owner`

```elixir
@spec owner(String.t() | nil) :: String.t() | nil
```

The owner in a `custom_id/1`, nil when the checkout named none.

# `payment`

```elixir
@spec payment(map()) :: {:ok, MishkaPay.Payment.t()} | {:error, Splode.Error.t()}
```

An Order as a `MishkaPay.Payment`: its id is the payment's id; its capture says whether it was
paid, and the capture's refunds how much went back.

# `plan_params`

```elixir
@spec plan_params(String.t(), MishkaPay.Price.t(), MishkaPay.Checkout.t()) :: map()
```

The body of `POST /v1/billing/plans`: the price's amount charged every interval, with no end,
after a free trial of the checkout's `:trial_days` when it has one. A quantity is allowed, so
the plan charges the amount for each one.

# `product_params`

```elixir
@spec product_params(MishkaPay.Price.t()) :: map()
```

The body of `POST /v1/catalogs/products`: the product a subscription's plan sells.

# `reference`

```elixir
@spec reference(String.t() | nil) :: String.t() | nil
```

The reference in a `custom_id/1`.

# `refund`

```elixir
@spec refund(map(), MishkaPay.Refund.t()) ::
  {:ok, MishkaPay.Refund.t()} | {:error, Splode.Error.t()}
```

The refund with PayPal's answer: its id, status, amount and time.

# `refund_params`

```elixir
@spec refund_params(MishkaPay.Refund.t()) :: map()
```

The body of `POST /v2/payments/captures/{id}/refund`: the amount when it is not the whole.

# `subscription`

```elixir
@spec subscription(map()) ::
  {:ok, MishkaPay.Subscription.t()} | {:error, Splode.Error.t()}
```

A subscription read with its plan (`?fields=plan`) as a `MishkaPay.Subscription`: its one price
from the plan's regular cycle, the period from its last and next bill, and `:trialing` while
the plan's trial runs.

# `subscription_checkout`

```elixir
@spec subscription_checkout(map(), MishkaPay.Checkout.t() | nil) ::
  MishkaPay.Checkout.t()
```

A subscription made or read back, as its checkout: the buyer approves it on PayPal's page and
comes back with its id in `subscription_id`; once approved the checkout is complete and names it.

# `subscription_params`

```elixir
@spec subscription_params(String.t(), MishkaPay.Price.t(), MishkaPay.Checkout.t()) ::
  map()
```

The body of `POST /v1/billing/subscriptions`: the plan, the quantity, the reference as
`custom_id`, the buyer's email when known, and the return and cancel URLs.

# `upcoming_invoice`

```elixir
@spec upcoming_invoice(map()) ::
  {:ok, MishkaPay.Invoice.t()} | {:error, Splode.Error.t()} | nil
```

The next bill of an active subscription read with its plan: the plan's price for each one of
its quantity, on its next billing time. Nil when PayPal will not bill it again.

---

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