# SurchargeQuoteRequestDto

A model the API reference uses in a request or a response. The operation pages link every field typed as this model here.

Request for the authenticated, merchant-scoped surcharge-eligibility quote endpoint. A direct API
integrator supplies a BIN prefix (never a full PAN), the transaction amount, the cardholder state,
and the presentment channel; the platform evaluates surcharge eligibility and returns a
`SurchargeQuoteResultDto`.

## Fields
- `merchantId` (string(uuid)) required: The merchant the quote is for.
- `binPrefix` (string) required: The card BIN prefix: 6 to 8 digits only. A full PAN (or any value longer than 8 digits) is  rejected at validation. Used to resolve the card brand, funding source, and issuer country. (nullable, pattern ^[0-9]{6,8}$)
- `amount` (number(double)): The base transaction amount a surcharge would apply to, in the transaction currency. (greater than 0)
- `cardholderState` (string): The cardholder billing state code (2-letter, e.g. CO), or null when unknown. Governs the  per-state cap / prohibition. Merchant-state rules are applied authoritatively at auth time. Conditional: When CardholderState is not empty. (nullable)
- `channel` ([TransactionSource](https://devportal.demo.winkpg.io/docs/api/models/TransactionSource.md)): The presentment channel the quote is for. Defaults to `Api`, the  natural channel for a direct integrator; surcharge eligibility is channel-restricted.
  Values:
  - `Unknown`: The source of the transaction is unknown or not specified.
  - `VirtualTerminal`: The transaction originated from a virtual terminal interface.
  - `Api`: The transaction was initiated through an API call.
  - `HostedPaymentPage`: The transaction was processed via a hosted payment page.
  - `RecurringBilling`: The transaction is part of a recurring billing cycle.
  - `OfflineBatch`: The transaction was processed as part of an offline batch.
  - `Invoicing`: The transaction is an automatic charge against an invoice (e.g. a recurring-invoice auto-charge or a smart-retry attempt) submitted by the Invoicing module.

## See also

- [All documentation](https://devportal.demo.winkpg.io/llms.txt): the machine-readable index of every public page on this site.