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:
sourcePinBlocksourceKsnsourcePinBlockFormat(represents and specifies thePinBlockFormat)
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
destinationKsiwhen translating to DUKPT - Use
keyLabelwhen 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"
}
NoteThese 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 VerificationOnce 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"
}
NoteThese 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 fieldsThis 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.
| Property | Type | Description |
|---|---|---|
partnerId | String | ID provided by Bluefin for access to the PIN Translate API. |
partnerKey | String | API key provided by Bluefin for access to the PIN Translate API. |
clientId | String | Optional 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. |
serial | String | The serial number of the device. |
deviceType | Number | The device type generating the encrypted PIN block. |
reference (optional) | String | A 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. |
sourcePinBlock | String | Hex encoded encrypted PIN block obtained from the device. |
sourceKsn | String | Key Serial Number (KSN) obtained from the device. Required for DUKPT-based encryption. This field is exclusively used when the source encryption is DUKPT. |
sourcePinBlockFormat | String | PIN 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. |
keyLabel | String | This 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. |
destinationKsi | String | This 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. |
destinationPinBlockFormat | String | Desired 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. |
primaryAccountNumber | String | Primary 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 Format | ISO Format | Description | Algorithm supported | Default |
|---|---|---|---|---|
01 | 0 | ISO 9564-1 & ANSI X9.8 format 0 | DES/3DES | Enabled |
02 | - | Docutel ATM format | DES/3DES | Disabled |
03 | - | Diebold & IBM ATM format | DES/3DES | Disabled |
04 | - | PLUS Network format | DES/3DES | Disabled |
05 | 1 | ISO 9564-1 format 1 | DES/3DES | Enabled |
34 | 2 | Standard EMV 1996 format | DES/3DES | Disabled |
35 | - | Mastercard Pay Now & Pay Later format | DES/3DES | Enabled |
41 | - | Visa/Amex new PIN only format | DES/3DES | Enabled |
42 | - | Visa/Amex new & old PIN format | DES/3DES | Enabled |
47 | 3 | ISO 9564-1 & ANSI X9.8 format 3 | DES/3DES | Enabled |
48 | 4 | ISO 9564-1 format 4 | AES | Enabled |
Response Fields
A successful API call outputs a JSON object with the following properties.
| Property | Type | Description |
|---|---|---|
success | Boolean | Indicates whether the translation was successful. |
reference | String | Echoes the reference value provided in the request, if supplied. |
messageId | String | Bluefin assigned unique identifier for each API response. This value should be stored for troubleshooting purposes. |
translated | Object | The translated PIN block encrypted under the destination domain (processor): ZPK or DUKPT. |
translated
translated| Property | Type | Description |
|---|---|---|
destinationKsi | String | This 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. |
destinationPinBlock | String | Destination PIN Block. The PIN block encrypted under the Destination Key. This is the final translated PIN subsequently used for PIN Verification. |
failed | Boolean | true if the PIN translation has failed |
message | String | Human readable error message indicating why the call failed. |
code | String | Pragmatic code for specific failure reasons. |
Updated about 15 hours ago
