Cardholder Present Payments

Cardholder Present (CHP) payments refer to transactions using a Point of Sale (POS) terminal. The terminal may read card data by:

  • dipping an EMV card
  • NFC (Near Field Communication) from a contactless card
  • swiping a magnetic stripe card
  • keying the card number

Support for all of the above is available from API version 40 onwards.

A CHP payment is initiated by a terminal and sent to the gateway as a Verify, Authorize, Capture, Pay, or Refund transaction. For example, transactions that are authorized offline by the chip on the card will be sent as a Capture only, whereas transactions requiring authorization by the issuer will use an online Authorize transaction, and then a Capture transaction.

CHP transactions interwork with many of the other gateway features. You can:

  • tokenize the card,
  • refund using the same integration as your e-commerce transactions, or via the UI
  • unify e-commerce and CHP reporting

Prerequisites

Your payment service provider and your acquirer must enable you for cardholder present transactions.

Common Fields Used for CHP Transactions

The following API fields are relevant to all cardholder present integrations via the gateway.

Mandatory Fields
  • transaction.source=CARD_PRESENT: If you do not provide this field, the default transaction source configured on your acquirer link by your payment service provider will be used. [REST][NVP]


  • sourceOfFunds.type=CARD [REST][NVP]

  • order.amount [REST][NVP]

  • order.currency [REST][NVP]

  • card number: It is mandatory to provide the card number but depending on the card read manner, via key entry, magnetic stripe, or EMV chip, you may provide it in:


  • terminal identifier: It is mandatory to provide the terminal identifier but depending on the card read manner, via key entry, magnetic stripe, or EMV chip, you may provide it in:

Optional Fields

Ensure that values for the following POS terminal fields are set correctly based on how the terminal generated the card data for the transaction. If data for these fields is available, always provide it. The gateway will pass the data as required to the acquirer. If the acquirer requires a field and if it's not present, then the transaction will fail.

  • posTerminal.address
  • posTerminal.attended: If you do not provide this field, the gateway defaults the value to UNKNOWN_OR_UNSPECIFIED
  • posTerminal.authorizationMethod
  • posTerminal.cardHolderActivated: If you do not provide this field, the gateway defaults the value to NOT_CARDHOLDER_ACTIVATED
  • posTerminal.inputCapability: This field is mandatory for EMV transactions.
  • posTerminal.location: This field is mandatory for EMV transactions.
  • posTerminal.panEntryMode
  • posTerminal.pinEntryCapability
  • posTerminal.onlineReasonCode: This field is mandatory for chip and chip fallback transactions (including reversals) for all online transactions.
  • posTerminal.serialNumber
  • POS Terminal API Reference [REST][NVP]

  • order.gratuityAmount: Provide this field if the payment includes a gratuity amount.
    [REST][NVP]

  • order.cashbackAmount: Provide this field if the payment includes a cashback amount.
    [REST][NVP]

  • order.cashAdvance: Provide this field if the payment includes a cash advance amount.
    [REST][NVP]

Process an EMV Transaction

