API Reference
Start typing to search…

KLV Lookup

Key-Length-Value (KLV) is a data encoding standard where the Key identifies the data, Length specifies the data’s length and Value is the data itself.
KLV is an instance of the TLV encoding scheme used for optional information elements within communication protocols.

The length of each string is:

  1. A Key indicator of 3 digits, zero left padded.
  2. A Length indicator of 2 digits, zero left padded.
  3. A Value with the number of characters as specified by the Length indicator.

It is important to note:

  • Keys do not need to be in any particular order or sequence within transactionData.
  • Customers must be able to receive all keys available within transactionData.
  • Customers may ignore keys not pertinent to processing.
  • You must be able to successfully process messages that contain new unannounced keys.
  • Available keys are subject to change and will often be customer specific, thus these will be communicated via means other than this API documentation.
    For example, the KLV 00206AB48DE026044577 contains:
    1. Key 002 with length 06 and value AB48DE
    2. Key 026 with length 04 and value 4577
  • Transactions may or may not contain keys depending on the type of transaction.
  • Transaction types which include KLV data are:
    • Balance
    • Deduct
    • Deduct Reversals
    • Deduct Adjustment
    • Load Auth
    • Load Adjustment
    • Load Auth Reversal
    • Load Reversal
    • Stop

KLV Data

Key Name

Index

Values

Additional Information

Applicable to

Tracking Number

002

Card tracking number

Virtual & Physical

Original Transaction Amount

004

Original amount of the incoming transaction

Virtual & Physical

Conversion Rate

010

Forex conversion rate at the time of the transaction. The same value received from the network is echoed in the companion call. The leftmost digit of this field signifies the number of decimal places in the rate, and the remaining 7 digits give the actual rate. For example, 69972522 represents 9.972522

Virtual & Physical

Merchant category code

026

The four digit MCC that defines the sort of merchant making the transaction

Virtual & Physical

Acquiring Institution Code

032

The code for the Acquiring Institution

Virtual & Physical

Retrieval Reference Number

037

The retrieval reference number of the transaction

Virtual & Physical

Terminal ID

041

The terminal ID where the transaction is done

Virtual & Physical

Merchant Identifier

042

The merchant identifier for the transaction

Virtual & Physical

Merchant Description

043

The merchant description for the data

Virtual & Physical

Merchant name

044

Merchant name provided as part of tokenization messages

Tokenization

Transaction type Identifier

045

Transaction type Identifier "TTI" used for funding

Virtual, physical and Money send

Fraud scoring data

048

Fraud score received in transaction message

Mastercard only

Virtual & Physical

Original Currency Code

049

The original currency code of the transaction

Virtual & Physical

From Account

050

  • Indicate cardholder account type : 00 = Default Account (Not specified or not applicable)
  • 10 = Savings Account
  • 20 = Checking Account
  • 30 = Credit Card Account
  • Note: This type of multiple account card is currently specific to South American markets.

Virtual & Physical

Pin Block

052

A PIN block in 3DES ISO-1 format

Physical

POS Data

061

Data from the POS terminal used in the transaction

Physical

TraceID

063

Additional data received from Mastercard Network DE 48, Sub element 63

Virtual & Physical

Extended payment code

067

Code indicating extended payment transaction

Virtual & Physical

Is recurring

068

Indicates that a transaction is recurring

Virtual & Physical

message reason code

069

4 digit

can be empty

All card types and transactions

Markup Amount

085

The markup amount applied to the transaction

Virtual & Physical

Recipient Name

108

Name of the recipient of the funds in the transaction

Moneysend

Recipient address

109

Street address of the person who receives the funds in the transaction

Moneysend

Recipient account number

110

The account number of the person who receives the funds

Moneysend

Recipient account number type

111

The account type of the person who receives the funds

Moneysend

Capture Mode

250

  • ***Note: We are in a transition period to implement a new behavior of this KLV index. KLV 250 will be used in conjunction with KLV 262 to show capture mode and transaction type.
  • MAG - Magstripe
  • MAN - Manual (Terminal)
  • EMV - EMV
  • OB - On Behalf (EMV)
  • NFC - NFC (EMV)
  • ECOM - Ecommerce
  • 3DS - 3D-Secure (Ecommerce)
  • ADJ - Adjustment

Virtual & Physical

Network

251

Local Mastercard VISA CUP Unknown Adjustment

Virtual & Physical

Fee Type

252

  • 0 - No fee
  • 31 - Insufficient Funds
  • 32 - Withdrawal Limit Exceeded
  • 33 - Security Violation
  • 34 - Transaction Not Supported
  • 35 - PIN Tries Exceeded
  • 36 - Invalid PIN
  • 37 - PIN Length Error
  • 38 - Expired Card

Virtual & Physical

Last four digits PAN

253

The account number's last four digits of the card being swiped.

Physical

MDES Digitized PAN

254

The PAN which was digitized

Tokenization - MDES

MDES Digitized Wallet ID

255

