- Pautas de integración
- Implementación de una integración de Hosted Payment Session
- El modelo de Hosted Payment Session con JavaScript
- Cree su integración
Cree su integración
Esta página proporciona instrucciones sobre cómo realizar una integración mediante el modelo de Hosted Payment Session con JavaScript (HPF.js). Crear y enviar la página de pago son pasos críticos en la integración de comerciante para este modelo. Los detalles de la tarjeta recopilados del pagador se envían directamente a la Mastercard Gateway mediante un método JavaScript. Mastercard Gateway almacena los detalles de la tarjeta en un identificador de sesión, que se le devuelve cuando se resuelven todos los errores. Puede usar el identificador de sesión en lugar de los detalles de tarjeta para iniciar una transacción de pago.
Incluya la biblioteca de JavaScript (hpf.js) de Hosted Payment Session en la página de pago y configure el ID de comerciante:
<script id="hpfScript" src="https://mtf.gateway.mastercard.com/form/v3/hpf.js"></script> <script>HostedForm.setMerchant(<my merchantId>);</script>
<my merchantId> con el ID de comerciante proporcionado por Mastercard Gateway. Para probar su integración como un comerciante de prueba, escriba como prefijo “TEST” en el ID de comerciante. Por ejemplo, TESTCOMERCIANTE123 donde el ID de comerciante es “COMERCIANTE123”.Debe recopilar los detalles de la tarjeta (número de tarjeta, código de seguridad, mes y año de vencimiento) del pagador y transmitirlos en el método HostedForm.createSession( )/HostedForm.updateSession( ). El siguiente es un ejemplo de formulario HTML que recopila todos los detalles de tarjeta.
<!-- REPLACE THE action URL with the payment URL on your webserver --> <form name="myform" method="POST" action="https://my.company.com/pay">
<!-- Name attributes are not provided for the card details to stop them from being submitted to your web server as part of the form submission --> Tarjeta: <input type="text" id="cardNumber"> CSC: <input type="text" id="cardSecurityCode"> Mes: <input type="text" id="expiryMonth"> Año: <input type="text" id="expiryYear">
<!-- Other fields can be added to enable you to collect additional data on the payment page --> Correo electrónico: <input type="text" name="email">
<!-- The hidden values below can be set in the updateSessionCallback function as they are returned when creating the session --> <input type="hidden" name="sessionId" id="sessionId"> <input type="hidden" name="cardBrand" id="cardBrand"> <input type="button" value="Pay" onclick="doCheckout()"> </form>
"https://my.company.com/pay" con la URL de su servidor web que hospeda una página que administrará el procesamiento del pago cuando se haya creado un identificador de sesión.La biblioteca HPF.js proporciona los siguientes métodos para crear y/o actualizar una sesión, que se llaman cuando se envían los detalles de tarjeta.
Crear una sesión
Puede crear una sesión con el método HostedForm.createSession( ), el cual toma los detalles de tarjeta recopilados del pagador y una función de devolución de llamada como parámetros.
HostedForm.createSession(sessionDetails, createSessionCallback);
De manera alternativa, puede crear una nueva sesión si llama al método HostedForm.updateSession( ) sin transmitir un identificador de sesión.
HostedForm.updateSession(sessionDetails, updateSessionCallback);
El siguiente es un ejemplo de código que le muestra cómo llamar al método HostedForm.createSession() o al método HostedForm.updateSession() para crear una nueva sesión.
// Collect the card details based on the 'id' of the form elements
var getSessionDetailsFromForm = function() {
return {
cardNumber: document.getElementById('cardNumber').value,
cardSecurityCode: document.getElementById('cardSecurityCode').value,
cardExpiryMonth: document.getElementById('expiryMonth').value,
cardExpiryYear: document.getElementById('expiryYear').value
}
}
// Call doCheckout() from the form submit onClick() event
var doCheckout = function() {
var sessionDetails = getSessionDetailsFromForm();
HostedForm.createSession(sessionDetails, callback);
// HostedForm.updateSession(sessionDetails, callback);
};
Actualizar una sesión
Si llama al método HostedForm.updateSession( ) transmitiendo un identificador de sesión, entonces los detalles de la sesión, si esta existe, se actualizan. Esto resulta útil si ya tiene una sesión que contiene detalles como la dirección de facturación y envío, pero desea agregar los detalles de pago a la sesión más adelante en el flujo del proceso de compra. O bien, si desea recopilar otros detalles de la tarjeta del pagador debido a que los detalles recopilados anteriormente no son aceptables, por ejemplo, si la marca de tarjeta no se aceptó.
HostedForm.updateSession(sessionId, sessionDetails, updateSessionCallback);
El siguiente es un ejemplo de código que le muestra cómo llamar al método HostedForm.updateSession() para actualizar una sesión existente.
// Collect the card details based on the 'id' of the form elements
var getSessionDetailsFromForm = function() {
return {
cardNumber: document.getElementById('cardNumber').value,
cardSecurityCode: document.getElementById('cardSecurityCode').value,
cardExpiryMonth: document.getElementById('expiryMonth').value,
cardExpiryYear: document.getElementById('expiryYear').value
}
}
// Call doCheckoutWithExistingSession() from the form submit onClick() event
var doCheckoutWithExistingSession = function(sessionId) {
var sessionDetails = getSessionDetailsFromForm();
HostedForm.updateSession(sessionId, sessionDetails, callback);
};
Cuando Mastercard Gateway procesa su formulario, la respuesta es administrada por una función de devolución de llamada que usted debe definir en su página Web. Esta función recibe un objeto que describe el resultado de la llamada a HostedForm.createSession( ) o HostedForm.updateSession( ).
Si response.status es “ok”, su página Web debe transmitir el identificador de sesión devuelto a su servidor Web para que se pueda usar para invocar una transacción. Si response.status es “fields_in_error”, su página Web debe analizar campos individuales en busca de errores. Para obtener información sobre códigos de error, consulte Administración de Errores de Formulario de Pago.
El siguiente es un ejemplo de código que incluye el identificador de sesión y el elemento de marca de tarjeta en el formulario de pago que se envía a su servidor Web.
var callback = function(response) {
if (response.status === "ok") {
// call your server to do the payment with the response.session value
// this is where we populate the hidden values in the form
var sessionIdElement = document.getElementById("sessionId");
sessionIdElement.value = response.session;
// card brand is not required to be submitted, but shown here as an optional field
// the response object contains the full list of fields
var cardBrandElement = document.getElementById("cardBrand");
cardBrandElement.value = response.cardBrand;
document.myform.submit();
} else if (response.status === "request_timeout") {
// handle the timeout for example by giving the payer the possibility to retry
} else if (response.status === "fields_in_error") {
// check in the response.fieldsInError object to see which field was marked as invalid or missing
if (response.fieldsInError.cardNumber === "invalid") {
document.getElementById('cardNumber').style.color="red";
} else if (response.fieldsInError.cardExpiryMonth === "invalid") {
document.getElementById('expiryMonth').style.color="red";
} else if (response.fieldsInError.cardExpiryYear === "invalid") {
document.getElementById('expiryYear').style.color="red";
} else if (response.fieldsInError.cardSecurityCode === "invalid") {
document.getElementById('cardSecurityCode').style.color="red";
}
}
} else if (response.status === "invalid_session") {
// handle invalid session details for example by giving the payer the possibility to retry with different card details. If the new details are correct, you can call the updateSession( ) method
} else {
// add system error handling here. Typically this would mean the integration is not working properly because there is no response from the client library.
// this could result in displaying a page to the payer to try again later and call support
}
};