- 集成指南
- 支持的功能（付款方式）
- 持卡人在位付款
持卡人在位
持卡人在位付款 (CHP) 付款指使用销售点 (POS) 终端的交易。 终端可以通过以下方式读取卡数据：
- 掏取 EMV 卡
- 通过非接触式卡进行 NFC（近场通讯）
- 刷磁条卡
- 键入卡号
webServices Integration 版本 40 之前的版本提供上述所有支持。
CHP 付款由终端发起，然后作为 Verify、Authorize、Capture、Pay 或 Refund 交易发送到网关。 例如，由卡芯片离线授权的交易将只作为 Capture 发送，而需要发卡机构授权的交易将使用在线 Authorize 交易，然后使用 Capture 交易。
CHP 交易与很多其他网关功能交互。 您可以：
- 将卡令牌化，
- 使用与您的电子商务交易相同的集成或通过 UI 退款
- 统一电子商务和 CHP 报告
先决条件
Your payment service provider 和您的收单行必须为您启用持卡人在位交易。
用于 CHP 交易的通用字段
以下 API 字段与通过网关的所有持卡人在位集成相关。
强制字段
transaction.source=CARD_PRESENT: 如果不提供此字段，将使用 your payment service provider 在收单行链接配置的默认交易来源。 [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.addressposTerminal.attended: 如果您未提供此字段，网关将默认此值为UNKNOWN_OR_UNSPECIFIEDposTerminal.authorizationMethodposTerminal.cardHolderActivated: 如果您未提供此字段，网关将默认此值为NOT_CARDHOLDER_ACTIVATEDposTerminal.inputCapability: 此字段对于 EMV 交易是强制的。posTerminal.location: 此字段对于 EMV 交易是强制的。posTerminal.panEntryModeposTerminal.pinEntryCapabilityposTerminal.onlineReasonCode: 此字段对于所有在线交易的芯片和芯片回调交易（包括撤消）是强制的。posTerminal.serialNumberposTerminal.mobile.cardInputDevice: 此字段适用于能够接受点击屏幕或物理键盘来输入 PIN 的移动 POS (mPOS) 设备。 软件 PIN 应仅用于没有支持 PIN 输入的硬件键盘的设备。 有关 mPOS 集成的要求，请参见通过集成使用 mPOS。
处理磁条交易
如果卡轨数据从卡磁条读取，
- 在
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://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"
}
处理键控交易
如果在终端键盘手动输入卡号，
sourceOfFunds.provided.card.number[REST][NVP]
请求示例
这里是使用手动键入卡号的在线授权交易的示例。
| URL | https://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) 交易
P2PE 是支付卡行业标准委员会制定的标准。 使用 P2PE，敏感的卡数据会在读取卡数据后在终端立即加密。 由于您不必处理敏感数据，因此这会最大化持卡人在位交易的安全性，并会减少您的 PCI 合规义务。
ARC Pay Gateway 在 webServices Integration 版本 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.cardBinsourceOfFunds.provided.card.p2pe.encryptionState: 如果您未提供此字段，网关将默认此值为VALIDsourceOfFunds.provided.card.p2pe.initializationVector: 如果终端未使用初始化向量来进行加密，可以忽略此字段。
- 提供强制字段。
- 提供可选字段（如果需要）。
下表汇总了 sourceOfFunds.provided.card.p2pe 参数组的字段约束。
| 如果字段 | 那么网关... | ||
|---|---|---|---|
sourceOfFunds.provided.card.p2pe. initializationVector |
sourceOfFunds.provided.card.p2pe. keySerialNumber |
sourceOfFunds.provided.card.p2pe. payload | |
| 已提供 | 已提供 | 未提供 | 拒绝交易请求。 |
| 已提供 | 已在解密前或解密后提供，但使用纯文本 | 已提供 | 返回错误并生成安全日志条目。 |
交易响应
sourceOfFunds.provided.card.encryption 字段在交易响应中返回 DUKPT（webServices Integration 43 及更高版本）以指示卡数据已加密。 sourceOfFunds.provided.card.p2pe 参数组中的字段不在响应中返回。
集成以使用在线 PIN
持卡人输入的在线 PIN 在 PIN 输入设备内在源头加密。 ARC Pay Gateway 在 webServices Integration 45 及更高版本中支持 DUKPT (Derived Unique Key Per Transaction) 加密的在线 PIN 数据。
- 在以下字段中提供来自终端的 DUKPT 加密的 PIN 数据：
sourceOfFunds.provided.card.pin.payloadsourceOfFunds.provided.card.pin.keySerialNumberposTerminal.pinLengthCapabilitysourceOfFunds.provided.card.pin.encryptionState
- 提供强制字段。
- 提供可选字段（如果需要）。
通过集成使用 mPOS
从 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，否则网关将拒绝交易。
- 提供强制字段。
- 提供可选字段（如果需要）。
交易响应
如果付款人输入了无效的 PIN、超过了允许的 PIN 输入尝试次数，或在需要 PIN 来完成交易时跳过了 PIN 输入，PIN 身份验证可能失败。
在因 PIN 身份验证错误而导致授权失败的情况下，网关会返回特定的授权响应代码。 您可以在下一次交易中重新使用同一个订单 ID。
测试持卡人在位集成
您可以使用收单行专有的测试卡。