Payment encryption: adds or replaces one key entry.

PUT /api/merchants/{id}/payment-encryption-bindings/{providerName}/keys/{ksi} deprecated

Requires: Merchants.Merchants.Update, merchant scope.

A key entry verb rather than a whole-binding save, so rotating one device family's key does not require sending the provider credentials back. The binding must already exist. Omitting `keyReference` keeps the stored one. `createdAtUtc`, `statusChangedAtUtc` and `isKeyReferenceConfigured` are server-owned and ignored on the body. An omitted `status` is stored as `Active` on a new entry and keeps the stored status on a replace, so correcting a retired key's label cannot return it to service: use the reactivate endpoint for that. Optionally send `If-Match: "<concurrencyStamp>"`.

Signed in, you can send this request to your own sandbox merchant from the console and read the answer. Sign in to try it.

Example request

Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key.

The request body is a PaymentEncryptionKeyEntry. See the Request body section below for its fields.

cURL PowerShell TypeScript C# Python

cURL

curl -X PUT "{{BASE_URL}}/api/merchants/{id}/payment-encryption-bindings/{providerName}/keys/{ksi}" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
  "ksi": ""
}'

PowerShell

$headers = @{
    'api-key' = '{{API_KEY}}'
}

$body = @'
{
  "ksi": ""
}
'@

$response = Invoke-RestMethod -Method PUT -Uri '{{BASE_URL}}/api/merchants/{id}/payment-encryption-bindings/{providerName}/keys/{ksi}' `
    -Headers $headers -ContentType 'application/json' -Body $body

npm install @winkpg/winkpg-api

TypeScript (SDK)

import { Configuration, MerchantPaymentEncryptionBindingApi } from '@winkpg/winkpg-api';

const api = new MerchantPaymentEncryptionBindingApi(new Configuration({
  basePath: '{{BASE_URL}}',
  apiKey: '{{API_KEY}}',
}));

const { data } = await api.merchantPaymentEncryptionBindingUpsertPaymentEncryptionKeyEntry("3fa85f64-5717-4562-b3fc-2c963f66afa6", "PROVIDER_NAME", "KSI", {
  "ksi": ""
});

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/merchants/{id}/payment-encryption-bindings/{providerName}/keys/{ksi}', {
  method: 'PUT',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "ksi": ""
  }),
});

const data = await response.json();

dotnet add package WinkPg.Api.Client

C# (SDK)

using WinkPg.Api.Client.Api;
using WinkPg.Api.Client.Client;
using System.Text.Json;

var config = new Configuration { BasePath = "{{BASE_URL}}" };
config.AddApiKey("api-key", "{{API_KEY}}");

var api = new MerchantPaymentEncryptionBindingApi(config);
var body = JsonSerializer.Deserialize<PaymentEncryptionKeyEntry>("""
    {
      "ksi": ""
    }
    """);

var result = await api.MerchantPaymentEncryptionBindingUpsertPaymentEncryptionKeyEntryAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"), "PROVIDER_NAME", "KSI", body);

C# (raw HTTP)

using System.Text;

using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") };

var request = new HttpRequestMessage(new HttpMethod("PUT"), "/api/merchants/{id}/payment-encryption-bindings/{providerName}/keys/{ksi}");
request.Headers.Add("api-key", "{{API_KEY}}");

request.Content = new StringContent("""
    {
      "ksi": ""
    }
    """, Encoding.UTF8, "application/json");

var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

pip install winkpg-api

Python (SDK)

import winkpg_api

configuration = winkpg_api.Configuration(host="{{BASE_URL}}")
configuration.api_key["ApiKey"] = "{{API_KEY}}"

with winkpg_api.ApiClient(configuration) as client:
    api = winkpg_api.MerchantPaymentEncryptionBindingApi(client)
    body = winkpg_api.PaymentEncryptionKeyEntry.from_dict({
      "ksi": ""
    })
    result = api.merchant_payment_encryption_binding_upsert_payment_encryption_key_entry("3fa85f64-5717-4562-b3fc-2c963f66afa6", "PROVIDER_NAME", "KSI", body)

pip install requests

Python (raw HTTP)

import requests

headers = {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
}

body = {
  "ksi": ""
}

response = requests.request(
    "PUT",
    "{{BASE_URL}}/api/merchants/{id}/payment-encryption-bindings/{providerName}/keys/{ksi}",
    headers=headers,
    json=body,
)
response.raise_for_status()
data = response.json()

Parameters

Name	In	Type	Description
`id` required	path	string (uuid)	The merchant id.
`providerName` required	path	string	The provider whose binding holds the key table.
`ksi` required	path	string	The key serial identifier to write (authoritative; any KSI on the body is ignored).
`suppressNulls` required	query	boolean	If true, omit properties with null values.

Request body

application/json , required

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
`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
`scheme` required	all of PaymentEncryptionScheme	Which encryption scheme the terminals under this key produce. Required: When Status != Deactivated. nullable
`dukptMode` required	all of PaymentEncryptionDukptMode	The DUKPT key derivation algorithm this key uses. nullable
`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
`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
`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
`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
`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
`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
`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
`status` required	all of 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
`requireMac` required	boolean	Reserved: whether the device family attaches a MAC that should be verified during decryption. nullable
`createdAtUtc` required	string (date-time)	When the entry was created, in UTC. nullable
`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

This request body has no documented fields.