- Pautas de integración
- Implementación de una integración de Batch
Implementación de una integración de Batch
Prerrequisitos
- Asegúrese de que el perfil del negocio está habilitado para el servicio de Batch.
- Antes de comenzar la integración, consulte Mejores prácticas y consejos.
Pasos de integración
Paso 1: Acceder al motor de pagos
Como primer paso, verifique su conectividad con el Mastercard Gateway.
Paso 2: Conocer sus campos de información
Antes de comenzar a crear la integración, debe prepararse con los valores para los campos que requieren su información.
Paso 3: Crear una solicitud de lote
Crear el cuerpo de la solicitud es un paso crítico en la integración.
Paso 4: Enviar una solicitud de lote
Hay muchos componentes para garantizar que el cuerpo de la solicitud de transacción se envíe de forma segura al Mastercard Gateway.
Paso 5: Recuperar el estado del lote
Una vez que se envía un lote, puede solicitar periódicamente el estado del lote para determinar el estado actual del procesamiento del lote.
Paso 6: Procesar la respuesta de lote
Una vez que un lote haya completado el procesamiento, puede solicitar un archivo de respuesta que contenga el resultado de cada una de las operaciones cargadas.
Paso 7: Probar e iniciar transacciones en producción
Las pruebas le permiten comprobar si su integración funciona como lo desea.
Solución de problemas y preguntas frecuentes
¿Puedo usar varios perfiles de negocio en una solicitud de lote único?
Sí, puede usar varios perfiles de negocio en una solicitud de lote único si puede asegurar que las credenciales de operación (identificador de negocio y contraseña de autenticación) para cada fila de operación son válidas para permitir una autenticación y autorización satisfactorias.
De manera predeterminada, las credenciales de operación para cada operación de un lote usarán las credenciales de autenticación suministradas en el encabezado de solicitud del lote (tanto identificador como contraseña de negocio). Puede optar por utilizar el mecanismo predeterminado o proporcionar credenciales de operación en cada fila del registro de operación. Con este último, la autenticación de la operación utilizará las credenciales del nivel de operación y no utilizará de forma predeterminada las credenciales de carga por lotes. Si las credenciales del nivel de operación son incorrectas, se rechazará la carga por lotes.
En el archivo de lote de muestra a continuación, las operaciones VOID usarán las credenciales de encabezado de solicitud de lote, ya que el identificador de negocio y la contraseña no se han proporcionado.
merchant,apiPassword,apiOperation,order.id,transaction.id,transaction.amount,transaction.currency, cardDetails.card.number, cardDetails.card.expiry.month,cardDetails.card.expiry.year,card.number,result,error.cause, error.explanation,response.gatewayCode TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104167,TXID1,30,AUD,5123456789012346,05,13,,,,, TESTMERCHANT,<TESTMERCHANT_API_PASSWORD>,PAY,921830104168,TXID1,30,AUD,5123456789012346,05,13,,,,, ,,VOID,1256378915689,TXID1,100,AUD,4987654321098769,05,13,,,,, ,,VOID,1256378915690,TXID1,100,AUD,4987654321098769,05,13,,,,, ,,VOID,1256378915691,TXID1,100,AUD,4987654321098769,05,13,,,,,
¿Cuáles son las posibles causas por las que falla el envío por lotes?
Un envío por lotes puede fallar debido a las siguientes condiciones de error.
| Escenario | Mensaje de error |
|---|---|
| Lote incompleto debido a que el resumen del mensaje SHA-1 no coincide | El envío del lote falló por uno de los siguientes motivos:
|
Nombre de lote duplicado
|
Error en el envío del lote: actualmente se está cargando un lote con este nombre, o ya se cargó un lote con el mismo nombre pero con un contenido diferente. Si el archivo ya se está cargando, espere a que finalice la carga. Si está utilizando un nombre de archivo que ya está en uso, cambie el nombre del archivo y envíelo nuevamente. |
Se devuelve un error de autenticación si no tiene privilegios suficientes para enviar lotes:
|
La autenticación falló: las credenciales proporcionadas en el registro <record number> son incorrectas. Esto se puede deber a:
|
| Se devuelve un error de autenticación si proporciona solo la contraseña pero no el ID del negocio en el nivel de operación. | La autenticación falló. En el registro <record number> del archivo por lotes se proporciona una contraseña pero no un ID de negocio. Agregue un ID de negocio o elimine la contraseña para usar las credenciales del negocio en el nivel de lote para este registro, luego intente enviar la solicitud nuevamente. |
| Se devuelve un error de autenticación si las credenciales del lote tienen un formato incorrecto. | Error de autenticación: las credenciales proporcionadas en el encabezado:
|
Se devuelve un error de autenticación si:
|
La autenticación falló: Las credenciales proporcionadas para el lote no son válidas. Corrija las credenciales e intente enviar la solicitud nuevamente. |
| Se devuelve un error de análisis si el encabezado contiene caracteres no válidos. | Error en el envío del lote: No se pudo analizar el lote porque el encabezado contenía un carácter no válido. Los caracteres permitidos son:
|
| Se devuelve un error de análisis si una fila de registro de operación contiene más valores de los definidos en el encabezado. | Error en el envío del lote: No se pudo analizar el lote porque el registro <record number> contenía más valores de los definidos en el encabezado. Corrija el lote y luego intente enviarlo nuevamente. |
| Se devuelve un error de análisis si se excede el tamaño máximo de campo individual o si se produce un error de análisis desconocido en un registro de operación. | Error en el envío del lote: No se pudo analizar el lote debido a un error en el registro <record number>. Asegúrese de que el lote cumpla con el formato de archivo y de que esté utilizando la codificación correcta, luego intente enviar el lote nuevamente. |
| Se devuelve un error de codificación si no se ha proporcionado ninguna codificación o si se ha proporcionado una codificación no compatible. | Solicitud fallida: La codificación proporcionada no es compatible. Las codificaciones admitidas son UTF-8 y LATIN1. Envíe la solicitud nuevamente utilizando una codificación compatible. |
| No se pudo encontrar el lote | Solicitud fallida: no se pudo encontrar ningún lote con este nombre. Corrija el nombre del lote y envíe la solicitud nuevamente. |
| Falló la verificación de longitud para la versión proporcionada. | Solicitud fallida: La versión proporcionada no es válida. Corrija la versión y envíe la solicitud nuevamente. |
| Falló la verificación de longitud para el nombre de lote proporcionado. | Solicitud fallida: El nombre del lote proporcionado no es válido. Corrija el nombre del lote y envíe la solicitud nuevamente. |
| Se produjo un error en la comprobación del ID de negocio proporcionado. | Solicitud fallida: el ID de negocio proporcionado no es válido. Corrija el ID de negocio y envíe la solicitud nuevamente. |
| Se produjo un error en el motor de pagos | La solicitud no se pudo enviar al motor de pagos debido a un error interno en el motor de pagos. Vuelva a intentarlo más tarde. |
El procesamiento de operaciones por Batch puede fallar debido a errores en las comunicaciones o los sistemas. Esto puede generar uno de los siguientes errores:
- Se produjo un error debido a una falla interna del sistema.
- Se produjo un error porque el servidor no tenía recursos suficientes para procesar la solicitud en ese momento.
- Se produjo un error al procesar una transacción de verificación Tokenization
Cuando esto ocurre y una operación se puede reintentar, Batch volverá a intentar enviar la operación para su procesamiento hasta que se reciba una respuesta no reintentable sobre la operación o se alcance el límite de reintentos.
Batch almacena los nombres de los lotes y su correspondiente código de integridad del mensaje (MIC) cargado por usted. Los lotes con un nombre de lote que se han enviado anteriormente pero con contenido diferente se pueden identificar y serán rechazados por Batch.
Los lotes con un mismo nombre y contenido que un lote enviado anteriormente también se pueden identificar y Batch devuelve el mismo estado que para el lote cargado antes. De manera que si el negocio sospecha que hubo un problema de transmisión, es capaz de verificar que el lote se cargó correctamente en Batch.
Los valores en la fila del encabezado de una solicitud por lotes enviada para su procesamiento solo pueden contener caracteres que se pueden encontrar en los nombres de los campos NVP de API. Se permiten los siguientes caracteres:
- Alfanumérico (a-z, A-Z, 0-9)
- Punto (.)
- Paréntesis cuadrados ([ ])
Batch rechaza un lote si se encuentran errores de análisis. El análisis incluye dividir el lote en filas y las filas en campos.
Puede ocurrir un error de análisis cuando:
- un registro de operación tiene más comas que las incluidas en el registro de encabezado;
- se ha sobrepasado el tamaño máximo del campo individual.
Primero debe corregir estos errores antes de enviar el lote para su procesamiento nuevamente.
Mejores prácticas y consejos
El servicio de Batch no garantiza que procesará las operaciones en el mismo orden según se especifica en el archivo de lote, porque el despachador del Batch puede procesar operaciones en paralelo. Este comportamiento también se puede atribuir a la función de reintento, es decir, si algunas operaciones en un archivo de lote deben reintentarse, entonces las operaciones que están listas se procesarán primero, independientemente del orden en el cual se especificaron. Por ejemplo, incluso si se especifican operaciones posteriores después de operaciones iniciales (Capture seguida de Authorization, Void seguida de Pay), entonces Capture se puede realizar antes que Authorization, o bien Void antes que Pay.
Por lo tanto, para las operaciones que deben seguir estrictamente un orden, se recomienda ejecutar primero el lote inicial de operaciones, esperar el archivo de respuesta del lote y, si tiene éxito, ejecutar el lote de operaciones posterior.
Tokenization almacena los detalles de las tarjetas en un token. Para usar Tokenization con Batch, debe usar el identificador de token en el archivo de lote, como se muestra a continuación.
apiOperation,cardDetails.card.number,cardDetails.card.expiry.month,cardDetails.card.expiry.year,cardDetails.card.securityCode,cardDetails.cardToken,transaction.amount,transaction.currency,transaction.id,transaction.authorizationCode,order.id,card.start.month,card.start.year,card.issueNumber,card.bankAccountType
AUTHORIZE,,,,,200,10,AUD,TXID1,,10323711802,,,,
AUTHORIZE,,,,,300,20,AUD,TXID1,,10323711803,,,,
AUTHORIZE,,,,,400,10,AUD,TXID1,,10323711804,,,,
AUTHORIZE,,,,,500,5.99,AUD,TXID1,,10323711805,,,,
Las credenciales de operación incluyen identificador y contraseña de negocio. Las credenciales de operación para cada operación de un lote se aplicarán de manera predeterminada a las credenciales de autenticación suministradas en el encabezado de solicitud del lote (tanto identificador como contraseña de negocio). Sin embargo, si especifica valores para ambos campos en las filas del registro de operación, la autenticación de la operación utilizará las credenciales del nivel de operación y no utilizará de forma predeterminada las credenciales del lote de carga.
Sí, puede procesar múltiples tipos de operaciones en un solo archivo por lotes siempre que NO estén relacionadas con el mismo pedido, es decir, que no contengan el mismo identificador de pedido. El servicio de Batch no garantiza que procesará las operaciones en el mismo orden según se especifica en el archivo de lote, porque el despachador del Batch puede procesar operaciones en paralelo. Este comportamiento también se puede atribuir a la función de reintento, es decir, si algunas operaciones en un archivo de lote deben reintentarse, entonces las operaciones que están listas se procesarán primero, independientemente del orden en el cual se especificaron. Por ejemplo, si las operaciones Pay y Void están en el mismo archivo de lote, Void puede realizarse primero que Pay. Sin embargo, si las operaciones NO están relacionadas con el mismo pedido, es decir, si contienen diferentes identificadores de pedido, entonces puede tener varios tipos de operaciones en un único archivo por lotes.
Sí, puede utilizar múltiples fuentes de detalles de la tarjeta en un único archivo por lotes, excepto el identificador de la sesión de pago. Para obtener información sobre múltiples fuentes, consulte Múltiples fuentes de detalles de tarjetas.
Las operaciones Authorize en el ejemplo siguiente utilizan tokens en lugar de detalles de la tarjeta.
apiOperation,order.id,transaction.id,transaction.amount,transaction.currency,cardDetails.card.number,cardDetails.card.expiry.month,cardDetails.card.expiry.year,card.number,cardDetails.cardToken,result,error.cause,error.explanation,response.gatewayCode
PAY,921830104167,TXID1,30,AUD,5123456789012346,05,13,,,,,,
PAY,921830104168,TXID1,50,AUD,5123456789012346,05,13,,,,,,
PAY,921830104169,TXID1,100,AUD,4987654321098769,05,13,,,,,,
AUTHORIZE,10072028281,TXID1,,,,,,,200,,,,,
AUTHORIZE,10072028282,TXID1,,,,,,,300,,,,,
AUTHORIZE,10072028283,TXID1,,,,,,,400,,,,,