持卡人在位

持卡人在位付款 (CHP) 付款指使用销售点 (POS) 终端的交易。终端可以通过以下方式读取卡数据：

掏取 EMV 卡
通过非接触式卡进行 NFC（近场通讯）
刷磁条卡
键入卡号

Direct API 版本 40 之前的版本提供上述所有支持。

CHP 付款由终端发起，然后作为 Verify、Authorize、Capture、Pay 或 Refund 交易发送到网关。例如，由卡芯片离线授权的交易将只作为 Capture 发送，而需要发卡机构授权的交易将使用在线 Authorize 交易，然后使用 Capture 交易。

CHP 交易与很多其他网关功能交互。您可以：

将卡令牌化，
使用与您的电子商务交易相同的集成或通过 UI 退款
统一电子商务和 CHP 报告

先决条件Copied to Clipboard

Your payment service provider 和您的收单行必须为您启用持卡人在位交易。

用于 CHP 交易的通用字段Copied to Clipboard

以下 API 字段与通过网关的所有持卡人在位集成相关。

强制字段

transaction.source=CARD_PRESENT: 如果不提供此字段，将使用 your payment service provider 在收单行链接配置的默认交易来源。 [REST][NVP]

sourceOfFunds.type=CARD [REST][NVP]
order.amount [REST][NVP]
order.currency [REST][NVP]
卡号：强制提供卡号，不过提供方式取决于卡读取方式，包括键盘输入、磁条或 EMV 芯片，您可以在以下位置提供：
- 键控交易的 sourceOfFunds.provided.card.number。
- 磁条交易的 sourceOfFunds.provided.card.track1 和/或 sourceOfFunds.provided.card.track2，或
  
  标签 56 和标签 57 的 EMV 标签等效实体，这些标签分别在卡数据为磁条格式的非接触式交易的 sourceOfFunds.provided.card.emvRequest 中提供。
- 卡数据为 EMV 格式的 EMV 交易（接触式/非接触式）的 sourceOfFunds.provided.card.emvRequest 中的标签 5A。
- 卡数据为 DUKPT 加密格式的 P2PE（点对点加密）交易的 sourceOfFunds.provided.card.p2pe.payload。

终端识别码：强制提供终端识别码，不过提供方式取决于卡读取方式，包括键盘输入、磁条或 EMV 芯片，您可以在以下位置提供：
- 键控交易和磁条交易的 posTerminal.lane。
- 卡数据为 EMV 格式的 EMV 交易（接触式/非接触式）的 sourceOfFunds.provided.card.emvRequest 中的标签 9F1C。

可选字段

确保以下 POS 终端字段值根据终端生成交易的卡数据的方式正确设置。如果存在这些字段的数据，应始终提供这些数据。网关将根据需要将此数据传送到收单行。如果收单行需要一个字段，但实际不存在，那么交易将失败。

posTerminal.address
posTerminal.attended: 如果您未提供此字段，网关将默认此值为 UNKNOWN_OR_UNSPECIFIED
posTerminal.authorizationMethod
posTerminal.cardHolderActivated: 如果您未提供此字段，网关将默认此值为 NOT_CARDHOLDER_ACTIVATED
posTerminal.inputCapability: 此字段对于 EMV 交易是强制的。
posTerminal.location: 此字段对于 EMV 交易是强制的。
posTerminal.panEntryMode
posTerminal.pinEntryCapability
posTerminal.onlineReasonCode: 此字段对于所有在线交易的芯片和芯片回调交易（包括撤消）是强制的。
posTerminal.serialNumber
posTerminal.mobile.cardInputDevice: 此字段适用于能够接受点击屏幕或物理键盘来输入 PIN 的移动 POS (mPOS) 设备。软件 PIN 应仅用于没有支持 PIN 输入的硬件键盘的设备。有关 mPOS 集成的要求，请参见通过集成使用 mPOS。

POS 终端 API 参考 [REST][NVP]

order.gratuityAmount: 如果付款含有小费金额，请提供此字段。
[REST][NVP]
order.cashbackAmount: 如果付款含有返现金额，请提供此字段。
[REST][NVP]
order.cashAdvance: 如果付款含有预付现金金额，请提供此字段。
[REST][NVP]

处理磁条交易Copied to Clipboard

如果卡轨数据从卡磁条读取，

在 sourceOfFunds.provided.card.track1 字段中提供卡轨 1 数据，或在 sourceOfFunds.provided.card.track2 字段中提供卡轨 2 数据。如果卡轨 1 和卡轨 2 在终端均可用，那么在交易请求中全部提供。
提供强制字段。
提供可选字段（如果需要）。

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

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

卡轨数据必须包含正确的开始和结束标记字符，且后跟纵向冗余检验 (LRC) 字符。不支持卡轨 3 数据。

请求示例

这里是使用磁条数据的在线授权交易的示例。

URL	https://cnp.merchantlink.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
HTTP 方法	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"
}

处理键控交易Copied to Clipboard

如果在终端键盘手动输入卡号，

在 sourceOfFunds.provided.card.number 请求字段中提供键入的卡号。
提供强制字段。
提供可选字段（如果需要）。

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

请求示例

这里是使用手动键入卡号的在线授权交易的示例。

URL	https://cnp.merchantlink.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid}
HTTP 方法	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"
}

处理点对点加密 (P2PE) 交易Copied to Clipboard

