Integrar en Ingenico ePayments DirectLink (de servidor a servidor)

Ingenico ePayments DirectLink le permite configurar una integración de servidor a servidor con nuestra plataforma. Mientras que con Ingenico ePayments e-Commerce el cliente era redireccionado a la página de pago seguro (alojada por Ingenico ePayments), con DirectLink el cliente permanece en una página propia que enviará de forma segura los datos de pago a nuestros servidores.

También puede usar DirectLink para las tareas de mantenimiento de transacciones, independientemente de que se hayan iniciado en DirectLink o en, por ejemplo, el modo e-Commerce.

2.1 Usuario API

Para realizar solicitudes con DirectLink, se requiere un usuario de interfaz de programación de aplicaciones (API, Application Program Interface).

En general, se trata de un usuario diseñado de forma específica para que la aplicación lo utilice para realizar solicitudes automáticas a la plataforma de pago.

Puede crear un usuario API en su cuenta de Ingenico ePayments a través de "Configuración" > "Usuarios". Seleccione "Nuevo usuario" y complete los campos necesarios.

Para convertir al nuevo usuario en un usuario API, asegúrese de habilitar la casilla "Usuario Especial para el API (sin acceso a admin.)".

2.2 Formulario de solicitud

Para nuevas solicitudes de pedido, solicitudes de mantenimiento y consultas directas, debe enviar las solicitudes con determinados parámetros a las URL específicas. Los parámetros de nuevo pedido/mantenimiento/consulta deben enviarse en una solicitud POST de la siguiente forma:

PSPID=value1&USERID=value2&PSWD=value3&…

El tipo/subtipo que indica el tipo de medio en el campo Content-Type entity-header de la solicitud POST debe ser "application/x-www-form-urlencoded".

DirectLink funciona en modo “una solicitud-una respuesta”. Cada pago se procesa de forma individual. Nuestro sistema gestiona las solicitudes de transacción individuales a través de DirectLink y puede funcionar de forma sincrónica. (donde está opción es compatible desde un punto de vista técnico). Por ejemplo, esperamos la respuesta del banco antes de devolver una respuesta XML para la solicitud.

2.3 Seguridad

Cuando recibimos una solicitud en nuestros servidores, comprobamos el nivel de cifrado y la dirección IP desde la que se envió la solicitud.

2.3.1 Cifrado

DirectLink se basa en un protocolo sólido de comunicación segura. DirectLink El API de lote es un conjunto de instrucciones enviadas con solicitudes HTTPS POST estándar.

En el extremo del servidor, usamos un certificado proporcionado por Verisign. El cifrado TLS garantiza que se comunica con nuestros servidores y que sus datos se transmiten de forma cifrada. No es necesario un certificado TLS de cliente.

Cuando recibimos una solicitud, comprobamos el nivel de cifrado. Permitimos a los comerciantes que se pongan en contacto con nosotros solo mediante el modo https seguro, usando protocolos TLS y recomendamos encarecidamente utilizar las versiones más recientes y seguras, que actualmente son TLS 1.1 y 1.2.

Nota: En este momento, seguimos siendo compatibles con SSL v3. No obstante, debido a determinadas vulnerabilidades, este protocolo se está quedando anticuado y con el tiempo dejará de ser compatible.

2.3.2 Dirección IP

Con cada solicitud, nuestro sistema comprueba la dirección IP en la que se originó la solicitud para garantizar que las solicitudes se están enviando desde el servidor del comerciante. En el campo Dirección IP de la sección "Comprobaciones de DirectLink" de la pestaña "Verificación de datos y origen" de la página Información técnica de la cuenta, debe especificar la dirección o las direcciones IP o el rango o rangos IP de los servidores que envíen sus solicitudes.

Si la dirección IP de origen no se ha declarado en el campo de dirección IP correspondiente, recibirá el mensaje de error “pedido desconocido/1/i”. La dirección IP desde la que se envió la solicitud también aparecerá en el mensaje de error.

2.3.3 Firma SHA

La firma SHA se basa en el principio del servidor del comerciante que genera una cadena de caracteres única para cada pedido, generando un hash con algoritmos SHA-1, SHA-256 o SHA-512. El resultado de este hash se nos envía más adelante en su solicitud de pedido. Nuestro sistema reconstruye esta firma para comprobar la integridad de los datos del pedido que se nos han enviado en la solicitud.

Vaya a Firma SHA-IN (documentación de Ingenico ePayments e-Commerce). El principio es el mismo en modo e-Commerce y DirectLink.

Para DirectLink, la frase de contraseña SHA-IN debe configurarse en la sección "Comprobaciones de DirectLink" en la pestaña "Verificación de datos y origen" de su página Información técnica.

