# MerchantPaymentEncryptionBinding

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

Per-merchant payment encryption provider binding. Persisted as an element of
`Merchant.PaymentEncryptionBindings`.
            


The binding belongs to the merchant, so every decryption for that merchant uses it, including
decryptions that run in the background with no signed-in operator.

            


Collection membership decides whether the merchant is boarded with that provider at all, and
`isEnabled` decides whether it is currently switched on: the same two-level shape the tax
and 3-D Secure bindings use, so a merchant can be switched off without losing its keys.

## Fields
- `providerName` (string): Which payment encryption provider this entry binds the merchant to, by the provider's registered  name. Compared case-insensitively. A null or blank provider is treated as no binding at all, so an  incompletely boarded row cannot silently become a live selection. Required: When IsEnabled is true. (nullable, max length 64)
- `isEnabled` (boolean): Master enable flag for this provider on this merchant. When `false` or null, the selector  must not return this binding even though the row exists. (nullable)
- `credentialSource` ([PaymentEncryptionCredentialSource](https://devportal.demo.winkpg.io/docs/api/models/PaymentEncryptionCredentialSource.md)): Whose provider account the decryption calls are billed to. Null reads as  `Gateway`. (nullable)
  Values:
  - `Gateway`: The gateway's own provider account. The binding stores no credential of its own: the values are filled in at read time from the host-scoped provider settings, and the merchant surfaces never carry them. This is what a null credentialSource reads as, which is the safe default: a half-completed row cannot accidentally claim to hold the merchant's own contract.
  - `Merchant`: The merchant's own provider account. The binding carries the credentials, with every secret value held as ciphertext and stripped on any read that leaves the server.
- `fieldValues` (array<[PaymentEncryptionBindingFieldValue](https://devportal.demo.winkpg.io/docs/api/models/PaymentEncryptionBindingFieldValue.md)>): The provider-declared configuration values for this merchant, keyed by the setting names the  provider declares.                   <b>Secret values are stored encrypted</b> and are stripped, not decrypted, on every read that  leaves the server. Only the server-side call to the provider ever uses the plaintext.                     Empty for a `Gateway` binding, whose values are  filled in at read time from the host-scoped provider settings instead. A gateway-sourced row that  carried values would be a copy of the gateway's credentials living on a merchant document. Conditional: When FieldValues is not null. (nullable)
  Fields of each item:
  - `key` (string): The provider setting name this value belongs to, matching a  `PaymentEncryptionSettingFieldDefinition.SettingName` the provider's contributor  declares. Compared case-insensitively. (nullable)
  - `value` (string): The configured value. Ciphertext at rest whenever `isSecret` is `true`, and  `null` on every read that leaves the server. (nullable)
  - `isSecret` (boolean): Whether `value` is credential material, and so held encrypted and stripped on read. (nullable)
  - `isConfigured` (boolean): Whether a secret value is stored, set on reads so an operator can tell a configured secret from  an empty one without the value ever being sent. (nullable)
- `keyEntries` (array<[PaymentEncryptionKeyEntry](https://devportal.demo.winkpg.io/docs/api/models/PaymentEncryptionKeyEntry.md)>): The key serial identifier entries that map an inbound key serial number to an HSM key. Conditional: When KeyEntries is not null. (nullable)
  Fields of each item:
  - `ksi` (string) required: The key serial identifier: six to ten significant hex characters, stored upper-case with leading  `F` padding stripped. Unique within a binding. Conditional: When Ksi is not empty. (nullable)
  - `label` (string): An operator-facing label for this key, such as the device family it was injected into. Shown  wherever the key reference itself must not be. (nullable, max length 100)
  - `scheme` ([PaymentEncryptionScheme](https://devportal.demo.winkpg.io/docs/api/models/PaymentEncryptionScheme.md)): Which encryption scheme the terminals under this key produce. Required: When Status != Deactivated. (nullable)
    Values:
    - `Dukpt`: Generic DUKPT (ANSI X9.24 data variant), TDES or AES.
    - `OnGuard`: The Ingenico On-Guard protocol.
  - `dukptMode` ([PaymentEncryptionDukptMode](https://devportal.demo.winkpg.io/docs/api/models/PaymentEncryptionDukptMode.md)): The DUKPT key derivation algorithm this key uses. (nullable)
    Values:
    - `Tdes`: Triple DES DUKPT (ANSI X9.24 Part 1).
    - `Aes`: AES DUKPT (ANSI X9.24 Part 3). Carries a working-key type alongside it.
  - `aesWorkingKeyType` (string): The AES working-key type, required when `dukptMode` is  `Aes` and meaningless otherwise. A provider token value  rather than an enum, because the vocabulary belongs to the vendor's command set. Required: When DukptMode == Aes. Conditional: When DukptMode is not null and DukptMode != Aes. (nullable, max length 16)
  - `keyReference` (string): The HSM key reference: a storage-table slot or a wrapped key block. <b>Always stored encrypted,  and never returned on a read that leaves the server.</b> (nullable, max length 1024)
  - `isKeyReferenceConfigured` (boolean): Whether a key reference is stored, set on reads so an operator can tell a configured key from an  empty one without the reference ever being sent. Server-owned: the save paths ignore whatever  arrives here. (nullable)
  - `majorKey` (string): The major key the reference is stored under, in the provider's own token vocabulary. Null leaves  the provider's default in force. (nullable, max length 16)
  - `onGuardExtendedEncryption` (boolean): On-Guard extended encryption, when the device family uses it. Meaningful only when  `scheme` is `OnGuard`. Conditional: When Scheme is not null and Scheme != OnGuard. (nullable)
  - `onGuardEndingPanDigitsEncrypted` (boolean): Whether the device family encrypts the ending PAN digits. Meaningful only for  `OnGuard`. Conditional: When Scheme is not null and Scheme != OnGuard. (nullable)
  - `onGuardClearPanDigits` (integer(int32)): How many leading PAN digits the device family leaves in the clear. Meaningful only for  `OnGuard`. Conditional: When Scheme is not null and Scheme != OnGuard. Conditional: When OnGuardClearPanDigits is not null. Range: 0 to 6. (nullable)
  - `status` ([PaymentEncryptionKeyEntryStatus](https://devportal.demo.winkpg.io/docs/api/models/PaymentEncryptionKeyEntryStatus.md)): Whether the entry may be matched. Null reads as  `Deactivated`: an entry whose status nobody set has  not been through the boarding step that activates it, and matching it would use a key the  platform cannot confirm is live. (nullable)
    Values:
    - `Active`: The entry may be matched against an inbound key serial number.
    - `Deactivated`: The entry is retired. It stays readable for explaining past transactions, and is never matched.
  - `requireMac` (boolean): Reserved: whether the device family attaches a MAC that should be verified during decryption. (nullable)
  - `createdAtUtc` (string(date-time)): When the entry was created, in UTC. (nullable)
  - `statusChangedAtUtc` (string(date-time)): When `status` last changed, in UTC. Separate from the audit log because it is shown  on the key table itself, where an operator decides whether a key is still in rotation. (nullable)
- `primaryEndpoint` (string): The primary provider endpoint for this merchant, or null to use the provider's own configured  endpoint. HTTPS-only, enforced by the binding validator. Conditional: When PrimaryEndpoint is not empty. (nullable, max length 512)
- `secondaryEndpoint` (string): The secondary provider endpoint, used when the primary does not answer. HTTPS-only. Null when the  merchant is bound to one region only. Conditional: When SecondaryEndpoint is not empty. Conditional: When SecondaryEndpoint is not empty and PrimaryEndpoint is empty. (nullable, max length 512)
- `decryptTimeoutMillisecondsOverride` (integer(int32)): A per-merchant override of the gateway-wide decryption budget, in milliseconds, or null to use  the gateway setting. Conditional: When DecryptTimeoutMillisecondsOverride is not null. Range: 250 to 30000. (nullable)

## See also

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