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

PayPal as a provider: one-time payments with PayPal Orders (v2), subscriptions with billing
plans, reading a payment, refunds and webhooks. A mishka_installer plugin: supervise it to install it.

    children = [MishkaPay.Providers.PayPal]

## Keys

A site's `MishkaPay.Credentials` for `"paypal"`:

  * `:publishable_key`: the app's client id; `:secret_key`: its secret. Mishka Pay gets an OAuth
    token with them and keeps it until shortly before it expires
    (`MishkaPay.Helpers.TokenCache`).
  * `:webhook_secret`: the id of the webhook in the PayPal app (`WH-...`): PayPal checks each
    message's signature itself, given that id.
  * `:mode`: `:test` talks to PayPal's sandbox, `:live` to PayPal.

## How a payment goes

  * `checkout/2` creates an Order (`intent: CAPTURE`) with the items and totals, the return and
    cancel URLs, and the reference (with the checkout's owner, when it names one) as its
    `custom_id`; the idempotency key (`PayPal-Request-Id`)
    comes from the reference. The buyer approves it on PayPal's page and comes back to the return
    URL with the Order id in its `token` parameter.
  * PayPal takes the money only when an approved Order is captured. `fetch_checkout/2` and
    `fetch_payment/2` capture an approved Order before they answer, with a key from the Order, so
    the return page, a webhook and a sync may all ask and it is captured once.
  * The payment's id is the Order's id. `refund/2` refunds its capture, in full or in part, as
    often as the site's refund rule allows (`MishkaPay.ProviderKit`).
  * A checkout in `mode: :subscription` sells one recurring price: it makes a catalog product
    and a billing plan for it (the price every interval, after a free trial of `:trial_days`),
    then the subscription, with idempotency keys from the price and the reference. The buyer
    approves it on PayPal's page and comes back to the return URL with its id (`I-...`) in
    `subscription_id`; that id is also the checkout's id.
  * A subscription's bills are its transactions (`list_invoices/2` by `:subscription_id`), and
    its next bill is the plan's price on its next billing time. PayPal cancels a subscription at
    once (`at: :now`): a cancel at the period's end, taking one back, a customer's bills and one
    bill by id are refused.
  * `raw_request/2` calls any path of PayPal's REST API with the site's OAuth token, a write's
    body as JSON and its reference (with the method and path) as `PayPal-Request-Id`, and
    answers PayPal's JSON as it is (`{}` for an empty answer). PayPal has no API version or
    expand option: either one is refused before any request.
  * `verify_webhook/3` asks PayPal to check the message (`verify-webhook-signature`) and answers
    it as a `MishkaPay.Event` naming its Order, or its subscription (a renewal's sale names it as
    its billing agreement).

## What it refuses before any request

A currency PayPal does not take, an amount with decimals in a currency PayPal takes whole (HUF,
JPY, TWD), a price by a provider id (PayPal has no stored prices on this path), a subscription
checkout with more than one price, and a checkout that asks PayPal to sell as the merchant of
record. Metadata has no
place on a PayPal Order and is left out.

## Errors

A refused card is `MishkaPay.Errors.Declined`, anything else PayPal refuses
`MishkaPay.Errors.Rejected`. Both keep PayPal's debug id (the `PayPal-Debug-Id` header) as
`:request_id` and the error's `information_link` as `:doc_url`, for PayPal's support and the
log; their messages never show them.

`config :mishka_pay, MishkaPay.Providers.PayPal, base_url: "http://localhost:..."` points it at
another address, such as a test server.

Tested against a stand-in that answers in PayPal's shapes, and against PayPal's own sandbox
(`mix test --only paypal_live`).

# `error_return`

```elixir
@type error_return() ::
  {:error, [%{action: atom(), field: atom(), message: String.t()}]}
```

# `okey_return`

```elixir
@type okey_return() :: {:ok, struct() | map() | module() | [any()]}
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `config`

```elixir
@spec config() :: keyword()
```

# `config`

```elixir
@spec config(atom()) :: any()
```

# `enable`

```elixir
@spec enable() :: okey_return() | error_return()
```

# `get`

```elixir
@spec get() :: keyword()
```

# `health_check`

```elixir
@spec health_check() :: :ok | {:degraded, term()} | {:error, term()}
```

Optional. See `c:MishkaInstaller.Event.Hook.health_check/0`. Override to report health.

# `on_dependency_error`

```elixir
@spec on_dependency_error(term()) :: term()
```

Optional. See `c:MishkaInstaller.Event.Hook.on_dependency_error/1`. Override to react.

# `register`

```elixir
@spec register() :: okey_return() | error_return()
```

# `restart`

```elixir
@spec restart() :: okey_return() | error_return()
```

# `start`

```elixir
@spec start() :: okey_return() | error_return()
```

# `start_link`

# `stop`

```elixir
@spec stop() :: okey_return() | error_return()
```

# `unregister`

```elixir
@spec unregister() :: okey_return() | error_return()
```

---

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