providerName
required |
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.
nullablemax length 64
Values:
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.
|
isEnabled
required |
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
Values:
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.
|
credentialSource
required |
PaymentEncryptionCredentialSource
PaymentEncryptionCredentialSource |
Whose provider account the decryption calls are billed to. Null reads as
`Gateway`.
nullable
Values:
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.
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
required |
array of PaymentEncryptionBindingFieldValue
array of PaymentEncryptionBindingFieldValue |
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
Values:
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.
|
Fields of each PaymentEncryptionBindingFieldValue:
| Field |
Type |
Description |
|---|
key
required |
string
|
The provider setting name this value belongs to, matching a
`PaymentEncryptionSettingFieldDefinition.SettingName` the provider's contributor
declares. Compared case-insensitively.
nullable
Values:
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.
| value
required |
string
|
The configured value. Ciphertext at rest whenever `isSecret` is `true`, and
`null` on every read that leaves the server.
nullable
Values:
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.
| isSecret
required |
boolean
|
Whether `value` is credential material, and so held encrypted and stripped on read.
nullable
Values:
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.
| isConfigured
required |
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
Values:
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.
|
This body has no documented fields. |
keyEntries
required |
array of PaymentEncryptionKeyEntry
array of PaymentEncryptionKeyEntry |
The key serial identifier entries that map an inbound key serial number to an HSM key.
Conditional: When KeyEntries is not null.
nullable
Values:
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.
|
Fields of each PaymentEncryptionKeyEntry:
| Field |
Type |
Description |
|---|
ksi
required |
string
|
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
Values:
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.
| label
required |
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.
nullablemax length 100
Values:
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.
| scheme
required |
PaymentEncryptionScheme
PaymentEncryptionScheme |
Which encryption scheme the terminals under this key produce.
Required: When Status != Deactivated.
nullable
Values:
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.
Dukpt |
Generic DUKPT (ANSI X9.24 data variant), TDES or AES. | OnGuard |
The Ingenico On-Guard protocol. |
| dukptMode
required |
PaymentEncryptionDukptMode
PaymentEncryptionDukptMode |
The DUKPT key derivation algorithm this key uses.
nullable
Values:
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.
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
required |
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.
nullablemax length 16
Values:
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.
| keyReference
required |
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>
nullablemax length 1024
Values:
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.
| isKeyReferenceConfigured
required |
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
Values:
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.
| majorKey
required |
string
|
The major key the reference is stored under, in the provider's own token vocabulary. Null leaves
the provider's default in force.
nullablemax length 16
Values:
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.
| onGuardExtendedEncryption
required |
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
Values:
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.
| onGuardEndingPanDigitsEncrypted
required |
boolean
|
Whether the device family encrypts the ending PAN digits. Meaningful only for
`OnGuard`.
Conditional: When Scheme is not null and Scheme != OnGuard.
nullable
Values:
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.
| onGuardClearPanDigits
required |
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
Values:
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.
| status
required |
PaymentEncryptionKeyEntryStatus
PaymentEncryptionKeyEntryStatus |
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:
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.
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
required |
boolean
|
Reserved: whether the device family attaches a MAC that should be verified during decryption.
nullable
Values:
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.
| createdAtUtc
required |
string (date-time)
|
When the entry was created, in UTC.
nullable
Values:
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.
| statusChangedAtUtc
required |
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
Values:
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.
|
This body has no documented fields. |
primaryEndpoint
required |
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.
nullablemax length 512
Values:
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.
|
secondaryEndpoint
required |
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.
nullablemax length 512
Values:
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.
|
decryptTimeoutMillisecondsOverride
required |
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
Values:
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.
|