P2PE 是支付卡行业标准委员会制定的标准。使用 P2PE，敏感的卡数据会在读取卡数据后在终端立即加密。由于您不必处理敏感数据，因此这会最大化持卡人在位交易的安全性，并会减少您的 PCI 合规义务。

Payment Gateway 在 Direct API 版本 40 及更高版本中使用 DUKPT (Derived Unique Key Per Transaction) 支持 P2PE（仅面向欧盟地区的 Verifone）。

如何处理 P2PE 交易：

在以下字段中提供来自终端的 DUKPT P2PE 数据：
- sourceOfFunds.provided.card.p2pe.keySerialNumber: 您必须提供终端提供的 DUKPT 密钥序列号。
- sourceOfFunds.provided.card.p2pe.payload: 如果提供此字段，则不强制提供 sourceOfFunds.provided.card.number。网关将从提供的支付数据中提取所有相关的卡详细信息。
- posTerminal.serialNumber:
- sourceOfFunds.provided.card.p2pe.cardBin
- sourceOfFunds.provided.card.p2pe.encryptionState: 如果您未提供此字段，网关将默认此值为 VALID
- sourceOfFunds.provided.card.p2pe.initializationVector: 如果终端未使用初始化向量来进行加密，可以忽略此字段。
提供强制字段。
提供可选字段（如果需要）。

P2PE API 参考 [REST][NVP]

下表汇总了 sourceOfFunds.provided.card.p2pe 参数组的字段约束。

如果字段			那么网关...
sourceOfFunds.provided.card.p2pe. initializationVector	sourceOfFunds.provided.card.p2pe. keySerialNumber	sourceOfFunds.provided.card.p2pe. payload	那么网关...
已提供	已提供	未提供	拒绝交易请求。
已提供	已在解密前或解密后提供，但使用纯文本	已提供	返回错误并生成安全日志条目。

交易响应

sourceOfFunds.provided.card.encryption 字段在交易响应中返回 DUKPT（Direct API 43 及更高版本）以指示卡数据已加密。 sourceOfFunds.provided.card.p2pe 参数组中的字段不在响应中返回。

集成以使用在线 PINCopied to Clipboard

持卡人输入的在线 PIN 在 PIN 输入设备内在源头加密。 Payment Gateway 在 Direct API 45 及更高版本中支持 DUKPT (Derived Unique Key Per Transaction) 加密的在线 PIN 数据。

在以下字段中提供来自终端的 DUKPT 加密的 PIN 数据：
- sourceOfFunds.provided.card.pin.payload
- sourceOfFunds.provided.card.pin.keySerialNumber
- posTerminal.pinLengthCapability
- sourceOfFunds.provided.card.pin.encryptionState
在线 PIN API 参考 [REST][NVP]
提供强制字段。
提供可选字段（如果需要）。

通过集成使用 mPOSCopied to Clipboard

从 API v56 开始，网关支持在移动 POS (mPOS) 设备上接受付款。要启用此功能，在 Verify、Authorize、Capture、Pay 或 Refund 交易中提供以下内容：

posTerminal.cardholderActivated=MPOS_ACCEPTANCE_DEVICE
在 posTerminal.mobile.cardInputDevice

中提供读卡器的值
- BUILT_IN: 只有内置非接触式读卡器的非专门设计的手机或平板电脑。在这种情况下，posTerminal.pinEntryCapability 必须设置为 SOFTWARE_ONLINE_PIN_ONLY，否则网关将拒绝交易。
- INTEGRATED_DONGLE: 带有集成读卡器的专用移动终端。在这种情况下，posTerminal.pinEntryCapability 必须设置为 PIN_SUPPORTED 或 OFFLINE_PIN_ONLY，否则网关将拒绝交易。
- SEPARATE_DONGLE: 带有单独读卡器的非专门设计的设备或专用移动终端。在这种情况下，posTerminal.pinEntryCapability 必须设置为 PIN_SUPPORTED 或 OFFLINE_PIN_ONLY，否则网关将拒绝交易。
mPOS API 参考 [REST][NVP]
提供强制字段。
提供可选字段（如果需要）。

交易响应

如果付款人输入了无效的 PIN、超过了允许的 PIN 输入尝试次数，或在需要 PIN 来完成交易时跳过了 PIN 输入，PIN 身份验证可能失败。

在因 PIN 身份验证错误而导致授权失败的情况下，网关会返回特定的授权响应代码。您可以在下一次交易中重新使用同一个订单 ID。

测试持卡人在位集成Copied to Clipboard

您可以使用收单行专有的测试卡。

持卡人在位

先决条件 Copied to Clipboard

用于 CHP 交易的通用字段 Copied to Clipboard

处理磁条交易 Copied to Clipboard

处理键控交易 Copied to Clipboard

处理点对点加密 (P2PE) 交易 Copied to Clipboard

交易响应

集成以使用在线 PIN Copied to Clipboard

通过集成使用 mPOS Copied to Clipboard

交易响应

测试持卡人在位集成 Copied to Clipboard

On This Page

先决条件Copied to Clipboard

用于 CHP 交易的通用字段Copied to Clipboard

处理磁条交易Copied to Clipboard

处理键控交易Copied to Clipboard

处理点对点加密 (P2PE) 交易Copied to Clipboard

集成以使用在线 PINCopied to Clipboard

通过集成使用 mPOSCopied to Clipboard

测试持卡人在位集成Copied to Clipboard