- Pautas de integración
- Características soportadas (métodos de pago)
- Pagos con titular de la tarjeta presente
Titular de la tarjeta presente
Los pagos con el titular de tarjeta presente (CHP) se refieren a transacciones que utilizan un terminal de punto de venta (POS). Los siguientes son los métodos del terminal para la lectura de datos de la tarjeta:
- inserción de una tarjeta EMV;
- NFC (Near Field Communication, comunicación de campo cercano) desde una tarjeta sin contacto;
- deslizamiento de una tarjeta con banda magnética;
- ingreso del número de la tarjeta con un teclado.
El soporte para todo lo anterior está disponible desde la versión 40 en adelante de Direct API.
El pago con CHP lo inicia un terminal y se envía al motor de pagos como una transacción Verify, Authorize, Capture, Pay o Refund. Por ejemplo, las transacciones que están autorizadas sin conexión mediante el chip de la tarjeta se enviarán solo como Capture, mientras que las transacciones que requieren autorización del emisor utilizarán una transacción Authorize en línea y, a continuación, una transacción Capture.
Las transacciones de CHP interactúan con muchas de las otras características del motor de pagos. Usted puede hacer lo siguiente:
- tokenizar la tarjeta;
- reembolsar utilizando la misma integración que sus transacciones de comercio electrónico, o a través de la UI;
- unificar el comercio electrónico y la reportería de CHP.
Prerrequisitos
Your payment service provider y su adquirente deben habilitarlo para las transacciones con titular de la tarjeta presente.
Campos comunes usados para transacciones CHP
Los siguientes campos de API son relevantes para todas las integraciones del titular de la tarjeta presente a través del motor de pagos.
transaction.source=CARD_PRESENT: si no proporciona este campo, se utilizará la fuente de transacción predeterminada que your payment service provider configuró en su vínculo de adquirente. [REST][NVP]- Número de tarjeta: es obligatorio proporcionar el número de la tarjeta, pero, dependiendo de la forma de lectura de la tarjeta, mediante el ingreso con teclado, banda magnética o chip EMV, puede proporcionarlo en:
.sourceOfFunds.provided.card.numberpara transacciones digitadas.sourceOfFunds.provided.card.track1y/osourceOfFunds.provided.card.track2para transacciones de banda magnética, o bien
sus equivalentes de etiqueta EMV, etiqueta 56 y etiqueta 57, proporcionadas respectivamente ensourceOfFunds.provided.card.emvRequestpara transacciones sin contacto, donde los datos de la tarjeta están en formato de banda magnética.- Etiqueta 5A en
sourceOfFunds.provided.card.emvRequestpara transacciones EMV (con o sin contacto), donde los datos de la tarjeta están en formato EMV. sourceOfFunds.provided.card.p2pe.payloadpara Transacciones P2PE (Cifrado punto a punto) donde los datos de la tarjeta están en formato cifrado DUKPT.
- Identificador de terminal: es obligatorio proporcionar el identificador de terminal, pero, dependiendo de la forma de lectura de la tarjeta, mediante el ingreso con teclado, banda magnética o chip EMV, puede proporcionarlo en:
posTerminal.lanepara transacciones digitadas y transacciones de cinta magnética.- Etiqueta 9F1C en
sourceOfFunds.provided.card.emvRequestpara transacciones EMV (con o sin contacto), donde los datos de la tarjeta están en formato EMV.
Asegúrese de que los valores de los siguientes campos de terminal de punto de venta se configuren correctamente, según cómo el terminal generó los datos de la tarjeta para la transacción. Si los datos de estos campos están disponibles, siempre proporciónelos. El motor de pagos pasará los datos al adquirente, según sea necesario. Si el adquirente requiere un campo y no está presente, la transacción no se podrá realizar.
posTerminal.addressposTerminal.attended: si no proporciona este campo, el motor de pagos estableceUNKNOWN_OR_UNSPECIFIEDcomo valor predeterminado.posTerminal.authorizationMethodposTerminal.cardHolderActivated: si no proporciona este campo, el motor de pagos estableceNOT_CARDHOLDER_ACTIVATEDcomo valor predeterminado.posTerminal.inputCapability: este campo es obligatorio para las transacciones EMV.posTerminal.location: este campo es obligatorio para las transacciones EMV.posTerminal.panEntryModeposTerminal.pinEntryCapabilityposTerminal.onlineReasonCode: este campo es obligatorio para las transacciones de chip y alternativa de chip (incluyendo reversiones) para todas las transacciones en línea.posTerminal.serialNumberposTerminal.mobile.cardInputDevice: este campo es aplicable a dispositivos POS móviles (mPOS), en los que el dispositivo puede aceptar un toque en la pantalla o el teclado físico para ingresar el PIN. El PIN del software solo debe usarse para dispositivos que no tienen un teclado de hardware para admitir la entrada de PIN. Para conocer los requisitos de integración de mPOS, consulte Integración para usar mPOS.order.gratuityAmount: proporcione este campo si el pago incluye un monto de propina.
[REST][NVP]order.cashbackAmount: proporcione este campo si el pago incluye un monto de devolución.
[REST][NVP]order.cashAdvance: proporcione este campo si el pago incluye un monto de anticipo en efectivo.
[REST][NVP]
Referencia de API de Terminal de punto de venta [REST][NVP]
Procesar una transacción de banda magnética
Si los datos de pista de la tarjeta se leyeron desde la banda magnética de la tarjeta:
- Proporcione los datos de la Pista 1 en el campo
sourceOfFunds.provided.card.track1o los datos de la Pista 2 en el camposourceOfFunds.provided.card.track2. Si tanto la Pista 1 como la Pista 2 están disponibles desde el terminal, proporcione ambos en la solicitud de transacción. - Complete los campos obligatorios.
- Complete los campos opcionales, si es necesario.
sourceOfFunds.provided.card.track1 [REST][NVP]
sourceOfFunds.provided.card.track2 [REST][NVP]
A continuación, se muestra un ejemplo de una transacción Authorization en línea, que utiliza datos de una banda magnética.
| URL | https://cnp.merchantlink.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| Método 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"
}
Procesar una transacción digitada
Si el número de tarjeta se ingresó manualmente en el teclado de su terminal:
- Proporcione el número de tarjeta ingresado en el campo de solicitud
sourceOfFunds.provided.card.number. - Complete los campos obligatorios.
- Complete los campos opcionales, si es necesario.
sourceOfFunds.provided.card.number[REST][NVP]
A continuación, se muestra un ejemplo de una transacción Authorization en línea, que utiliza un número de tarjeta ingresado manualmente.
| URL | https://cnp.merchantlink.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| Método 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"
}
Procesar una transacción de cifrado punto a punto (P2PE)
P2PE es un estándar establecido por el PCI Security Standards Council. Con P2PE, los datos confidenciales de la tarjeta se cifran en el terminal inmediatamente después de que se leen los datos de la tarjeta. Esto maximiza la seguridad de las transacciones actuales con el titular de la tarjeta presente y reduce sus obligaciones de cumplimiento de PCI ya que no tiene que manejar datos confidenciales.
Para procesar una transacción P2PE:
- Proporcione los datos DUKPT P2PE del terminal en los siguientes campos:
sourceOfFunds.provided.card.p2pe.keySerialNumber: debe proporcionar el número de serie de la clave DUKPT suministrado por el terminal.sourceOfFunds.provided.card.p2pe.payload: si se proporciona este campo,sourceOfFunds.provided.card.numberno es obligatorio. El motor de pagos extraerá todos los detalles pertinentes de la tarjeta de los datos de carga proporcionados.posTerminal.serialNumber:sourceOfFunds.provided.card.p2pe.cardBinsourceOfFunds.provided.card.p2pe.encryptionState: si no proporciona este campo, el motor de pagos se fija de forma predeterminada en el valorVALID.sourceOfFunds.provided.card.p2pe.initializationVector: este campo se puede omitir si el terminal no está usando un vector de inicialización para el cifrado seed.
- Complete los campos obligatorios.
- Complete los campos opcionales, si es necesario.
Referencia de API de P2PE [REST][NVP]
En la siguiente tabla se resumen las limitaciones del campo para el grupo de parámetros de sourceOfFunds.provided.card.p2pe.
| Si el campo | entonces el motor de pagos... | ||
|---|---|---|---|
sourceOfFunds.provided.card.p2pe. initializationVector |
sourceOfFunds.provided.card.p2pe. keySerialNumber |
sourceOfFunds.provided.card.p2pe. payload | |
| se proporciona | se proporciona | no se proporciona | rechaza la solicitud de transacción. |
| se proporciona | se proporciona, pero en texto sin formato antes o después del cifrado | se proporciona | devuelve un error y se genera una entrada en el registro de seguridad. |
Respuesta de la transacción
El campo sourceOfFunds.provided.card.encryption devuelve DUKPT (de Direct API versión 43 en adelante) en la respuesta de transacción para indicar que los datos de la tarjeta fueron cifrados. Los campos en el grupo de parámetros sourceOfFunds.provided.card.p2pe no se devuelven en la respuesta.
Integración para utilizar PIN en línea
El PIN en línea ingresado por el titular de la tarjeta está cifrado en la fuente, dentro del dispositivo de entrada del PIN. El Payment Gateway admite datos de PIN en línea cifrados con DUKPT (clave única derivada por transacción) desde Direct API versión 45 en adelante.
- Proporcione los datos de PIN cifrado con DUKPT del terminal en los siguientes campos:
sourceOfFunds.provided.card.pin.payloadsourceOfFunds.provided.card.pin.keySerialNumberposTerminal.pinLengthCapabilitysourceOfFunds.provided.card.pin.encryptionState
- Complete los campos obligatorios.
- Complete los campos opcionales, si es necesario.
Integración para utilizar mPOS
El motor de pagos permite aceptar pagos en dispositivos POS móviles (mPOS) desde la API v56 en adelante. Para habilitar la funcionalidad, proporcione lo siguiente en la transacción Verify, Authorize, Capture, Pay o Refund:
posTerminal.cardholderActivated=MPOS_ACCEPTANCE_DEVICE- Proporcione el valor del lector de tarjetas en el
posTerminal.mobile.cardInputDevice
BUILT_IN: teléfono móvil o tableta estándar con solo un lector sin contacto incorporado. En este caso, posTerminal.pinEntryCapability debe establecerse en SOFTWARE_ONLINE_PIN_ONLY; de lo contrario, el motor de pagos rechazará la transacción.INTEGRATED_DONGLE: terminal móvil dedicado con lector de tarjetas integrado. En este caso, posTerminal.pinEntryCapability debe establecerse en PIN_SUPPORTED u OFFLINE_PIN_ONLY; de lo contrario, el motor de pagos rechazará la transacción.SEPARATE_DONGLE: dispositivo estándar o terminal móvil dedicado, con lector de tarjetas por separado. En este caso, posTerminal.pinEntryCapability debe establecerse en PIN_SUPPORTED u OFFLINE_PIN_ONLY; de lo contrario, el motor de pagos rechazará la transacción.
- Complete los campos obligatorios.
- Complete los campos opcionales, si es necesario.
Respuesta de la transacción
La autenticación de PIN puede fallar si el pagador ingresa un PIN no válido, excede los intentos de ingreso de PIN permitidos u omite el ingreso del PIN cuando es obligatorio para completar la transacción.
En estos escenarios donde la autorización falla debido a un error de autenticación de PIN, el motor de pagos devolverá códigos de respuesta de autorización específicos. Puede reutilizar el mismo ID de pedido en la próxima transacción.
Integración de prueba de titular de la tarjeta presente
Puede probar su integración utilizando tarjetas de prueba específicas para su adquirente.