# `Worldpay.WPG.Features`
[🔗](https://github.com/iamkanishka/worldpay/blob/v1.0.0/lib/worldpay/wpg/features.ex#L1)

Advanced WPG features: DCC, Guaranteed Payments, Prime Routing,
Revenue Boost, Lodging, MAC, zero-value auth, stored credentials,
submission fulfillment, and JSC device data snippet builder.

All `Builder.*` functions return XML fragments to embed in a WPG order
or modification. Wrap with `Worldpay.WPG.Builder.envelope/2` before
submitting via `Worldpay.WPG.submit/2`.

# `account_name_inquiry`

```elixir
@spec account_name_inquiry(String.t(), String.t(), String.t()) :: String.t()
```

Build a WPG Account Name Inquiry request.

Used to verify account holder name before payouts.

# `convenience_fee_xml`

```elixir
@spec convenience_fee_xml(non_neg_integer(), String.t()) :: String.t()
```

Build an order XML with a convenience fee (WPG).

Convenience fees apply to all payment methods.

# `dcc_enquiry`

```elixir
@spec dcc_enquiry(keyword()) :: String.t()
```

Build a DCC enquiry order (step 1 — get offered rate).

Submit before the actual payment. Customer chooses their currency.
Then submit the payment with `dcc_payment/1` including their choice.

# `dcc_payment`

```elixir
@spec dcc_payment(keyword()) :: String.t()
```

Build a DCC payment after customer accepts or declines DCC offer.

## Options

- `:dcc_accepted` — boolean (customer accepted DCC?)
- `:dcc_currency` — offered currency code (if accepted)
- `:dcc_amount` — amount in offered currency (if accepted)
- `:dcc_rate` — exchange rate (if accepted)
- `:dcc_rate_type` — rate type (if accepted)
- `:dcc_margin` — margin percentage (if accepted)

# `dcc_status`

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

Parse DCC status from a WPG XML response map.

Returns one of: `"ACCEPTED"` | `"DECLINED"` | `"NOT_OFFERED"` | `"NOT_AVAILABLE"` | `nil`

# `dynamic_mcc_xml`

```elixir
@spec dynamic_mcc_xml(String.t()) :: String.t()
```

Build a dynamic MCC XML element for per-transaction MCC override.
Embed inside a WPG order `<paymentDetails>` element.

# `fast_refund`

```elixir
@spec fast_refund(keyword()) :: String.t()
```

Build a WPG Fast Refund modification (≤30 min credit).

## Options

- `:order_code` — original order code
- `:amount` — refund amount
- `:currency` — currency code

# `guaranteed_payment_order`

```elixir
@spec guaranteed_payment_order(keyword()) :: String.t()
```

Build a Guaranteed Payments (Signifyd) order with device session data.

The `web_session_id` is collected by the Signifyd JSC snippet on the
checkout page and identifies the device session for fraud assessment.

## Options

- `:web_session_id` — Signifyd device session ID (required)
- `:shopper_email` — customer email
- `:shopper_ip` — customer IP address
- `:subscription` — boolean (recurring payment?)

# `jsc_snippet`

```elixir
@spec jsc_snippet(String.t(), :try | :live) :: String.t()
```

Returns the JavaScript snippet string for WPG Device and Behavioral JSC.

Embed in checkout page HTML. The `session_id` is used as the
`webSessionId` / `<message>` in FraudSight / Guaranteed Payments requests.

## Parameters

- `session_id` — unique session identifier for the checkout session
- `environment` — `:try` | `:live`

# `lodging_xml`

```elixir
@spec lodging_xml(keyword()) :: String.t()
```

Add lodging (hotel) data to a WPG order for lower interchange.

## Options

- `:hotel_folio_number` — folio/invoice number
- `:check_in_date` — YYYY-MM-DD
- `:check_out_date` — YYYY-MM-DD
- `:duration_of_stay` — integer (nights)
- `:fire_safe_indicator` — boolean
- `:program_code` — Mastercard lodging program code
- `:charge_type` — "RESTAURANT" | "GIFTSHOP" | "MINIBAR" | "TELEPHONE" | "LAUNDRY" | "OTHER"

# `mac_code`

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

Parse Mastercard Authorization Optimizer (MAC) code from WPG response.

# `prime_routing_sale`

```elixir
@spec prime_routing_sale(keyword()) :: String.t()
```

Build a Prime Routing debit sale order.

Prime Routing routes eligible debit transactions to the lowest-cost network.
Requires Sale (not Authorization-only) transaction type.

# `revenue_boost_npt?`

```elixir
@spec revenue_boost_npt?(map()) :: boolean()
```

Parse Revenue Boost NPT upgrade from WPG response.

# `risk_factors`

```elixir
@spec risk_factors(%{required(String.t()) =&gt; term()}) :: %{
  cvc: String.t() | nil,
  avs_address: String.t() | nil,
  avs_postcode: String.t() | nil
}
```

Parse AVS and CVC risk factors from a WPG XML response.

Returns `%{cvc: "MATCHED" | "NOT_MATCHED" | "NOT_SENT_TO_ACQUIRER" | nil,
           avs_address: "MATCHED" | ... | nil,
           avs_postcode: "MATCHED" | ... | nil}`

# `stored_credentials_xml`

```elixir
@spec stored_credentials_xml(keyword()) :: String.t()
```

Add stored credential data to a WPG order.

## `reason` values:
`"UNSCHEDULED"` | `"SUBSCRIPTION"` | `"INSTALLMENT"` | `"RESUBMISSION"` |
`"REAUTHORISATION"` | `"DELAYED_CHARGE"` | `"NO_SHOW"`

## `usage` values:
`"FIRST"` | `"USED"`

# `submission_fulfillment`

```elixir
@spec submission_fulfillment(keyword()) :: String.t()
```

Build a WPG submission fulfillment modification.

Used for deferred capture: pre-orders, delayed shipping, subscriptions.
Marks an authorized order as ready for capture/settlement.

## Options

- `:order_code` — original order code
- `:fulfillment_data` — optional fulfillment metadata map

# `surcharge_xml`

```elixir
@spec surcharge_xml(non_neg_integer(), String.t()) :: String.t()
```

Build an order XML with a surcharge element (WPG).

Surcharges apply to credit cards only and cannot be combined with convenience fees.

# `zero_value_auth`

```elixir
@spec zero_value_auth(keyword()) :: String.t()
```

Build a zero-value authorization order to check card validity (WPG).

Use with CVC and AVS to validate a card without charging it.
Response includes riskFactors for CVC/AVS match results.

---

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