- 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 DirectAPI.
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 EMV
Si los datos de la tarjeta se leyeron desde el chip de una tarjeta (solo tarjetas EMV):
- Solicite el terminal para estas etiquetas EMV (etiquetas admitidas por el motor de pagos).
- Proporcione las etiquetas devueltas en el campo
sourceOfFunds.provided.card.emvRequestcomo un objeto JSON en el protocolo REST o como una colección de campos en el protocolo NVP (está bien si su terminal no proporciona todas las etiquetas EMV admitidas).Los valores de las etiquetas EMV se deben formatear exactamente como el terminal las devolvió. Los valores binarios se representarán en formato hexadecimal. - Complete los campos obligatorios.
- Complete los campos opcionales, si es necesario.
sourceOfFunds.provided.card.emvRequest [REST][NVP]
Algunas de las etiquetas EMV admitidas corresponden a conceptos de pago básico, como el número de cuenta principal. Estos conceptos también aparecen como campos de solicitud de API, como sourceOfFunds.provided.card.number. La documentación de Referencia de API para estos campos de solicitud de API correspondientes muestra su vinculación en la descripción. Por ejemplo, la descripción para sourceOfFunds.provided.card.number contiene el texto "Este campo corresponde a EMV etiqueta 5A".
Si proporciona datos como una etiqueta EMV, no necesita proporcionar el mismo campo que una solicitud de API. El motor de pagos rellena los campos de solicitud de API correspondientes con los valores proporcionados en las etiquetas EMV, donde existen, y utiliza estos valores en todas las tareas de procesamiento interno, de mensajería del adquirente y de respuestas de transacción. Por ejemplo, si envía sourceOfFunds.provided.card.emvRequest.9F1C con el valor -Lane_03', posTerminal.lane con el valor -Lane_03' se envía al adquirente y se devuelve en la respuesta de la transacción.
Si es necesario, puede elegir proporcionar las etiquetas EMV y los campos de solicitud de API correspondientes en la solicitud de transacción. Consulte Uso avanzado: datos de transacción tanto en etiquetas EMV como en campos de solicitud de API.
A continuación, se muestra un ejemplo de una solicitud de EMV en REST para una transacción Standalone Capture, en la que la autorización se realizó sin conexión en el terminal.
| URL | https://ap-gateway.mastercard.com/api/rest/version/72/merchant/{merchantId}/order/{orderid}/transaction/{transactionid} |
| Método HTTP | PUT |
{
"apiOperation": "CAPTURE",
"transaction": {
"currency": "EUR",
"amount": "10.99",
"source": "CARD_PRESENT"
},
"sourceOfFunds": {
"type": "CARD",
"provided": {
"card": {
"number": "5457210089020012",
"expiry": {
"month": "1",
"year": "39"
},
"emvRequest": {
"82": "0000",
"95": "0000000000",
"9F02": "000000001099",
"9A": "161021",
"5F2A": "840",
"9F1A": "840",
"9F10": "06011103A000000A0100000000000BB0ABAD",
"9F34": "1E0300",
"9F36": "0002",
"9C": "00",
"9F26": "D1F722D47FCA8273",
"9F27": "40",
"9F37": "2A4E1690",
"9F33": "E0B8C8"
}
}
}
},
"posTerminal": {
"inputCapability": "CONTACTLESS_CHIP",
"panEntryMode": "CHIP",
"pinEntryCapability": "PIN_SUPPORTED",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"lane": "Lane_03",
"attended": "ATTENDED",
"serialNumber":"123456789",
"onlineReasonCode":"FORCED_BY_MERCHANT",
"cardPresenceCapability":"CARD_PRESENT",
"authorizationMethod":"OFFLINE",
"address":
{
"country":"IRL",
"city":"Dublin"
}
}
}
{
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TESTSMOKE-RETAIL",
"order": {
"amount": 10.99,
"creationTime": "2017-06-06T09:42:54.280Z",
"currency": "EUR",
"id": "sa-dfc1b030-4520-48ec-a7e0-889999d7e4ab",
"status": "CAPTURED",
"totalAuthorizedAmount": 10.99,
"totalCapturedAmount": 10.99,
"totalRefundedAmount": 0
},
"posTerminal": {
"address": {
"city": "Dublin",
"country": "IRL"
},
"attended": "ATTENDED",
"authorizationMethod": "OFFLINE",
"cardPresenceCapability": "CARD_PRESENT",
"cardholderActivated": "NOT_CARDHOLDER_ACTIVATED",
"inputCapability": "CONTACTLESS_CHIP",
"lane": "Lane_03",
"location": "MERCHANT_TERMINAL_ON_PREMISES",
"onlineReasonCode": "FORCED_BY_MERCHANT",
"panEntryMode": "CHIP",
"pinEntryCapability": "PIN_SUPPORTED",
"serialNumber": "123456789"
},
"response": {
"gatewayCode": "APPROVED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "MASTERCARD",
"emvRequest": {
"82": "0000",
"95": "0000000000",
"5F2A": "840",
"9A": "161021",
"9C": "00",
"9F02": "000000001099",
"9F10": "06011103A000000A0100000000000BB0ABAD",
"9F1A": "840",
"9F26": "D1F722D47FCA8273",
"9F27": "40",
"9F33": "E0B8C8",
"9F34": "1E0300",
"9F36": "0002",
"9F37": "2A4E1690"
},
"emvResponse": {
"4D3E": "456",
"5A2F": "123"
},
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "DEBIT",
"issuer": "CAPITAL ONE BANK (CANADA BRANCH)",
"number": "545721xxxxxx0012",
"scheme": "MASTERCARD"
}
},
"type": "CARD"
},
"timeOfRecord": "2017-06-06T09:42:54.280Z",
"transaction": {
"acquirer": {
"batch": 1,
"id": "FOOBANK",
"merchantId": "11223344"
},
"amount": 10.99,
"currency": "EUR",
"frequency": "SINGLE",
"id": "1",
"receipt": "1706063974",
"source": "CARD_PRESENT",
"terminal": "0001",
"type": "CAPTURE"
},
"version": "43"
}
La siguiente es una lista de etiquetas EMV admitidas por el motor de pagos. Si el terminal devuelve alguna de estas, inclúyala en el campo sourceOfFunds.provided.card.emvRequest.
Etiqueta EMV |
Nombre |
Obligatorio |
|---|---|---|
| 4F | Nombre de identificador de aplicación (AID) | - |
| 56 | Pista 1 | - |
| 57 | Datos equivalentes de pista 2 | - |
| 5A | Número de cuenta principal (PAN) de la aplicación |
- |
| 5F24 | Fecha de vencimiento de la aplicación | - |
| 5F25 | Fecha de aplicación efectiva | - |
| 5F28 | Código del país emisor | - |
| 5F2A | Código de moneda de transacción | - |
| 5F34 | Número de secuencia del número de cuenta principal (PAN) de la aplicación |
- |
| 82 | Perfil de intercambio de la aplicación (AIP) | Sí |
| 84 | Nombre de archivo dedicado | - |
| 87 | Indicador de prioridad de aplicación | - |
| 95 | Resultado de verificación del terminal (TVR) | Sí |
| 9A | Fecha de la transacción | Sí |
| 9B | Información del estado de la transacción | - |
| 9C | Tipo de transacción | Sí |
| 9F02 | Monto autorizado | Sí |
| 9F03 | Monto de devolución | - |
| 9F06 | Identificador de aplicación (AID): terminal | - |
| 9F07 | Control de uso de aplicación | - |
| 9F08 | Número de versión de la aplicación: ICC | - |
| 9F09 | Número de versión de la aplicación: terminal | - |
| 9F0D | Código de acción del emisor: predeterminado | - |
| 9F0E | Código de acción del emisor: rechazo | - |
| 9F0F | Código de acción del emisor: en línea | - |
| 9F10 | Datos de aplicación del emisor (IAD) | Sí |
| 9F1A | Código de país de terminal | Sí |
| 9F1C | Identificación de terminal | - |
| 9F1E | Número de serie del dispositivo de interfaz (IFD) | - |
| 9F21 | Hora de la transacción | - |
| 9F26 | Criptograma de aplicación (AC) | Sí |
| 9F27 | Datos de información de criptograma (CID) | Sí |
| 9F33 | Capacidades del terminal | - |
| 9F34 | Resultados del método de verificación de titular de la tarjeta (CVM) | Sí |
| 9F35 | Tipo de terminal | - |
| 9F36 | Contador de transacciones de aplicación | Sí |
| 9F37 | Número impredecible | Sí |
| 9F39 | Modo de entrada del punto de servicio (POS) | - |
| 9F40 | Capacidades adicionales del terminal | - |
| 9F41 | Contador de secuencia de transacción | - |
| 9F49 | Lista de objetos de datos de autenticación dinámica (DDOL) | - |
| 9F53 | Código de categoría de transacción | - |
| 9F5A | EMV (Kernel 3) : identificador del programa de aplicación (ID de programa) EMV (Kernel 4) : identificador de producto de suscripción |
- |
| 9F5B | EMV (Kernel 3) : resultados de script de emisor EMV (Kernel 2) : DSDOL EMV (Kernel 4) : número de suscripción de producto |
- |
| 9F66 | EMV (Kernel 2) : PUNATC(Track2) EMV (Kernel 3) : calificadores de transacciones de terminal (TTQ) |
- |
| 9F6E | Indicador de factor de forma | - |
| 9F7C | Datos exclusivos del cliente (CED) | - |
Si proporciona las etiquetas EMV y los campos de solicitud de API correspondientes en la solicitud de transacción, el motor de pagos utiliza el valor proporcionado en el campo de solicitud de la API correspondiente. Por ejemplo, si envía sourceOfFunds.provided.card.emvRequest.9F1C con el valor 'Lane_03' y posTerminal.lane con el valor 'Lane_04', entonces posTerminal.lane con el valor 'Lane_04' se envía al adquirente y se devuelve en la respuesta de la transacción. Esto puede ser útil si desea anular las etiquetas EMV y los valores de control campo por campo. Observe que tal uso es extraño y, por tanto, debe considerarse solo si su integración lo requiere.
Etiquetas EMV admitidas y los campos de solicitud de API correspondientes
En esta tabla se enumeran las etiquetas EMV donde el motor de pagos rellena los campos de solicitud de API correspondientes con los valores proporcionados en las etiquetas EMV.
Etiqueta EMV |
Nombre de etiqueta EMV |
Campo de solicitud de API correspondiente |
|---|---|---|
| 56 | Pista 1 | sourceOfFunds.provided.card.track1 |
| 57 | Datos equivalentes de pista 2 | sourceOfFunds.provided.card.track2 |
| 5A | Número de cuenta principal (PAN) de la aplicación | sourceOfFunds.provided.card.number |
| 5F24 | Fecha de vencimiento de la aplicación | sourceOfFunds.provided.card.expiry.year sourceOfFunds.provided.card.expiry.month |
| 5F34 | Número de secuencia PAN | sourceOfFunds.provided.card.sequenceNumber |
| 9C | Avance en efectivo | order.cashAdvance |
| 9F03 | Monto de devolución | order.cashbackAmount |
| 9F1A | Código de país de terminal | posTerminal.address.country |
| 9F1C | Identificación de terminal | posTerminal.lane |
| 9F1E | Número de serie del dispositivo de interfaz | posTerminal.serialNumber |
| 9F33 | Capacidades del terminal | posTerminal.inputCapability posTerminal.pinEntryCapability |
| 9F35 | Tipo de terminal | posTerminal.attended posTerminal.cardholderActivated |
El motor de pagos devuelve el campo sourceOfFunds.provided.card.emvResponse en la respuesta Retrieve Order y Retrieve Transaction. Este campo contiene datos generados por el emisor, que la tarjeta o el dispositivo pueden utilizar para que la verificación complete o rechace la transacción. También puede contener etiquetas EMV adicionales del emisor, incluyendo etiquetas repetidas de la solicitud.
La siguiente tabla muestra algunas etiquetas EMV que se pueden devolver en una respuesta Authorization en línea.
| Etiqueta EMV | Nombre |
|---|---|
| 8A | Código de respuesta de autorización |
| 89 | Código de autorización |
| 91 | Datos de autenticación del emisor |
| 71 | Plantilla de script de emisor 1 |
| 72 | Plantilla de script de emisor 2 |
El campo sourceOfFunds.provided.card.emvRequest proporcionado en la solicitud se reenvía en la respuesta, donde se excluyen las etiquetas EMV identificadas como confidenciales de PCI.
Su adquirente puede requerir elementos de datos EMV adicionales, que se incluirán al anular una transacción EMV. Por ejemplo, puede que se requiera la etiqueta EMV DF01 (Resultados de script de emisor). Póngase en contacto con su adquirente para conocer los requisitos específicos.
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://ap-gateway.mastercard.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://ap-gateway.mastercard.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 DirectAPI 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 Mastercard Gateway admite datos de PIN en línea cifrados con DUKPT (clave única derivada por transacción) desde DirectAPI 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.