API Usage

Bluefin PIN Translation | API Usage and Examples

Overview

This page provides API examples to enable merchants to fully integrate with the Decryptx PIN Translation service.

It covers how to construct requests that translate an encrypted PIN block from one encryption domain (card-reader device) to another (processor).


Our API supports the following encryption methods:

  • DUKPT-to-DUKPT — for processors using their own DUKPT key hierarchy
  • DUKPT-to-ZPK — for translation to the traditional Zone PIN Key used by most payment networks and issuers
    • DUKPT: This is when the PIN Block is encrypted at the terminal device using a unique key derived via DUKPT. This is considered to be the source encryption.
    • ZPK: This is when the PIN Block is re-encrypted within the secure HSM boundary under the payment processor's Zone PIN Key (ZPK). This is considered to be the destination encryption.

In a nutshell, the API takes an encrypted source PIN block and returns the translated PIN block in the format of the destination encryption, as demonstrated in the API Examples below.


For more information, including a general overview of PIN Translation and how it works, please refer to Decryptx PIN Translation | Introduction.



API Examples

Before reading this section, make sure you are familiar with Decryptx API Environments.

This section covers all supported encryption-to-encryption translations and provides a complete set of API request examples for PIN Translation, all of which are ready-to-use for your integration.

Source vs Destination Fields

The fields that start with source are obtained from the device at POS. This is when the PIN Block is encrypted at the terminal device using DUKPT from the Bluefin-injected key. This is considered to be the source encryption.

These fields include:

  • sourcePinBlock
  • sourceKsn
  • sourcePinBlockFormat (represents and specifies the PinBlockFormat)

On the other hand, the fields that start with destination represent the destination encryption domain (payment processor).



📘

PIN Block and PAN

  • PAN is mandatory for verification in both major methods — you cannot verify the PIN without it
  • PIN block formats often embed PAN digits to prevent certain attacks
  • Security: PAN + PIN are never stored together in cleartext. Everything stays in the HSM
  • For multiple processors: The PAN is what allows consistent verification regardless of the incoming encryption method




The main difference between DUKPT-to-DUKPT and DUKPT-to-ZPK is the destination encryption:

  • Use destinationKsi when translating to DUKPT
  • Use keyLabel when translating to ZPK

Note that we can only use one of these fields at a time when specifying the destination encryption, as highlighted in the Request Fields section.

DUKPT-to-DUKPT

Request

POST /api/pin-translation

{
  "partnerId": "bluefin",
  "partnerKey": "<REDACTED>",
  "clientId": "2",
  "serial": "1760039186",
  "deviceType": 1,

  // Source Encryption
  "sourceKsn": "00000005550000600001",
  "sourcePinBlock": "50B0DAB3500D5AFF",
  "sourcePinBlockFormat": "01",
  // Destination Encryption
  "destinationKsi": "555F987654",
  "destinationPinBlockFormat": "01",

  "primaryAccountNumber": "5413330089099049",
  "reference": "0001 - DECRYPTX API - PIN - Translation - DUKPT-to-DUKPT Translation Mode"
}
📘

Note

These examples use the sample reference values to illustrate the workflow for testing and documentation purposes.


Response

A successful API call outputs the following 2xx HTTP response in JSON format.

With the destinationPinBlock included in response, this means the PIN translation has been successful.

{
  "success": true,
  "messageId": "1202608251354151001866052",
  "reference": "0001 - DECRYPTX API - PIN - Translation - DUKPT-to-DUKPT Translation Mode",
  "translated": {
    "destinationKsi": "555F987654",
    "destinationPinBlock": "A188F752AEF7F36D"
  }
}


🚧

Translated PIN and PIN Verification

Once the Decryptx API returns the translated PIN block, it is ready to be used for the destination domain (processor) for PIN Verification.

It is important to note that Decryptx itself does not verify the cardholder's PIN, authorize the transaction, or choose the processor.

Your routing rules decide where the transaction goes — the processor, payment network, and issuer handle the rest.



DUKPT-to-ZPK

Request

POST /api/pin-translation

{
  "partnerId": "bluefin",
  "partnerKey": "<REDACTED>",
  "serial": "1770039279",
  "deviceType": 1,

  // Source Encryption
  "sourceKsn": "9C000200000000200097",
  "sourcePinBlock": "327CEC31D07723E4",
  "sourcePinBlockFormat": "01",
  // Destination Encryption
  "keyLabel": "ISSUER.ZPK.TEST",
  "destinationPinBlockFormat": "01",
  
  "primaryAccountNumber": "619222485434",
  "reference": "0002 - DECRYPTX API - PIN - Translation - DUKPT-to-ZPK Translation Mode"
}
📘

Note

These examples use the sample reference values to illustrate the workflow for testing and documentation purposes.


Response

A successful API call outputs the following 2xx HTTP response in JSON format.

With the destinationPinBlock included in response, this means the PIN translation has been successful.