The Wallet ID (Wallet Reference) used to digitize the card. <br> 327 - M4M <br> 216 - Google Pay <br> 217 - Samsung Pay <br> 103 - Apple Pay

Tokenization - MDES

Adjustment Reason

256

  • 99 - Generic reason
  • 00 - MasterCard initiated
  • 01 - Forex conversion difference
  • 02 - Settlement without authorization
  • 03 - Reversal timeout/ not accepted
  • 04 - Refund
  • 05 - Chargeback
  • 06 - MoneySend
  • 07 - Purchase Cancellation - ONLY applicable to Union Pay
  • 08 - Purchase Cancellation Reversal - ONLY applicable to Union Pay
  • 09 - Stand-in
  • 10 - Mass Transit Debt Collection
  • 11 - Final settlement - Unused funds
  • 26 - OCT (Visa only)

Virtual, Physical and Moneysend

Reference ID

257

Transaction ID of the original Deduct if any

Virtual & Physical

Markup Type

258

0 - No markup <br> 1 - Regular markup <br> 2 - DCC markup

Virtual & Physical

Acquirer Country

259

Country of the acquirer of a transaction

Virtual & Physical

Mobile number

260

Data containing the mobile number entered

Virtual & Physical

Transaction Fee Amount

261

Fee amount applicable to the incoming transaction if any

Always sent in the 'Deduct' call

Virtual & Physical

Transaction subtype

262

***Note: We are in a transition period to implement a new behavior of this KLV index. KLV 250 will be used in conjunction with KLV 262 to show capture mode and transaction type. Identifies a transaction as MDES or 3DS NB. This field will be empty if the transaction is neither MDES nor 3DS

MDES - 3DS

Card Issuer Data

263

Information about the card issuer

Colombia only

Virtual & Physical

Tax

264

Amount of tax charged on transaction

Colombia only

Virtual & Physical

Tax amount base

265

Value of the tax base amount used

Colombia only

Virtual & Physical

Retailer data

266

Information about the retailer where transaction took place

Colombia only

Virtual & Physical

IAC Tax amount

267

Rate levied by IAC

Colombia only

Virtual & Physical

Number of Installments

268

Number of installments to pay for the transaction

Virtual & Physical

Customer ID

269

ID value that identifies the customer

Colombia only

Virtual & Physical

Security Services Data

270

Authentication risk analysis reason codes (ARA)

Mastercard only

Virtual & Physical

On behalf of services

271

Indicates this is an 'on behalf of' transaction

Virtual & Physical

Original Merchant Description

272

The original description received from the merchant

Virtual & Physical

Installments financing type

273

Data that indicates the type of financing selected to pay installments

Brazil only

Virtual & Physical

Status

274

  • Associated with 3D Secure Out of Band authentication, providing additional status information in the Administrative Message 3DSecureAppFinalisation.
  • This field communicates status updates crucial for verifying transactions securely through a separate channel, typically a mobile app.
  • Possible values:
  • 0 - Successfully received final status
  • 1 - Timer on browser expired before response was received
  • 2 - General error
  • 3 - Transaction cancelled before response was received

Virtual & Physical

Installments grace period

275

Data indicating duration of the grace period for payment of the installment

Mexico only

Virtual & Physical

Installments type of credit

276

Data indicating the type of credit used for the installment transaction

Mexico only

Virtual & Physical

Payments Initiator

277

Represents who triggered the transaction. Potential values are "merchant", "cardholder", or an empty string/no value when cannot be determined

Mastercard only

Virtual & Physical

Payment Initiator Subtype

278

  • Some values can be either merchant initiated transactions or cardholder initiated transactions, such as Standing Order, where the first payment would typically be initiated by the cardholder. Potential values, when available:
  • "Unscheduled Credential on File"
  • "Standing Order""Subscription"
  • "Installment"
  • "Partial Shipment"
  • "Related/Delayed Charge"
  • "No Show Charge"
  • "Resubmission"
  • "Credential-on-file"

Mastercard only

Virtual & Physical

Additional amount

300

Cashbacks come as an "additional amount"

Columbia only

Second additional amount

301

There can be a maximum of two cashback amounts that can come through in a transaction

Virtual & Physical

cashback POS currency code

302

Represents the currency code of the cashback amount

Physical

cashback POS amount

303

Displays the actual cashback amount

Physical

Sender name

400

Name of the sender

Visa Direct & Money send

Sender Address

401

Street address of the person who sent the funds in the transaction

Visa Direct & Money send

Sender city

402

Name of the city of the person who sent the funds in the transaction

Visa Direct only

Visa Direct only

Sender state

403

Name of the State if the person who sent the funds in the transaction

Visa Direct only

Visa Direct only

Sender country

404

Name of the country of the person who sent the funds in the transaction

Visa Direct only

Visa Direct only

Sanction screening score

405

Data indicating the score achieved during sanction screening in the transaction

Visa Direct and Moneysend

Business application identifier

406

Code that identifies the intended use of a push payment in the transaction

Visa Direct only

Visa Direct only

Special condition indicator

408

Data indicating any special conditions for the transaction

Visa Direct only