2.4 Análisis de respuesta

Devolveremos una respuesta XML a su solicitud. Asegúrese de que sus sistemas analizan esta respuesta XML con la mayor tolerancia posible para evitar problemas en el futuro. Por ejemplo, evitar nombres de atributos que distinguen mayúsculas de minúsculas, no formular un orden específico para los atributos devueltos en respuestas, garantizar que los nuevos atributos de la respuesta no causen problemas, etc.

3.1 URL de solicitud

• La URL de solicitud en el entorno de PRUEBA es https://ogone.test.v-psp.com/ncol/test/orderdirect.asp.
• La URL de solicitud en el entorno de PRODUCCIÓN es https://secure.ogone.com/ncol/prod/orderdirect.asp.

3.2 Parámetros de solicitud

La siguiente tabla contiene los parámetros de solicitud para enviar una nueva solicitud de pedido:

Los siguientes parámetros de solicitud son obligatorios en los pedidos nuevos:

• PSPID y USERID
• PSWD
• ORDERID
• AMOUNT (x 100)
• CURRENCY
• CARDNO
• ED
• CVC
• OPERATION 

3.3 Página de prueba

Nuestra página de prueba para enviar solicitudes de pedido en DirectLink está disponible aquí: https://ogone.test.v-psp.com/ncol/test/testodl.asp.

3.4 Excluding specific payment methods

If there are payment methods you don't want a customer to be able to pay with, you can use a parameter to do so.
This is particularly useful for sub-brands, when you want to accept a brand (e.g. MasterCard) but not one of its sub-brands (e.g. Maestro).

The parameter is the following:

If a customer tries paying with a card linked to a payment method and/or (sub)brand you've excluded using the EXCLPMLIST parameter, the error message “Card number incorrect or incompatible” will be returned with the NCERRORPLUS return field.

3.5 Solicitud de pedido mediante 3-D Secure

Nuestro sistema admite el uso de 3-D Secure con DirectLink.

3.6 Dividir tarjetas de crédito/débito

La funcionalidad para dividir VISA y MasterCard en un método de pago de débito y de crédito le permite ofrecérselo a sus clientes como dos métodos de pago distintos (p. ej. VISA Débito y VISA Crédito) o puede decidir aceptar solo una de las dos marcas divididas.

Para utilizar la división de tarjetas de crédito y débito a través de DirectLink, tiene que incluir el parámetro CREDITDEBIT en los campos ocultos que envía a la página orderdirect.asp (y por tanto también se incluyen en el cálculo de SHA-IN).

Error relacionado: Cuando el comprador selecciona el método de tarjeta de crédito, pero introduce a continuación un número de tarjeta de crédito, se devuelve un código de error: ‘Se ha elegido una marca/método de pago incorrecto’.

Si el pago se ha procesado de forma correcta con el parámetro CREDITDEBIT, se devolverá el mismo parámetro en la respuesta XML o podrá solicitarse con una consulta directa. No obstante, mientras que los valores enviados sean C o D, los valores devueltos son "CREDIT" o "DEBIT".

También encontrará estos valores devueltos en la descripción general de la transacción a través de "Ver transacciones" e "Historial financiero", así como en informes que puede descargar más adelante.

3.7 Procesamiento de transacciones con credenciales guardadas

La transacción de credencial en archivo (COF) utiliza los detalles de la tarjeta que ya están almacenados por los comerciantes para procesar el pago. Antes de iniciar una transacción de credencial en archivo (COF), el titular de la tarjeta primero deberá autorizar al comerciante a almacenar los detalles de la tarjeta. La transacción de credencial en archivo (COF) se aplica principalmente a los pagos recurrentes y establece si es el titular de la tarjeta o el comerciante quien inicia el pago.

Hay dos tipos de transacciones de credenciales en archivo (COF): transacción iniciada por el titular de la tarjeta (CIT) o transacción iniciada por el comerciante (MIT). La transacción iniciada por el titular de la tarjeta (CIT) siempre deberá realizarse antes de la transacción iniciada por el comerciante (MIT).

Una transacción iniciada por el titular de la tarjeta (CIT) es una transacción en la que el titular de la tarjeta participa en la transacción y autentica personalmente la transacción mediante una firma, un dispositivo 3D-Secure o la presentación de documentos identificativos.

Ejemplo de una transacción iniciada por el titular de la tarjeta (CIT):

El titular de una tarjeta compra un billete de tren en línea y realiza un pago. Realiza el pago con su tarjeta de crédito y se le pide que autentique y autorice el pago. Al mismo tiempo, se pregunta al titular de la tarjeta si desea guardar la información de la tarjeta de crédito relacionada con este pago. Si el titular de la tarjeta está de acuerdo, esta información se puede reutilizar en futuras transacciones iniciadas por el comerciante.