{
  "success": true,
  "messageId": "1202608251428211001286046",
  "reference": "0002 - DECRYPTX API - PIN - Translation - DUKPT-to-ZPK Translation Mode",
  "translated": {
    "destinationPinBlock": "8CE2F238430C448E"
  }
}




Request Fields

📘

Required/Optional fields

This API does not explicitly define required or optional fields for its requests. Instead, we provide the most optimal requests above that you can integrate based on your desired translation method.

PropertyTypeDescription
partnerIdStringID provided by Bluefin for access to the PIN Translate API.
partnerKeyStringAPI key provided by Bluefin for access to the PIN Translate API.
clientIdStringOptional identifier for the partner client that owns this device. Configured by the partner at provisioning time. Provides additional uniqueness when serial numbers are not unique across manufacturers, and enables reporting at the client level. All devices for a partner must have a unique combination of Serial Number + Client. If Client is not used, Serial Numbers must be unique within the partner.
serialStringThe serial number of the device.
deviceTypeNumberThe device type generating the encrypted PIN block.
reference (optional)StringA string (up to 50 characters) used to identify individual API calls. If provided, the value will be logged and returned in the response body. It is recommended that a unique value be used for each call. This value will be logged to the P2PE Manager where it can be used to troubleshoot technical issues.
sourcePinBlockStringHex encoded encrypted PIN block obtained from the device.
sourceKsnStringKey Serial Number (KSN) obtained from the device. Required for DUKPT-based encryption. This field is exclusively used when the source encryption is DUKPT.
sourcePinBlockFormatStringPIN block format of the incoming device-encrypted PIN block. It can be provided by the POS PIN terminal or pre-configured in Device. This parameter is optional.
See PinBlockFormat.
keyLabelStringThis is the processor key label, used as an identifier of which configured Zone PIN Key (ZPK) should be used for translation. When this field is present, do not specify the destinationKsi.
This field is exclusively used for DUKPT-to-ZPK.
Provide exactly one of keyLabel or destinationKsi.
destinationKsiStringThis is the processor key label, used as an identifier of which configured DUKPT key should be used for translation. KSI stands for Key Set Identifier and is provided in hex format.
This field is exclusively used for DUKPT-to-DUKPT
Provide exactly one of keyLabel or destinationKsi.
destinationPinBlockFormatStringDesired PIN block format for the translated PIN block. It can be provided by the POS PIN terminal or pre-configured in Device. This parameter is optional.
See PinBlockFormat.
primaryAccountNumberStringPrimary Account Number (PAN) associated with the transaction. Required for ISO PIN block formats that incorporate PAN data.
This PAN value is provided in plain text, unencrypted.


PinBlockFormat

📘

Encryption Algorithms (What Actually Protects the Data)

DUKPT manages key generation and is paired with a standard encryption algorithm to protect the data itself. The algorithms most commonly used with DUKPT are:

  • TDES / 3DES (Triple Data Encryption Standard) — The older, traditional algorithm used with DUKPT.
  • AES (Advanced Encryption Standard) — The modern, highly secure standard officially approved by ANSI for DUKPT. AES DUKPT uses larger key sizes to securely support very high transaction volumes.
Thales FormatISO FormatDescriptionAlgorithm supportedDefault
010ISO 9564-1 & ANSI X9.8 format 0DES/3DESEnabled
02-Docutel ATM formatDES/3DESDisabled
03-Diebold & IBM ATM formatDES/3DESDisabled
04-PLUS Network formatDES/3DESDisabled
051ISO 9564-1 format 1DES/3DESEnabled
342Standard EMV 1996 formatDES/3DESDisabled
35-Mastercard Pay Now & Pay Later formatDES/3DESEnabled
41-Visa/Amex new PIN only formatDES/3DESEnabled
42-Visa/Amex new & old PIN formatDES/3DESEnabled
473ISO 9564-1 & ANSI X9.8 format 3DES/3DESEnabled
484ISO 9564-1 format 4AESEnabled


Response Fields

A successful API call outputs a JSON object with the following properties.

PropertyTypeDescription
successBooleanIndicates whether the translation was successful.
referenceStringEchoes the reference value provided in the request, if supplied.
messageIdStringBluefin assigned unique identifier for each API response. This value should be stored for troubleshooting purposes.
translatedObjectThe translated PIN block encrypted under the destination domain (processor): ZPK or DUKPT.

translated

PropertyTypeDescription
destinationKsiStringThis is the processor key label, used as an identifier of which configured DUKPT key has been used for translation. KSI stands for Key Set Identifier and is provided in hex format.
This field is exclusively returned when the DUKPT-to-DUKPT translation has been performed.
destinationPinBlockStringDestination PIN Block. The PIN block encrypted under the Destination Key. This is the final translated PIN subsequently used for PIN Verification.
failedBooleantrue if the PIN translation has failed
messageStringHuman readable error message indicating why the call failed.
codeStringPragmatic code for specific failure reasons.

Did this page help you?