Visa Direct only

Business tax ID

409

Data indicating the value of the business's tax ID number

Visa Direct only

Visa Direct only

Individual tax ID

410

Data indicating the value of the customer/individual's tax ID number

Visa Direct only

Visa Direct only

Source of funds

411

Data indicating where the funds come from

Visa Direct & Money send

Sender account number

412

The account number of the person who sent/paid the funds

Visa Direct & Money send

Sender Account Number Type

413

The account type of the person who sent/paid the funds

Visa Direct & Money send

MVV

414

Merchant Verification Value is used to identify merchants that participate in various programs and is unique to a merchant

Visa Direct only

Visa Direct only

Sender reference number

415

sender reference number

(Visa Direct only)

Visa Direct only

is afd transaction

416

AFD Transaction indicator for MCC 5542.1: AFD TXN, 0: NOT AFD

 Virtual & Physical (AFD only)

acquirer fee amount

417

Acquirer fee amount in transaction currency

Virtual & Physical

Address Verification Result

418

  • 0- postal/zip code and address matches
  • 1-postal/zip code matches, address does not
  • 2-Address matches, postal/zip code does not match
  • 3-Neither address nor postal/zip code match

Virtual & Physical

Postal code / ZIP code

419

Cardholder postal/ZIP code

Virtual & Physical

Street address

420

Cardholder street address only without city or area

Virtual & Physical

Sender Date of Birth

421

The Date of Birth of the person who sends the funds in the transaction.

Visa Direct only

Visa Direct only

OCT Activity check result

422

  • The activity check result of the Original Credit Transaction (OCT) when velocity checking has been performed.
  • 1 = 1-day count or amount exceeded.
  • 2 = 7-day count or amount exceeded.
  • 3 = 30-day count or amount exceeded.

Visa Direct only

Visa Direct only

Sender postal code

423

The postal code of the person who sends the funds in the transaction.

Visa Direct only

Visa Direct only

Recipient city

424

The city of the person who receives the funds in the transaction.

Visa Direct only

Visa Direct only

Recipient country

425

The country of the person who receives the funds in the transaction.

Visa Direct only

Visa Direct only

3D Secure OTP

900

Dynamic One Time Password for 3D Secure

3DS

Digitization activation

901

The password needed to activate an MDES digitization request

Tokenization

Digitization activation method type

902

Method used to send OTP to activate a token

Tokenization

Digitization activation method value

903

Code numerical value that indicates method used to send OTP to activate a token

Tokenization

Digitization activation expiry

904

Expiry of the activation

Tokenization

Digitization final tokenization decision

905

  • 1 = approve
  • 2 = approve but with additional authentication

Tokenization

Device name

906

Up tp 20 characters. This is the device name associated with the wallet provider

Tokenization

Digitized Device ID

910

The ID of the type of device used for tokenization

Tokenization

Digitized PAN expiry

911

Expiry date of the DPAN

Tokenization

Digitized FPAN Masked

912

The masked FPAN

Token Unique Reference

913

The token reference during the process

Tokenization

Digitized Token Requestor ID

915

Token Requestor ID during the process

Tokenization

Visa Digitized PAN

916

The digitized PAN for Visa

Visa only

Tokenization - VTS

Visa token type

917

Data indicating the type of token

Visa only

Tokenization - VTS

POS Transaction Status

920

  • Point-of-Service Data about the transaction status
  • 0 = Standard request
  • 1 = Deferred authorization
  • 4 = Pre-authorization request

Physical

POS Transaction Security

921

Point-of-Service Data about the security

Physical

POS Authorisation Lifecycle

922

Point-of-Service Data about the Authorization Lifecycle

Physical

Digitization event type

923

Event types include: Deleted, Deleted_from_device, Stopped, Digitized, Digitization_Exception, Replacement

Tokenization

Digitization event reason code

924

Code relating to a Digitization Exception event type

Tokenization

Supports partial auth

925

Indicates a transaction supports partial authorisation transaction

Virtual and Physical

Digitization path

929

  • GREEN
  • YELLOW
  • ORANGE
  • RED

Tokenization

Wallet recommendation

930

  • Decline
  • Approve
  • Require_additional_authentication

Tokenization

Tokenization pan source

931

  • card_on_file\
  • card_added_manually\
  • card_added_via_application\
  • existing_token_credential\
  • card_added_via_browser

Tokenization

Unique Transaction Reference

932

Unique Transaction Reference number for Mastercard MoneySend payment

Moneysend

Transaction purpose

933

Transaction purpose details

Moneysend

3D Secure OTP RefCode

934

Dynamic 4 letters reference code to be used along with 3DS OTP messages

BankServ only

3DS

Generic Key

999

Reserved for other uses

Stop Reason ID Codes

Reason IDInternal CodeNetwork response (Mastercard)Network response (Visa)Description
120084141Lost Card
220094343Stolen Card
310046262Do not honor
410165151Insufficient funds
510181414Invalid card number
610067575PIN tries exceeded
710020559Do not honor
Other10000505Do not honor