Device Integration

🚧

EMV Certification Requirement

This page is specifically intended for ISVs doing their own device integration, which requires EMV certification no matter the API environment. For more information, make sure to revisit PayConex™ and Decryptx®.

For more information and the comprehensive list of Bluefin P2PE certified devices, check out:

• P2PE Devices
• Decryptx®: Bluefin Supported PCI-Validated P2PE Devices
• Decryptx®
• Decryptx® Parser
• Point to Point Encryption
• P2PE Manager®
• Device Management
• Processing Payloads

This page can also be used for educational purposes to demonstrate how the device P2PE encrypted payloads and parameters would be included in the V4 API request from scratch.

Here, we briefly cover some of the most common transactions as simple sale transactions with the deviceProfile of PAX_A80:

• Keyed transaction with CVV
• EMV debit
• Contactless
• For the full list of CP device transactions, also refer to API References.

For more on Decryptx®, see Decryptx® Introduction.

📘

PAX_A80

We use PAX_A80 in the following examples as it is the most generic model type for PAX payment payloads.

Card Present Endpoints

📘

Note

PayConex™ Card Present endpoints are prefixed with device-* since Card Present transactions are executed directly on the device. This naming convention also aligns well with the use case of MOTO Transactions.

Again, before processing CP transactions within our PayConex™ Gateway, it is crucial for Decryptx® to extract and decrypt the sensitive P2PE data that was previously acquired and encrypted at the POS. To do this, devices use an advanced encryption method known as SRED. With that in mind, all of the examples below contain the required "card" field that is encrypted at the POS.

Request Parameters

In a nutshell, here are some essential device parameters for the V4 API with most of these used in the examples below. For the comprehensive list of CP parameters, refer to API References.

device

Device metadata for the PayConex™ Gateway and payment processor.

card

p2pe

These are all of the encrypted P2PE blocks that can be used.

masked

These are the masked values from the POS.

cvm

📘

Note

As outlined in the table above, the CVM (Cardholder Verification Method) information is included exclusively for the card issuers with the EMV standards for chip card transactions. Signatures are also used for printing receipts.
With this parameter provided, the PayConex system modifies the transaction via PATCH which then becomes available as transaction metadata via GET.

method

Getting Device Profiles

For CP transactions, it is helpful to list all the device profiles associated with your PayConex™ account. This way, you can validate the capabilities of every device profile available to you.

Point of sale profiles and entry modes are also applied in combination with device profiles.

GET /api/v4/device-profiles

*Required Scopes: pcx:device_profile:read

Here are the tables based on the GET response and the devices respective model group.

PAX

IDTECH

IDYNAMO_5

WISEPAD

INGENICO

Other

🚧

Note

In order for the PayConex™ Gateway to determine which device profile to use, it is critical that a particular device name as deviceProfile is specified to run a CP transaction, varying based on the device model. The same device profile property is also used for registering a device. See Device Management.

API Examples

Keyed Transaction with CVV

POST /api/v4/accounts/{accountId}/payments/device-sale

{
  "credentialOnFile": {
    "scheduleIndicator": "UNSCHEDULED"
  },
  "tenderType": "CREDIT",
  "entryMode": "KEYED",
  "posProfile": "ATTENDED_ON_PREM_POS",
  "deviceProfile": "PAX_A80",
  "amounts": {
    "currency": "USD",
    "total": "27.50"
  },
  "card": {
    "expiry": "1230",
    "p2pe": {
      "cvv": "BC53B84FA4B8F12C",
      "ksn": "FFFF9876540002400195",
      "pan": "B3804311123638D"
    },
    "masked": {
      "pan": ""
    }
  },
  "device": {
    "type": "A920",
    "serial": "0820617507",
    "app": "BluePOS",
    "appVersion": "1.0.0",
    "osVersion": "PayDroid 6.3",
    "capabilities": "E0F8C8"
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:device:*, pcx:payments:device:sale

EMV Debit

POST /api/v4/accounts/{accountId}/payments/device-sale

{
  "rules": {
    "allowPartial": true
  },
  "amounts": {
    "additionalFee": "0.00",
    "cashback": "2.00",
    "currency": "USD",
    "gratuity": "0.00",
    "surcharge": "0.00",
    "total": "25.00"
  },
  "card": {
    "expiry": "1230",
    "masked": {
      "pan": "444433******1111",
      "track2": ";444433******1111=**************?"
    },
    "p2pe": {
        "ksn": "FFFF9876540002400195",
        "pan": "B3804311123638D",
        "track2": "0FE17E517D242848D8B01784C38D9914D82A48B298CDEC49301256CE720ED4B73A7E32FBC9922C15"
    }
  },
  "device": {
    "app": "BluePOS",
    "appVersion": "0-22-4-dev-debug",
    "mode": "standalone",
    "osVersion": "22:5.1.1",
    "serial": "0820619992",
    "type": "A920"
  },
  "deviceProfile": "PAX_A80",
  "entryMode": "CONTACT",
  "pinBlock": {
    "ksn": "FFFF3D3D3D0005600161",
    "pin": "B2E7B2D1F0EB2E21"
  },
  "posProfile": "ATTENDED_ON_PREM_POS",
  "tenderType": "DEBIT",
  "tlv": "9F26086F520F4F3B45A7989F2701809F370430A92D3E9F3602007B950580800480009C010082021C009F3303E0F8C89F34034203009A032105245F2A0208409F02060000000030009F03060000000000009F3501225F3401015F24032212319F100706010A03A0A8009F1A0208408407A00000000310104F07A00000000310109F0607A00000000310109F0702FF009F0902008C9F1E0830383230363137359F3901059F4104000000019F530146"
}

*Required Scopes: pcx:payments:*, pcx:payments:device:*, pcx:payments:device:sale

Contactless

POST /api/v4/accounts/{accountId}/payments/device-sale

{
  "amounts": {
    "currency": "USD",
    "total": "10.02"
  },
  "entryMode": "CONTACTLESS",
  "card": {
    "expiry": "1231",
    "masked": {
      "pan": "444433******1111",
      "track2": ";444433******1111=**************?"
    },
    "p2pe": {
      "ksn": "FFFF9876540002400195",
      "pan": "B3804311123638D",
      "track2": "0FE17E517D242848D8B01784C38D9914D82A48B298CDEC49301256CE720ED4B73A7E32FBC9922C15"
    }
  },
  "device": {
    "app": "BluePOS",
    "appVersion": "0-18-1-dev-debug",
    "capabilities": "E00808",
    "mode": "standalone",
    "osVersion": "23:6.0",
    "serial": "1350024677",
    "type": "A920"
  },
  "deviceProfile": "PAX_A80",
  "posProfile": "ATTENDED_ON_PREM_POS",
  "tenderType": "CREDIT",
  "tlv": "9F26086F520F4F3B45A7989F2701809F370430A92D3E9F3602007B950580800480009C010082021C009F3303E0F8C89F34034203009A032105245F2A0208409F02060000000030009F03060000000000009F3501225F3401015F24032212319F100706010A03A0A8009F1A0208408407A00000000310104F07A00000000310109F0607A00000000310109F0702FF009F0902008C9F1E0830383230363137359F3901059F4104000000019F530146"
}

*Required Scopes: pcx:payments:*, pcx:payments:device:*, pcx:payments:device:sale