Cardholder Present Payments

• 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:
  
  
  • sourceOfFunds.provided.card.number for keyed transactions.
  • sourceOfFunds.provided.card.track1 and/or sourceOfFunds.provided.card.track2 for magnetic stripe transactions, or
    
    their EMV tag equivalents, tag 56 and tag 57, respectively provided in sourceOfFunds.provided.card.emvRequest for contactless transactions where card data is in magnetic stripe format.
  • Tag 5A in sourceOfFunds.provided.card.emvRequest for EMV transactions (contact/contactless) where card data is in EMV format.
  • sourceOfFunds.provided.card.p2pe.payload for 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.lane for keyed transactions and magnetic stripe transactions.
  • Tag 9F1C in sourceOfFunds.provided.card.emvRequest for 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.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
• posTerminal.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.

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]

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

{
  "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"
}

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

{
  "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"
}