ZPK

1. Overview

This document explains how a Merchant Connect integration retrieves or refreshes a terminal-level ZPK (Zone PIN Key) before an offline card PIN transaction.

The ZPK endpoint is a key-management API. It does not authorize a card transaction and does not call a PSP. The returned ZPK is encrypted under the configured institution-level ZMK/BDK. The terminal or an approved secure component uses the returned key material to encrypt a PIN block, and sends the returned checkValue with the later Payment request so Merchant Connect can locate the correct ZPK version.

3DES clarification: In this document, 3DES means Triple DES encryption for PIN-block processing. It is not 3DS (3-D Secure cardholder authentication).

Item	Description
Interface	ZPK retrieval
Method	`GET`
Path	`/g2/v1/payment/mer/{sid}/zpk?terminalID={terminalID}`
Protocol	HTTPS + JSON response
Initiator	Merchant Host or approved POS integration
Request body	None
Key source	Institution-level ZMK/BDK
Key scope	Institution + store `sid` + terminal ID
PIN algorithm	3DES in the current release
PSP call	None
Follow-up operation	Use `checkValue` in an offline card Payment request

The {sid} value represents the merchant/store identifier assigned to the target environment. It must not be hard-coded in a production integration.

2. Get a zpk

Location	Field	Required	Type	Length	Description
Path	`sid`	Yes	String	32	Store identifier. It is also the store dimension of the ZPK binding.
Query	`terminalID`	Yes	String	8	Registered terminal identifier. It is the terminal dimension of the ZPK binding.

The request has no JSON body. The server derives the institution dimension by resolving the store represented by {sid}.

3. Authentication Headers

Header	Required	Description
`Authorization`	Yes	Merchant Connect signature.
`Content-Type`	Yes	`application/json; charset=utf-8`.
`DateTime`	Yes	ISO 8601 message timestamp.
`MsgID`	Yes	Merchant-generated request trace identifier.
`SignType`	Yes	Configured signing method, such as `SHA256`, `SHA512`, `HMAC-SHA256`, or `HMAC-SHA512`.
`KeyID`	Conditional	Required when multi-level signing keys are enabled.
`Idempotency-Key`	Not applicable	This GET endpoint has no request body; follow the deployment's standard GET retry and tracing policy.

4. Key Scope and Lifecycle

4.1 Key scope

Merchant Connect V1 uses terminal-level isolation for ZPK storage and lookup:

Dimension	Scope	Description
Key source	Institution	BDK/ZMK is configured at institution level.
Store	`sid`	The store is resolved from the request path.
Terminal	`terminalID`	Each registered terminal has an independent ZPK.
Version	`checkValue`	Each generated ZPK version is identified by its check value.

A ZPK must not be reused across different stores or terminals. The same institution-level ZMK/BDK may be the derivation source, but the resulting ZPK binding remains terminal-specific.

4.2 Rotation and expiry

Rule	Behavior
Current ZPK	The latest ZPK for a terminal remains the current key until another ZPK is retrieved.
Previous ZPK	When a new ZPK is generated, the previous version remains usable for one hour.
Version timing	Each previous key has its own one-hour window; requesting another key does not extend older versions.
Lookup	Payment processing uses `checkValue` to locate the terminal's current or still-valid previous ZPK.
Missing or expired version	Merchant Connect returns `B0034`; the terminal should retrieve a new ZPK before retrying the related PIN transaction.

5. Response Fields

Field path	Required on success	Type	Length	Description
`result`	Yes	Object	—	Common response result container.
`result.code`	Yes	String	8	Response code. Success is `S0000`; key or validation failures use the documented error code.
`result.message`	Yes	String	1024	Human-readable response message.
`zpk`	Yes on success	Object	—	ZPK result container. It is omitted on failure.
`zpk.status`	Yes on success	String	20	Result status: `Success` or `Failed`.
`zpk.zpk`	Yes on success	String	32	ZPK ciphertext encrypted under the institution ZMK. It is not the plaintext ZPK.
`zpk.checkValue`	Yes on success	String	6	Six-character hexadecimal check value used to identify the ZPK version during Payment processing.

6. Request and Response Examples

All values below are placeholders. Do not replace them with production key material in documentation or source control.

6.1 Request

The request has no body.

6.2 Successful response

{
  "result": {
    "code": "S0000",
    "message": "Success"
  },
  "zpk": {
    "status": "Success",
    "zpk": "{{zpkCiphertext}}",
    "checkValue": "{{checkValue}}"
  }
}

zpk.zpk is an encrypted ZPK ciphertext. The integration must use the approved secure key-management process to unwrap it; the plaintext ZPK must never be exposed in logs, source code, or ordinary application storage.

6.3 Failure response: institution key is not configured

{
  "result": {
    "code": "B0049",
    "message": "ZMK not exist"
  }
}

7. Using the ZPK in an Offline Card Payment

After a successful ZPK response:

The terminal or approved secure component unwraps the returned ZPK using the configured secure key process.

The terminal encrypts the PIN block with the current-release 3DES method.

The terminal sends the encrypted PIN and the returned check value in the Payment request.

Merchant Connect locates the ZPK using the institution, store, terminal, and check value.

If the check value identifies a current or less-than-one-hour-old previous key, Merchant Connect continues PIN processing.

If the check value cannot be found or has expired, Merchant Connect returns B0034; retrieve a new ZPK and follow the approved retry policy.

Representative Payment fields:

{
  "paymentMethod": {
    "type": "card",
    "card": {
      "pin": {
        "encryptedPin": "{{encryptedPinBlock}}",
        "pinEncryptMethod": "3DES",
        "checkValue": "{{checkValue}}"
      }
    }
  },
  "transInitiator": {
    "platform": "POS",
    "paymentScenario": "inStore",
    "terminalID": "{{terminalId}}"
  }
}

The exact card, amount, currency, entry-mode, and terminal fields must follow the Payment API contract. This section only shows the ZPK-dependent PIN fields.

8. Validation and Error Handling

The exact HTTP status and message format must follow the deployed Merchant Connect error table. Common ZPK outcomes include:

Code	Meaning	Client action
`S0000`	ZPK retrieved successfully	Securely process the ciphertext and retain `checkValue`.
`C0000`	Institution not found	Check the store configuration and institution mapping.
`C0002`	Store not found	Correct the `sid` and do not retry unchanged.
`C0003`	Terminal not found under the requested store, including a cross-store terminal	Verify the store-terminal relationship and `terminalID`.
`B0001`–`B0004`	Group, merchant, store, or terminal status is invalid	Correct the resource status before retrying.
`B0005`	Offline/ZPK capability is not enabled	Enable the required product and configuration.
`B0049`	Institution ZMK/BDK is not configured	Configure the applicable institution key through the approved key-management process.
`B0034`	Payment `checkValue` is missing, unknown, or expired	Retrieve a new ZPK and retry according to the transaction retry policy.
`E0000`	System error	Follow the deployment retry and support procedure; do not log key material.

Do not blindly repeat a failed request when the cause is a resource, configuration, or key-version error.

1. Overview#

2. Get a zpk#

3. Authentication Headers#

4. Key Scope and Lifecycle#

4.1 Key scope#

4.2 Rotation and expiry#

5. Response Fields#

6. Request and Response Examples#

6.1 Request#

6.2 Successful response#

6.3 Failure response: institution key is not configured#

7. Using the ZPK in an Offline Card Payment#

8. Validation and Error Handling#