# TokenStoredCredentialConsentInput

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

The cardholder's stored-credential consent, captured outside the platform (on a payment terminal's
screen, by signature, or verbally) at the moment the card was read. Send it on the call that mints
the token, together with the customer the card is being stored for, and the platform records the
consent against the customer's stored payment method.

## Fields
- `capturedAtUtc` (string(date-time)) required: When the cardholder agreed, in UTC. Required. A time more than five minutes in the future is refused. Conditional: When CapturedAtUtc is not null. Conditional: When CapturedAtUtc meets a condition. (nullable)
- `method` ([ConsentCaptureMethod](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ConsentCaptureMethod.md)) required: How the cardholder agreed. Required. A terminal sends `OnScreen` for acceptance on its screen, `SignedForm` for a signature, or `InPerson` for verbal agreement at the counter; `Phone`, `Email`, `OnlineForm` and `Other` are accepted too. (nullable)
  Values:
  - `InPerson`: In-person interaction. Cardholder was physically present.
  - `Phone`: Phone call with the cardholder (potentially recorded).
  - `SignedForm`: Paper / digital form signed by the cardholder.
  - `Email`: Email exchange in which cardholder agreed.
  - `OnlineForm`: Online form on the merchant's own website / app.
  - `OnScreen`: The cardholder accepted the terms on a device screen at the point of sale, such as a payment terminal or a tablet, at the moment the card was read.
  - `Other`: Other method not captured above. Operators / merchants use the notes field or merchant reference to explain.
- `allowedUsages` ([StoredCredentialUsage](https://devportal.signapay-sbx.winkpg.io/docs/api/models/StoredCredentialUsage.md)): The future uses the cardholder agreed to, as flags: `Recurring`, `Installment`, `UnscheduledCOF` and `OneTimeFuture`, combined when the cardholder agreed to more than one. Required, and at least one flag must be set. Conditional: When AllowedUsages != None. Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
  Values:
  - `None`: No permitted uses. Consent record is effectively inactive.
  - `Recurring`: Scheduled recurring charges (subscriptions, membership dues). Maps to Recurring.
  - `Installment`: Fixed-schedule installment plans dividing a known total. Maps to Installment.
  - `UnscheduledCOF`: Merchant-triggered charges for pre-agreed events (balance top-ups, usage overages, no-show fees, delayed charges). Maps to several MIT reason codes including UnscheduledCOF, NoShow, DelayedCharge, and IncrementalAuth.
  - `OneTimeFuture`: A single known future cardholder-initiated purchase the credential was saved for (e.g. "save card for my next order"). Not used for MITs.
- `consentTextVersion` (string) required: The version of the consent text the cardholder was shown, as returned by the stored-credential consent configuration endpoint. Required, up to 200 characters. (nullable, max length 200)
- `evidenceReference` (string): Your own reference to the evidence you kept, such as the identifier of a stored signature image or a terminal log line. Optional, up to 200 characters. Shown on the consent's evidence in the back office. (nullable, max length 200)
- `enrollmentTerms` ([EnrollmentTermsInput](https://devportal.signapay-sbx.winkpg.io/docs/api/models/EnrollmentTermsInput.md)): The payment terms the cardholder agreed to. Required when `allowedUsages` includes `Recurring` or `Installment`, and then the amount, frequency and duration must each be set. Conditional: When EnrollmentTerms is not null. Required: When IncludesRecurringOrInstallment(AllowedUsages) is true.
  Fields:
  - `amount` (string): Free-text description of the amount (e.g. "$29.99 per month", "Based on usage during the preceding billing cycle"). Conditional: When Amount is not null. Max length: 500. (nullable)
  - `frequency` (string): Free-text description of the charge frequency (e.g. "Monthly, on the anniversary of my enrollment date", "As transactions occur"). Conditional: When Frequency is not null. Max length: 500. (nullable)
  - `duration` (string): Free-text description of how long the authorization remains in effect. Conditional: When Duration is not null. Max length: 500. (nullable)
  - `fixedAmount` (number(double)): Optional fixed amount per charge, in the transaction currency. When set, variable-amount notice detection uses this as the baseline to detect drift in upcoming recurring charges. Conditional: When FixedAmount is not null. Must be >= 0. Required: When CardPriceDisclosed is true. (nullable)
  - `amountRangeDescription` (string): Optional human-readable agreed-range description (e.g. "between $10 and $100 based on usage"). Conditional: When AmountRangeDescription is not null. Max length: 500. (nullable)
  - `convenienceFee` (string): Optional free-text description of a convenience fee charged on every charge under this authorization, in addition to `amount` (e.g. "$2.50 per payment"). Persisted as part of the agreed terms so the fee the cardholder accepted at enrollment is recoverable per occurrence, not only from the merchant's configuration as it stands later. Conditional: When ConvenienceFee is not null. Max length: 500. (nullable)
  - `cardPrice` (string): Optional free-text statement of the card price charged to a card on every charge under this authorization, for a merchant that posts a cash price and a card price (e.g. "$104.00 per payment, against a cash price of $100.00"). Persisted as part of the agreed terms so the price the cardholder accepted at enrollment is recoverable from the consent. Recording it does not by itself let a recurring charge be charged the card price: that takes the card price the platform states for the merchant, recorded with the consent (see `cardPriceDisclosed`). Conditional: When CardPrice is not null. Max length: 500. (nullable)
  - `cardPriceDisclosed` (boolean): Set to true when you showed the cardholder the merchant's card price for each payment before they agreed, for a merchant that posts a cash price and a card price. Whenever it is true, `fixedAmount` is required and must be greater than zero: it is the cash price of each payment. A card price is recorded only on a card consent that includes `Recurring` or `Installment`, for a merchant whose program covers recurring billing; any other consent records none. The platform prices that amount from the merchant's own configuration and records the card price it states with the consent, so later charges under the consent can be charged the card price, never more than it states. Leave `cardPrice` out and the platform records its own statement of the card price; send it and it must be that statement exactly (for example "$104.00 per payment, against a cash price of $100.00"), or no card price is recorded. The card price is never taken from the request. False or absent records no card price, and every charge under the consent is the cash price. (nullable)

## See also

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