GuidesAPI ReferenceRelease Notes

P2PE Decrypt Function

This function can be used to decrypt data that was previously encrypted at a point-of-interaction (POI) device or payment terminal. This function can be used as part of a PCI-Validated P2PE Solution, or as part of a non-validated end-to-end encryption (E2EE) solution.

Suggest Edits

Supported Encryption Algorithms

This P2PE Decrypt function is intended to be used with symmetric encryption algorithms only. Supported encryption algorithms:

  • AES_128

This function also expects the provided ciphertext to be decrypted using DUKPT. Thus, along with the ciphertext, a Key Serial Number (KSN) must be provided as an input to use this function.

Groups

A group is defined as one or more invocations of the P2PE Decrypt function within a request that share the same value for the group parameter. The value itself is an arbitrary string. Groups can be used if multiple functions need to parse plaintext from the same shared ciphertext, or if more than one ciphertext needs to be decrypted and parsed within the same request.

If a function in a group contains the KSN and CIPHERTEXT parameters, it is said to be decryptable. Additional functions for the same group in the same request can extract additional fields from the same decrypted plaintext.

🚧

At least one function must be decryptable within a group. Each group can have only one unique ciphertext and KSN pair.

Parseable Fields

This function can parse the decrypted plaintext, to pass individual fields within the request body to the destination API. The "FIELD" input parameter can have the following values:

Field ValueDescriptionExample
PANThe primary account number.5454545454545454
NMCardholder Name in track data format.LAST MIDDLE/FIRST
EDExpiration date of the payment card.2401
SCService Code.201
DDDiscretionary Data.224840100000000725000000
T1Track 1 data including start and end sentinels and LRC.%B5454545454545454^Doe/John A^27012010000123000?
T1NSTrack 1 data excluding start and end sentinels and LRC.B5454545454545454^Doe/John A^27012010000123000
T2Track 2 data including start and end sentinels and LRC.%5454545454545454^27010000123000?
T2NSTrack 2 data excluding start and end sentinels and LRC.5454545454545454^27010000123000
CVVThe 3-4 digit security code.533

📘

When the expiry date field is parsed (ED), you can specify the date format using the EXPDATEFORMAT parameter. Supported formats include: yyMM (default if omitted), MMyy, yyyyMM, MMyyyy, MM, yyyy, and yy.

Parameter NameExample ValueNote
FUNCTIONP2PEDecryptRequired. Name of the function.
GROUPpan1GroupRequired. Customer-defined string.
KSN101720230000000200000006Required in at least one function in a group. This alphanumeric field is output from the POI device along with the ciphertext.
CIPHERTEXTEA712B2752BCD5B87AA478A831481A7595AFDCDD9BC5A9A6488A
39345D617120B2453CCF9AB0145344819320DB787FBC1C42FC1BB34
A752D744510431B9178C8D861A75D1BC51697CBDB80C00EEFAD4C3
767F6D463F276E3F6700C49D6E7C01269811A0258ABA1B15466CC17
5ED58647A95A7CE237671EEF2AE393DF59A6FDF5		Required in at least one function in a group. Hexadecimal encoded ciphertext to be decrypted. Output from POI device.
FIELDEDRequired. The field to parse from the plaintext.
EXPDATEFORMATyyMMOnly used when "Field" is set to "ED". Defaults to yyMM when omitted.
DEVICESERIALNUMBER3031194953336321Required. The serial number of the physical device that originated the ciphertext.
DEVICEFIRMWAREVERSION2.1.14Optional. Version of the firmware on your device at the time of encryption.
{
    "PaymentInstrument1": {
        "name": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group1,FIELD:NM}}}}",
        "card": {
            "number": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group1,KSN:101720230000000100000001,CIPHERTEXT:D093069FE96C60A3D3A9C19D3D8EC6EF76E66207B9D537D31A4C24D571A319D9D8EDFA5C7A605D9C3CC6320873312DE7E83A9C97F3B498722A2EC3F135899643,FIELD:PAN}}}}",
            "expiry": {
                "month": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group1,FIELD:ED,EXPDATEFORMAT:MM}}}}",
                "year": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group1,FIELD:ED,EXPDATEFORMAT:YY}}}}",
                "yyMM": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group1,FIELD:ED}}}}",
                "MMyy": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group1,FIELD:ED, EXPDATEFORMAT:MMyy}}}}"
            }
        },
        "serviceCode": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group1,FIELD:SC}}}}",
        "discretionaryData": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group1,FIELD:DD}}}}",
        "track1": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group1,FIELD:T1}}}}",
        "track1NS": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group1,FIELD:T1NS}}}}",
        "track2": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group1,FIELD:T2}}}}",
        "track2NS": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group1,FIELD:T2NS}}}}"
    },
    "PaymentInstrument2": {
        "card": {
            "number": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group2,KSN:101720230000000100000002,CIPHERTEXT:E56821BF821DA1149CDD0A8A1D8E5C8A369D4D3A97329B73ADCF878EF9C3B661FBCFD177355A33694731592605840B08DFDE24A0504F71CA41DD603307D4719D,FIELD:PAN}}}}",
            "expiry": {
                "month": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group2,FIELD:ED,EXPDATEFORMAT:MM}}}}",
                "year": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group2,FIELD:ED,EXPDATEFORMAT:YY}}}}",
                "yyMM": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group2,FIELD:ED}}}}",
                "MMyy": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group2,FIELD:ED, EXPDATEFORMAT:MMyy}}}}"
            }
        },
        "discretionaryData": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group2,FIELD:DD}}}}"
    }
}

{
  "card": {
    "number": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group3,KSN:101720230000000100000003,CIPHERTEXT:65419C09071CAA1FB4F826541D825793BADE143BF1F968306832569DA4703EEB0C97CCD49CC4119D6E0D5053D1946A276B80AF9C27AA3F1188958863F948F400,FIELD:PAN}}}}",
    "expiry": {
      "month": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group3,FIELD:ED,EXPDATEFORMAT:MM}}}}",
      "year": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group3,FIELD:ED,EXPDATEFORMAT:YY}}}}",
      "yyMM": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group3,FIELD:ED}}}}",
      "MMyy": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group3,FIELD:ED, EXPDATEFORMAT:MMyy}}}}"
    },
    "securityCode": "{{{{FUNCTION:P2PEDECRYPT,GROUP:Group3,FIELD:CVV}}}}"
  }
}

Response Headers

In the response that the Transparent Gateway returns from the 3rd party API, TokenEx will include a header with a TokenEx Universal Token representing the PAN (if PAN was available).

📘

The returned token will use the token scheme specified in the tx-token-scheme request header.

Response HeaderExample Value
tx-token-1545454UvcgHo5454
tx-token-2444433SEKWRT1111

Updated 24 days ago