Una transacción iniciada por el comerciante (MIT) es una transacción iniciada por un comerciante que supervisa una transacción iniciada por el titular de la tarjeta (CIT) y por un pedido permanente previamente acordado de bienes y servicios comprados por el titular de la tarjeta. El titular de la tarjeta no tiene por qué estar involucrado en la transacción.

Ejemplo de una transacción iniciada por un comerciante (MIT):

Un comerciante puede iniciar automáticamente una transacción para cumplir con el pago del titular de la tarjeta en una suscripción mensual a una revista.

Esto le afecta si:

• Utiliza un alias
• Planea iniciar transacciones recurrentes (programadas o no) después de iniciar por primera vez una transacción iniciada por el titular de la tarjeta (CIT)

De forma predeterminada, estos parámetros se utilizan en una transacción de DirectLink Server-to-Server:

Los valores predeterminados se marcan si no se añade ningún parámetro. Sin embargo, si desea cambiarlos, puede sobrescribir estos valores predeterminados enviando los nuevos parámetros. No olvide recalcular también la firma SHA (haga clic aquí para obtener más información sobre la firma SHA.)

Nuestro servidor devuelve una respuesta XML a la solicitud:

La siguiente tabla contiene una lista de los atributos de etiqueta ncresponse:

La lista de atributos puede ser más larga para comerciantes que tengan activadas determinadas opciones (por ejemplo, la Detección de fraude) en sus cuentas. Consulte la documentación de la opción correspondiente para obtener más información acerca de los atributos de respuesta adicionales vinculados a la opción.

4.1 Solicitud duplicada

Una solicitud de mantenimiento directa de su aplicación le permite:

• Realizar una captura de datos (pago) de un pedido autorizado de forma automática (en lugar de hacerlo manualmente en el área de administración);
• Cancelar una autorización sobre un pedido;
• Renovar una autorización de un pedido;
• Reembolsar un pedido pagado.

5.1 Solicitud de mantenimiento

5.1.1 URL de solicitud

• La URL de solicitud del entorno de PRUEBA es https://ogone.test.v-psp.com/ncol/test/maintenancedirect.asp.
• La URL de solicitud del entorno de PRODUCCIÓN es https://secure.ogone.com/ncol/prod/maintenancedirect.asp.

5.1.2 Parámetros de solicitud

La siguiente tabla contiene los parámetros de solicitud obligatorios para realizar una operación de mantenimiento:

5.1.3 Página de prueba

Puede probar las solicitudes de mantenimiento directas aquí: https://ogone.test.v-psp.com/ncol/test/testdm.asp

5.2 Respuesta de mantenimiento

Nuestro servidor devuelve una respuesta XML a la solicitud:

La siguiente tabla contiene una lista de los atributos de etiqueta ncresponse:

Los atributos de etiqueta ncresponse estándar son los mismos que los de la respuesta XML a un nuevo pedido, salvo el atributo extra PAYIDSUB.

5.3 Solicitud duplicada

Si se solicita mantenimiento dos veces para el mismo pedido, el segundo se rechazará, en teoría, con un error “50001127” (este pedido no está autorizado), porque la transacción correcta inicial habrá cambiado el estado del pedido.

Una solicitud de consulta directa de su aplicación le permite consultar el estado de un pedido de forma automática (a diferencia de manualmente en el área de administración). Solo puede consultar un pago a la vez y solo recibirá un importe limitado de información sobre el pedido.

Si necesita más detalles sobre el pedido, puede buscar la transacción en el área de administración o realizar una descarga de archivo manual o automática (consulte Consultar sus transacciones y Fichero de Lote).

6.1 Solicitud de consulta

6.1.1 URL de solicitud

• La URL de solicitud del entorno de PRUEBA es https://ogone.test.v-psp.com/ncol/test/querydirect.asp
• La URL de solicitud del entorno de PRODUCCIÓN es https://secure.ogone.com/ncol/prod/querydirect.asp

6.1.2 Parámetros de solicitud

La siguiente tabla contiene los parámetros de solicitud obligatorios para realizar una consulta directa:

6.1.3 Página de prueba

Puede probar las solicitudes de consulta directa aquí: https://ogone.test.v-psp.com/ncol/test/testdq.asp.

6.2 Respuesta de consulta

Nuestro servidor devuelve una respuesta XML a la solicitud:

La siguiente tabla contiene una lista de los atributos de etiqueta ncresponse:

Los atributos de etiqueta ncresponse estándar son idénticos a los de la respuesta XML a un nuevo pedido, salvo los atributos adicionales PAYIDSUB, CARDNO e IP.

