Cardholder Present
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.
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]- 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:
sourceOfFunds.provided.card.numberfor keyed transactions.sourceOfFunds.provided.card.track1and/orsourceOfFunds.provided.card.track2for magnetic stripe transactions, or
their EMV tag equivalents, tag 56 and tag 57, respectively provided insourceOfFunds.provided.card.emvRequestfor contactless transactions where card data is in magnetic stripe format.- Tag 5A in
sourceOfFunds.provided.card.emvRequestfor EMV transactions (contact/contactless) where card data is in EMV format. sourceOfFunds.provided.card.p2pe.payloadfor P2PE (Point-to-Point Encryption) transactions where card data is in DUKPT encrypted format.
- 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:
posTerminal.lanefor keyed transactions and magnetic stripe transactions.- Tag 9F1C in
sourceOfFunds.provided.card.emvRequestfor EMV transactions (contact/contactless) where card data is in EMV format.
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.addressposTerminal.attended: If you do not provide this field, the gateway defaults the value toUNKNOWN_OR_UNSPECIFIEDposTerminal.authorizationMethodposTerminal.cardHolderActivated: If you do not provide this field, the gateway defaults the value toNOT_CARDHOLDER_ACTIVATEDposTerminal.inputCapability: This field is mandatory for EMV transactions.posTerminal.location: This field is mandatory for EMV transactions.posTerminal.panEntryModeposTerminal.pinEntryCapabilityposTerminal.onlineReasonCode: This field is mandatory for chip and chip fallback transactions (including reversals) for all online transactions.posTerminal.serialNumberposTerminal.mobile.cardInputDevice: This field is applicable to mobile POS (mPOS) devices where the device is capable of accepting tap on screen or physical keypad for entering the PIN. Software PIN should only be used for devices that do not have a hardware keypad to support PIN Entry. For mPOS integration requirements, see Integrating to use mPOS.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]
POS Terminal API Reference [REST][NVP]
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.track1or Track 2 data insourceOfFunds.provided.card.track2fields. 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]
Here's an example of an online Authorization transaction using magnetic stripe data.
| URL | https://na.gateway.spring.citi.com/api/rest/version/72/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": "39",
"month": "01"
},
"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"
}
}
{
"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": "1",
"year": "39"
},
"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,
- Provide the keyed card number in
sourceOfFunds.provided.card.numberrequest field. - Provide the mandatory fields.
- Provide the optional fields if needed.
sourceOfFunds.provided.card.number[REST][NVP]
Here's an example of an online Authorization transaction using a manually keyed card number.
| URL | https://na.gateway.spring.citi.com/api/rest/version/72/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": "39",
"month": "01"
}
}
}
},
"order": {
"amount": "100.00",
"currency": "EUR"
},
"transaction": {
"source": "CARD_PRESENT",
"frequency": "SINGLE"
}
}
{
"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": "1",
"year": "39"
},
"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.
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.numberis not mandatory. The gateway will extract all relevant card details from the payload data provided.posTerminal.serialNumber:sourceOfFunds.provided.card.p2pe.cardBinsourceOfFunds.provided.card.p2pe.encryptionState: If you do not provide this field, the gateway defaults the value toVALIDsourceOfFunds.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 Spring by Citi 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.payloadsourceOfFunds.provided.card.pin.keySerialNumberposTerminal.pinLengthCapabilitysourceOfFunds.provided.card.pin.encryptionState
- Provide the mandatory fields.
- Provide the optional fields if needed.
Integrating to use mPOS
The gateway supports accepting payments on mobile POS (mPOS) devices from API v56 onwards. To enable the functionality, provide the following in the Verify, Authorize, Capture, Pay, or Refund transaction:
posTerminal.cardholderActivated=MPOS_ACCEPTANCE_DEVICE- Provide the value of the card reader in the
posTerminal.mobile.cardInputDevice
BUILT_IN: Off-the-shelf mobile phone or tablet with only a built-in contactless reader. In this case, posTerminal.pinEntryCapability must be set to SOFTWARE_ONLINE_PIN_ONLY else the gateway rejects the transaction.INTEGRATED_DONGLE: Dedicated mobile terminal with an integrated card reader. In this case, posTerminal.pinEntryCapability must be set to PIN_SUPPORTED or OFFLINE_PIN_ONLY else the gateway rejects the transaction.SEPARATE_DONGLE: Off-the shelf device or dedicated mobile terminal, with a separate card reader. In this case, posTerminal.pinEntryCapability must be set to PIN_SUPPORTED or OFFLINE_PIN_ONLY else the gateway rejects the transaction.
- 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.