If card data was read from a card's chip (EMV cards only),

  • Request the terminal for these EMV tags (tags supported by the gateway).
  • Provide the returned tags in the sourceOfFunds.provided.card.emvRequest field as a JSON object in REST protocol, or as a collection of fields in NVP protocol (it's okay if your terminal does not supply all the supported EMV tags).
    EMV tag values must be formatted exactly as returned by the terminal — binary values will be represented in hex format.
  • Provide the mandatory fields.
  • Provide the optional fields if needed.

sourceOfFunds.provided.card.emvRequest [REST][NVP]

Some of the supported EMV tags correspond to core payment concepts, such as primary account number. These concepts also appear as API request fields, such as sourceOfFunds.provided.card.number. The API Reference documentation for these corresponding API request fields shows their linkage in the description. For example, the description for sourceOfFunds.provided.card.number contains the text "This field corresponds to EMV tag 5A".

If you provide data as an EMV tag, then you need not provide the same as an API request field. The gateway populates the corresponding API request fields with the values provided in the EMV tags, where they exist, and uses these values across all internal processing, acquirer messaging, and transaction responses. For example, if you send sourceOfFunds.provided.card.emvRequest.9F1C with value ‘Lane_03’, then posTerminal.lane with value ‘Lane_03’ is sent to the acquirer and returned in the transaction response.

You can provide EMV tags in place of API request fields.

If required, you can choose to provide both EMV tags and the corresponding API request fields in the transaction request. See Advanced Usage: Transaction Data in Both EMV Tags and API Request Fields.

Example Request

Here's an example EMV request in REST for a Standalone Capture transaction where the authorization was performed offline at the terminal.

URL https://credimax.gateway.mastercard.com/api/rest/version/56/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
HTTP Method PUT
{
    "apiOperation": "CAPTURE",
    "transaction": {
        "currency": "EUR",
        "amount": "10.99",
        "source": "CARD_PRESENT"
    },
    "sourceOfFunds": {
        "type": "CARD",
        "provided": {
            "card": {
                "number": "5457210089020012",
                "expiry": {
                    "month": "5",
                    "year": "21"
                },
                "emvRequest": {
                    "82": "0000",
                    "95": "0000000000",
                    "9F02": "000000001099",
                    "9A": "161021",
                    "5F2A": "840",
                    "9F1A": "840",
                    "9F10": "06011103A000000A0100000000000BB0ABAD",
                    "9F34": "1E0300",
                    "9F36": "0002",
                    "9C": "00",
                    "9F26": "D1F722D47FCA8273",
                    "9F27": "40",
                    "9F37": "2A4E1690",
                    "9F33": "E0B8C8"
                }
            }
        }
    },
    "posTerminal": {
        "inputCapability": "CONTACTLESS_CHIP",
        "panEntryMode": "CHIP",
        "pinEntryCapability": "PIN_SUPPORTED",
        "location": "MERCHANT_TERMINAL_ON_PREMISES",
        "lane": "Lane_03",
        "attended": "ATTENDED",
		"serialNumber":"123456789",
		"onlineReasonCode":"FORCED_BY_MERCHANT",
		"cardPresenceCapability":"CARD_PRESENT",
		"authorizationMethod":"OFFLINE",
		"address":
		{
			"country":"IRL",
			"city":"Dublin"
		}
    }
}
Example Response
{
  "gatewayEntryPoint": "WEB_SERVICES_API",
  "merchant": "TESTSMOKE-RETAIL",
  "order": {
    "amount": 10.99,
    "creationTime": "2017-06-06T09:42:54.280Z",
    "currency": "EUR",
    "id": "sa-dfc1b030-4520-48ec-a7e0-889999d7e4ab",
    "status": "CAPTURED",
    "totalAuthorizedAmount": 10.99,
    "totalCapturedAmount": 10.99,
    "totalRefundedAmount": 0
  },
  "posTerminal": {
    "address": {
      "city": "Dublin",
      "country": "IRL"
    },
    "attended": "ATTENDED",
    "authorizationMethod": "OFFLINE",
    "cardPresenceCapability": "CARD_PRESENT",
    "cardholderActivated": "NOT_CARDHOLDER_ACTIVATED",
    "inputCapability": "CONTACTLESS_CHIP",
    "lane": "Lane_03",
    "location": "MERCHANT_TERMINAL_ON_PREMISES",
    "onlineReasonCode": "FORCED_BY_MERCHANT",
    "panEntryMode": "CHIP",
    "pinEntryCapability": "PIN_SUPPORTED",
    "serialNumber": "123456789"
  },
  "response": {
    "gatewayCode": "APPROVED"
  },
  "result": "SUCCESS",
  "sourceOfFunds": {
    "provided": {
      "card": {
        "brand": "MASTERCARD",
        "emvRequest": {
          "82": "0000",
          "95": "0000000000",
          "5F2A": "840",
          "9A": "161021",
          "9C": "00",
          "9F02": "000000001099",
          "9F10": "06011103A000000A0100000000000BB0ABAD",
          "9F1A": "840",
          "9F26": "D1F722D47FCA8273",
          "9F27": "40",
          "9F33": "E0B8C8",
          "9F34": "1E0300",
          "9F36": "0002",
          "9F37": "2A4E1690"
        },
        "emvResponse": {
          "4D3E": "456",
          "5A2F": "123"
        },
        "expiry": {
          "month": "5",
          "year": "21"
        },
        "fundingMethod": "DEBIT",
        "issuer": "CAPITAL ONE BANK (CANADA BRANCH)",
        "number": "545721xxxxxx0012",
        "scheme": "MASTERCARD"
      }
    },
    "type": "CARD"
  },
  "timeOfRecord": "2017-06-06T09:42:54.280Z",
  "transaction": {
    "acquirer": {
      "batch": 1,
      "id": "FOOBANK",
      "merchantId": "11223344"
    },
    "amount": 10.99,
    "currency": "EUR",
    "frequency": "SINGLE",
    "id": "1",
    "receipt": "1706063974",
    "source": "CARD_PRESENT",
    "terminal": "0001",
    "type": "CAPTURE"
  },
  "version": "43"
}
Supported EMV Tags

Here's a list of EMV tags supported by the gateway. If any of these are returned by the terminal, include it in sourceOfFunds.provided.card.emvRequest field.

The gateway only accepts EMV tags on the supported EMV tags list — requests that include any other tags are rejected.
EMV Tag
Name
56 Track 1
57 Track 2 Equivalent Data
82 Application Interchange Profile (AIP)
84 Dedicated File Name
87 Application Priority Indicator
95 Terminal Verification Result (TVR)
4F Application identifier (AID) Name
5A Application Primary Account Number (PAN)
9A Transaction Date
9B Transaction Status Information
9C Transaction Type
5F2A Transaction Currency Code
5F24 Application Expiration Date
5F25 Application Effective Date
5F28 Issuer Country Code
5F34 Application Primary Account Number (PAN) Sequence Number
9F02 Amount Authorized
9F03 Cashback Amount
9F06 Application Identifier (AID) - Terminal
9F07 Application Usage Control
9F08 Application Version Number - ICC
9F09 Application Version Number - Terminal
9F10 Issuer Application Data (IAD)
9F0D Issuer Action Code - Default
9F0E Issue Action Code - Denial
9F0F Issue Action Code - Online
9F1A Terminal Country Code
9F1C Terminal Identification
9F1E Interface Device (IFD) Serial Number
9F5A EMV (Kernel 3) : Application Program Identifier (Program ID)
EMV (Kernel 4) : Membership Product Identifier
9F5B EMV (Kernel 3) : Issuer Script Results
EMV (Kernel 2) : DSDOL
EMV (Kernel 4) : Product Membership Number
9F6E Form Factor Indicator
9F7C Customer Exclusive Data (CED)
9F21 Transaction Time
9F26 Application Cryptogram (AC)
9F27 Cryptogram Information Data (CID)
9F33 Terminal Capabilities
9F34 Cardholder Verification Method (CVM) Results
9F35 Terminal Type
9F36 Application Transaction Counter
9F37 Unpredictable Number
9F39 Point-of-Service (POS) Entry Mode
9F40 Additional Terminal Capabilities
9F41 Transaction Sequence Counter
9F49 Dynamic Data Authentication Data Object List (DDOL)
9F53 Transaction Category Code
9F66 EMV (Kernel 2) : PUNATC(Track2)
EMV (Kernel 3) : Terminal Transaction Qualifiers (TTQ)
Advanced Usage: Transaction Data in Both EMV Tags and API Request Fields

If you provide both EMV tags and the corresponding API request fields in the transaction request, the gateway uses the value provided in the corresponding API request field. For example, if you send sourceOfFunds.provided.card.emvRequest.9F1C with value ‘Lane_03’ and posTerminal.lane with value ‘Lane_04’, then posTerminal.lane with value ‘Lane_04’ is sent to the acquirer and returned in the transaction response. This may be useful if you want to override the EMV tags and control values on a per-field basis. Please note that such a usage is rare and hence must be considered only if your integration requires it.

Supported EMV Tags and the Corresponding API Request Fields

This table lists EMV tags where the gateway populates the corresponding API request fields with the values provided in the EMV tags.

EMV Tag
EMV Tag Name
Corresponding API Request Field
9F1A Terminal Country Code posTerminal.address.country
9F35 Terminal Type posTerminal.attended
posTerminal.cardholderActivated
9F33 Terminal Capabilities posTerminal.inputCapability
posTerminal.pinEntryCapability
9F1C Terminal Identification posTerminal.lane
9F1E Interface Device Serial Number posTerminal.serialNumber
9F03 Cashback Amount order.cashbackAmount
9C Cash Advance order.cashAdvance
5F24 Application Expiration Date sourceOfFunds.provided.card.expiry.year
sourceOfFunds.provided.card.expiry.month
5A Application Primary Account Number (PAN) sourceOfFunds.provided.card.number
5F34 PAN Sequence Number sourceOfFunds.provided.card.sequenceNumber
56 Track 1 sourceOfFunds.provided.card.track1
57 Track 2 Equivalent Data sourceOfFunds.provided.card.track2
EMV Transaction Response

The gateway returns sourceOfFunds.provided.card.emvResponse field in the Retrieve Order and Retrieve Transaction response. This field contains data generated by the issuer, which the card/device can use for verification to complete or decline the transaction. It may also contain additional EMV tags from the issuer including tags echoed from the request.

The table below shows some EMV tags that may be returned in an online Authorization response.

EMV Tag Name
8A Authorization Response Code
89 Authorization Code
91 Issuer Authentication Data
71 Issuer Script Template 1
72 Issuer Script Template 2

The sourceOfFunds.provided.card.emvRequest field provided in the request is echoed back in the response where EMV tags identified as PCI sensitive are excluded.

Voiding an EMV Transaction

Your acquirer may require additional EMV data elements to be included when voiding an EMV transaction. For example, EMV tag DF01 (Issuer Script Results) may be required. Please contact your acquirer for specific requirements.

Process a Magnetic Stripe Transaction

If card track data was read from the card's magnetic stripe,

  • Provide Track 1 data in sourceOfFunds.provided.card.track1 or Track 2 data in sourceOfFunds.provided.card.track2 fields. If both Track 1 and Track 2 are available from the terminal, then provide both in the transaction request.
  • Provide the mandatory fields.
  • Provide the optional fields if needed.

sourceOfFunds.provided.card.track1 [REST][NVP]

sourceOfFunds.provided.card.track2 [REST][NVP]

The card track data must contain the correct start and end sentinel characters and trailing longitudinal redundancy check (LRC) character. Card track 3 data is not supported.
Example Request

Here's an example of an online Authorization transaction using magnetic stripe data.

URL https://credimax.gateway.mastercard.com/api/rest/version/56/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
HTTP Method PUT
{
  "apiOperation": "AUTHORIZE",
  "order": {
    "amount": 80,
    "currency": "AUD"
  },
  "transaction": {
    "source": "CARD_PRESENT",
    "frequency": "SINGLE"
  },
  "sourceOfFunds": {
    "type": "CARD",
    "provided": {
      "card": {
        "number": "5457210089020012",
        "sequenceNumber": "015",
        "expiry": {
          "year": "21",
          "month": "05"
        },
        "track2": ";5123456789012346=17051019681143384001?",
        "track1": "%B5123456789012346^MR JOHN R SMITH           ^17051019681143300001  840      ?;"
      }
    }
  },
  "posTerminal": {
    "lane": "AdamLane",
    "panEntryMode": "SWIPE",
    "pinEntryCapability": "PIN_NOT_SUPPORTED",
    "attended": "UNATTENDED",
    "cardholderActivated": "SELF_SERVICE_TERMINAL",
    "inputCapability": "MAGNETIC_STRIPE",
    "location": "MERCHANT_TERMINAL_OFF_PREMISES"
   }
}
Example Response
{
    "authorizationResponse": {
        "posData": "1605S0100130",
        "transactionIdentifier": "AmexTidTest"
    },
    "gatewayEntryPoint": "WEB_SERVICES_API",
    "merchant": "TESTSMOKE-RETAIL",
    "order": {
        "amount": 80,
        "creationTime": "2017-05-31T07:49:46.351Z",
        "currency": "AUD",
        "id": "sa-e229682a-2163-47cf-b080-fb60dd148192",
        "status": "AUTHORIZED",
        "totalAuthorizedAmount": 80,
        "totalCapturedAmount": 0,
        "totalRefundedAmount": 0
    },
    "posTerminal": {
        "attended": "UNATTENDED",
        "cardholderActivated": "SELF_SERVICE_TERMINAL",
        "inputCapability": "MAGNETIC_STRIPE",
        "lane": "AdamLane",
        "location": "MERCHANT_TERMINAL_OFF_PREMISES",
        "panEntryMode": "SWIPE",
        "pinEntryCapability": "PIN_NOT_SUPPORTED"
    },
    "response": {
        "acquirerCode": "00",
        "gatewayCode": "APPROVED"
    },
    "result": "SUCCESS",
    "sourceOfFunds": {
        "provided": {
            "card": {
                "brand": "MASTERCARD",
                "expiry": {
                    "month": "5",
                    "year": "21"
                },
                "fundingMethod": "DEBIT",
                "issuer": "CAPITAL ONE BANK (CANADA BRANCH)",
                "number": "545721xxxxxx0012",
                "scheme": "MASTERCARD",
                "sequenceNumber": "015",
                "trackDataProvided": true
            }
        },
        "type": "CARD"
    },
    "timeOfRecord": "2017-05-31T07:49:46.351Z",
    "transaction": {
        "acquirer": {
            "batch": 1,
            "id": "SYSTEST_ACQ1",
            "merchantId": "12345678"
        },
        "amount": 80,
        "authorizationCode": "000001",
        "currency": "AUD",
        "frequency": "SINGLE",
        "id": "1",
        "receipt": "1705313",
        "source": "CARD_PRESENT",
        "terminal": "0006",
        "type": "AUTHORIZATION"
    },
    "version": "43"
}

Process a Keyed Transaction

If the card number was manually entered on your terminal's keypad,

sourceOfFunds.provided.card.number[REST][NVP]

Example Request

Here's an example of an online Authorization transaction using a manually keyed card number.

URL https://credimax.gateway.mastercard.com/api/rest/version/56/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
HTTP Method PUT
{
  "posTerminal": {
    "serialNumber": "13130PP800781435",
    "cardholderActivated": "NOT_CARDHOLDER_ACTIVATED",
    "lane": "S2_Lane",
    "panEntryMode": "KEYED",
    "pinEntryCapability": "UNKNOWN",
    "attended": "ATTENDED",
    "inputCapability": "KEY_ENTRY",
    "location": "MERCHANT_TERMINAL_ON_PREMISES"
  },
  "apiOperation": "AUTHORIZE",
  "sourceOfFunds": {
    "type": "CARD",
    "provided": {
      "card": {
        "number": "5457210089020012",
        "sequenceNumber": "000",
        "expiry": {
          "year": "21",
          "month": "05"
        }
      }
    }
  },
  "order": {
    "amount": "100.00",
    "currency": "EUR"
  }, 
    "transaction": {
    "source": "CARD_PRESENT",
    "frequency": "SINGLE"
  }
}
Example Response
{
  "gatewayEntryPoint": "WEB_SERVICES_API",
  "merchant": "TESTSMOKE-RETAIL",
  "order": {
    "amount": 100,
    "creationTime": "2017-05-31T08:59:47.194Z",
    "currency": "EUR",
    "id": "sa-529e784a-e11d-474d-8012-c0790531bb0f",
    "status": "AUTHORIZED",
    "totalAuthorizedAmount": 100,
    "totalCapturedAmount": 0,
    "totalRefundedAmount": 0
  },
  "posTerminal": {
    "attended": "ATTENDED",
    "cardholderActivated": "NOT_CARDHOLDER_ACTIVATED",
    "inputCapability": "KEY_ENTRY",
    "lane": "S2_Lane",
    "location": "MERCHANT_TERMINAL_ON_PREMISES",
    "panEntryMode": "KEYED",
    "pinEntryCapability": "UNKNOWN",
    "serialNumber": "13130PP800781435"
  },
  "response": {
    "gatewayCode": "APPROVED"
  },
  "result": "SUCCESS",
  "sourceOfFunds": {
    "provided": {
      "card": {
        "brand": "MASTERCARD",
        "expiry": {
          "month": "5",
          "year": "21"
        },
        "fundingMethod": "DEBIT",
        "issuer": "CAPITAL ONE BANK (CANADA BRANCH)",
        "number": "545721xxxxxx0012",
        "scheme": "MASTERCARD",
        "sequenceNumber": "000"
      }
    },
    "type": "CARD"
  },
  "timeOfRecord": "2017-05-31T08:59:47.194Z",
  "transaction": {
    "acquirer": {
      "batch": 1,
      "id": "FOOBANK",
      "merchantId": "11223344"
    },
    "amount": 100,
    "authorizationCode": "471223",
    "currency": "EUR",
    "frequency": "SINGLE",
    "id": "1",
    "receipt": "170531475",
    "source": "CARD_PRESENT",
    "terminal": "0001",
    "type": "AUTHORIZATION"
  },
  "version": "43"
}

Process a Point-to-Point Encryption (P2PE) Transaction

P2PE is a standard established by the PCI Security Standards Council. With P2PE, sensitive card data is encrypted on the terminal immediately after the card data is read. This maximizes the security of cardholder present transactions and reduces your PCI compliance obligations as you don't have to handle sensitive data.

The Mastercard Payment Gateway supports P2PE using DUKPT (Derived Unique Key Per Transaction) from API version 40 onwards, only for Verifone in the EU region.

To process a P2PE transaction:

  • Provide the DUKPT P2PE data from the terminal in the following fields:
    • sourceOfFunds.provided.card.p2pe.keySerialNumber: You must provide the DUKPT key serial number supplied by the terminal.
    • sourceOfFunds.provided.card.p2pe.payload: If this field is provided, sourceOfFunds.provided.card.number is not mandatory. The gateway will extract all relevant card details from the payload data provided.
    • posTerminal.serialNumber:
    • sourceOfFunds.provided.card.p2pe.cardBin
    • sourceOfFunds.provided.card.p2pe.encryptionState: If you do not provide this field, the gateway defaults the value to VALID
    • sourceOfFunds.provided.card.p2pe.initializationVector: This field can be omitted if the terminal is not using an initialization vector to seed encryption.
  • Provide the mandatory fields.
  • Provide the optional fields if needed.

P2PE API Reference [REST][NVP]

The table below summarizes the field constraints for the sourceOfFunds.provided.card.p2pe parameter group.

If field then the gateway...
sourceOfFunds.provided.card.p2pe. initializationVector
sourceOfFunds.provided.card.p2pe. keySerialNumber
sourceOfFunds.provided.card.p2pe. payload
is provided is provided not provided rejects the transaction request.
is provided is provided but in plain text before or after decryption is provided returns an error and a security log entry is generated.

Transaction Response

The sourceOfFunds.provided.card.encryption field returns DUKPT (from API 43 onwards) in the transaction response to indicate that the card data was encrypted. The fields in the sourceOfFunds.provided.card.p2pe parameter group are not returned in the response.

Integrating to use Online PIN

The online PIN entered by the cardholder is encrypted at source, within the PIN entry device. The Mastercard Payment Gateway supports DUKPT (Derived Unique Key Per Transaction) encrypted online PIN data from API 45 onwards.

  • Provide the DUKPT encrypted PIN data from the terminal in the following fields:
    • sourceOfFunds.provided.card.pin.payload
    • sourceOfFunds.provided.card.pin.keySerialNumber
    • posTerminal.pinLengthCapability
    • sourceOfFunds.provided.card.pin.encryptionState

    Online PIN API Reference [REST][NVP]

  • Provide the mandatory fields.
  • Provide the optional fields if needed.

Transaction Response

The PIN authentication may fail if the payer enters an invalid PIN, exceeds the allowed PIN entry attempts, or skips PIN entry when PIN is required to complete the transaction.

In these scenarios where the authorisation fails due to a PIN authentication error, the gateway will return specific authorisation response codes. You can reuse the same order ID on the next transaction.

Test Cardholder Present Integration

You can test your integration using test cards specific to your acquirer.

Copyright © 2020 Mastercard