La lista de atributos puede ser más larga para comerciantes que tengan activadas determinadas opciones (por ejemplo, la Detección de fraude) en sus cuentas. Consulte la documentación de la opción respectiva para obtener más información acerca de los atributos de respuesta adicionales vinculados a la opción. 

6.2.1 Transacciones procesadas con e-Commerce

Si la transacción cuyo estado desea comprobar se ha procesado con e-Commerce, puede que también reciba los siguientes atributos adicionales (siempre que haya enviado estos campos con la transacción original de e-Commerce).

*Consulte Parámetros de respuesta variables en la documentación de e-Commerce.

6.3 Posibles estados de respuesta

El campo STATUS contendrá el estado de la transacción (consulte Posibles estados).

Solo el siguiente estado está relacionado de forma específica con la propia consulta:

6.4 Consulta directa como último recurso

Los tiempos de respuesta de una solicitud de transacción de DirectLink suelen ser de unos pocos segundos. No obstante, algunas entidades adquirentes pueden tener tiempos de respuesta más largos.  

Si no ha recibido una respuesta de nuestro sistema pasados 30 segundos, puede enviar una solicitud a querydirect.asp, pidiéndole el estado de su transacción más reciente enviada a orderdirect.asp. Si recibe una respuesta inmediata que contenga un estado no final para la transacción, puede que haya problemas por parte de la entidad adquirente.

Si no ha recibido una respuesta a esta solicitud de consulta directa pasados 10 segundos, puede que haya problemas de nuestro lado. Puede repetir esta solicitud a querydirect.asp cada 30 segundos hasta que vea que ha recibido una respuesta en 10 segundos.

7.1 URL de solicitud

7.1.1 Solicitud de consulta

• La URL de solicitud del entorno de PRUEBA es https://secure.ogone.com/ncol/test/privacy-policy.asp

Cambiar "test" a "prod"

7.1.2 Parámetros de solicitud

La tabla siguiente contiene los parámetros de solicitud obligatorios que enviar a su cliente en relación al uso de su información de privacidad:

7.1.3 Página de prueba

Puede probar las solicitudes de consulta directa aquí: https://secure.ogone.com/ncol/test/privacy-policy.asp

7.2 Respuesta de consulta

A continuación se muestra una lista de elementos XML y los ejemplos de respuestas XML devueltas para distintos resultados.

<?xml version="1.0" encoding="utf-8"?>
 <Response>
    <Status>SuccessWithWarnings</Status>
    <Warnings>
        <Warning>
            <Code>NoContent</Code>
        </Warning>
    </Warnings>
    <Body>
        <Html/>
    </Body>
 </Response>

<?xml version="1.0" encoding="utf-8"?>
<Response>
    <Status>Success</Status>
    <Body>
        <Html><![CDATA[<ul><li><h2>Title 1</h2><p>Content 1</p></li><li>
<h2>Title 2 (VISA, American Express)</h2><p>Content 2</p></li></ul>]]></Html>
    </Body>
</Response>

Para determinados métodos de pago, los valores de parámetro difieren de los de tarjeta de crédito estándar.

8.1 Direct Debits

8.1.1 Domiciliaciones AT

La siguiente tabla contiene los valores de parámetro específicos que permiten la transmisión de transacciones de Domiciliaciones AT a través de DirectLink.

_{(*Si la opción Reembolso está disponible y activa, y Reembolsos de DTAUS está disponible)}

8.1.2 Domiciliaciones DE (ELV)

La siguiente tabla contiene los valores de parámetro específicos, que permiten la transmisión de transacciones de ELV a través de DirectLink. (no Wirecard/Billpay)

_{(*Si la opción Reembolso está disponible y activa, y Reembolsos de DTAUS está disponible)}

8.1.3 Domiciliaciones NL

La siguiente tabla contiene los valores de parámetro específicos que permiten la transmisión de transacciones de Domiciliaciones NL a través de DirectLink.

_{(*SEPA: Single Euro Payments Area o Zona Única de Pagos en Euros)}

Nota: Estos campos se pueden devolver en la respuesta XML de DirectLink y deben incluirse en el cálculo SHA-IN (y, opcionalmente, SHA-OUT).

8.2 Métodos de pago con solo mantenimiento a través de DirectLink

Para determinados métodos de pago (tarjeta que no sea de crédito), no puede enviar nuevas transacciones a través de DirectLink, pero puede enviar determinadas operaciones de mantenimiento a través de DirectLink. Es el caso de la tarjeta PostFinance, PostFinance E-finance, compra mediante PayPal Express y TUNZ. Cuando se envían operaciones de mantenimiento, PM/BRAND/CARDNO/ED no son campos necesarios, así que, para estos métodos de pago, no deben enviarse valores específicos.