- Pautas de integración
- Características soportadas (métodos de pago)
- Pagos de <<ach>>
<<ach>>
<<ach>> es una red electrónica para procesar lotes de transacciones de débito y crédito entre instituciones financieras en EE. UU. Está administrada por la National Clearing House Association (NACHA).
La red se puede usar para la transferencia electrónica de fondos entre cuentas. Se usa para Pago directo a través de <<ach>> (por ejemplo, pagos recurrentes de hipoteca o bien una compra en línea de algún consumidor) y Depósito directo a través de <<ach>> (por ejemplo, pagos de nómina, un reembolso realizado para una compra en línea o bien un pago B2B).
El motor de pagos le permite procesar Pagos directos (pagos) y Depósitos directos (reembolsos) a través de <<ach>>.
En esta página se describen los requisitos para procesar pagos de <<ach>> a través del QNB ALAHLI y se proporciona información general del flujo de pagos y detalles acerca de operaciones compatibles de <<webServicesIntegration>> para pagos de <<ach>>.
Prerrequisitos
Usted debe tener una cuenta de <<ach>> configurada con un adquirente de <<ach>>.
- Para que se pueda llevar a cabo una liquidación de <<ach>>, se debe obtener autorización explícita del cliente.
- Dado que <<ach>> no es una red en tiempo real, las devoluciones aún pueden tener lugar después de enviada la solicitud de pago al QNB ALAHLI.
- Debe respetar los reglamentos de NACHA. El incumplimiento puede acarrear sanciones considerables. Para mantenerse al día con los reglamentos actuales, visite https://www.nacha.org/
- Debe establecer, implementar y actualizar políticas, procedimientos y sistemas relacionados con la iniciación, el procesamiento y el almacenamiento de entradas, a fin de:
- Garantizar la confidencialidad de la información.
- Proteger contra amenazas a la seguridad de la información.
- Proteger contra el uso no autorizado de la información.
Flujo de datos de <<ach>>
- El pagador autoriza el pago o el depósito.
Los Códigos de entrada estándar (SEC) permitidos por NACHA son:
TEL. Entrada iniciada por teléfono.WEB. Entrada iniciada por web.PPD. Pago y depósitos preorganizados.
- El negocio envía una solicitud de transacción al QNB ALAHLI.
Las solicitudes pueden ser
PAY,REFUNDoVOID. - QNB ALAHLI emite una respuesta que contiene información de estado (por ejemplo,
APPROVED_PENDING_SETTLEMENT).La transacción se agrega al lote actual para liquidación.
El lote de transacciones se puede cerrar de dos maneras:
- Una vez al día a la hora configurada.
- Usted cierra el lote abierto actualmente al enviar una solicitud <<webServicesIntegration>>
CLOSE_BATCH. Cualquier otra transacción posterior se agregará a un lote nuevo.
Al final del día, todos los lotes cerrados que aún no se han enviado se recopilan en un archivo de liquidación y se transmiten al adquirente <<ach>>.
- La primera adquirente <<ach>> emite una respuesta inmediata, que contiene el resultado de la validación de los datos transmitidos (por ejemplo,
APPROVEDoDECLINED) y envía las solicitudes de pago a la red de <<ach>> para su procesamiento.Notas:
- Un estado
APPROVEDemitido por el adquirente <<ach>> simplemente implica la aceptación validada de la transmisión para procesamiento posterior; no una aprobación real de la transacción financiera. - Para que se le notifique de la respuesta del adquirente de <<ach>>, suscríbase a Notificaciones de webhook.
- Un estado
- La red de <<ach>> administra las transacciones de pago entre las instituciones financieras aplicables.
- Después de un retraso de hasta 3 días, la red de <<ach>> envía un reporte de excepción de solicitudes de pago aprobadas al adquirente de <<ach>>, quien se lo proporcionará a usted.
Integración de pagos de <<ach>>
Hay tres opciones para integrar pagos de <<ach>> a su página de pago:
Si tiene una integración actual de <<checkout>>, puede usar <<checkout>> para verificar los detalles de pago de <<ach>>.
Puede hacerlo al configurar interaction.operation=VERIFY en la sesión Create Checkout Session. <<checkout>> muestra los pagos de <<ach>> como una opción de pago para el pagador. Los datos ingresados por el pagador se comprueban mediante los métodos de verificación admitidos por el adquirente configurado.
Usted puede determinar si la operación de verificación se realizó correctamente o no al comparar resultIndicator con successIndicator. Si la interacción no se realizó correctamente, <<checkout>> muestra un mensaje donde se indica que la verificación no pudo realizarse y se solicita que el pagador vuelva a intentarlo.
Si tiene su propia página de pago, entonces puede elegir que la opción de integración Hosted Session haga que el QNB ALAHLI capte de manera segura los detalles de pago de <<ach>> y los almacene en una sesión de pago.
<html>
<head>
<!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
<script src="https://qnbalahli.test.gateway.mastercard.com/form/version/72/merchant/<MERCHANTID>/session.js"></script>
<!-- APPLY CLICK-JACKING STYLING AND HIDE CONTENTS OF THE PAGE -->
<style id="antiClickjack">body{display:none !important;}</style>
</head>
<body>
<!-- CREATE THE HTML FOR THE PAYMENT PAGE -->
<div>Please enter your Automated Clearing House details:</div>
<div>
<label class="control-label" id="ach-account-type-label">Account Type:</label>
<select class="form-control col-sm-6" name="ach-account-type" id="ach-account-type">
<option value="CONSUMER_SAVINGS">Consumer Savings Account</option>
<option value="CONSUMER_CHECKING" selected>Consumer Checking Account</option>
<option value="CORPORATE_CHECKING">Business Checking Account</option>
</select>
</div>
<div>Bank Account Holder: <input type="text" id="ach-account-holder" class="input-field" value="" readonly></div>
<div>Bank Account Number:<input type="text" id="ach-account-number" class="input-field" value="" readonly></div>
<div>Routing Number:<input type="text" id="ach-routing-number" class="input-field" value="" readonly></div>
<div><button id="payButton" onclick="pay();">Pay Now</button></div>
<!-- JAVASCRIPT FRAME-BREAKER CODE TO PROVIDE PROTECTION AGAINST IFRAME CLICK-JACKING -->
<script type="text/javascript">
if (self === top) {
var antiClickjack = document.getElementById("antiClickjack");
antiClickjack.parentNode.removeChild(antiClickjack);
} else {
top.location = self.location;
}
PaymentSession.configure({
fields: {
// ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR ACH
ach: {
accountType: "#ach-account-type",
bankAccountHolder: "#ach-account-holder",
bankAccountNumber: "#ach-account-number",
routingNumber: "#ach-routing-number"
}
},
//SPECIFY YOUR MITIGATION OPTION HERE
frameEmbeddingMitigation: ["javascript"],
callbacks: {
initialized: function(response) {
// HANDLE INITIALIZATION RESPONSE
},
formSessionUpdate: function(response) {
// HANDLE RESPONSE FOR UPDATE SESSION
if (response.status) {
if ("ok" == response.status) {
console.log("Session updated with data: " + response.session.id);
} else if ("fields_in_error" == response.status) {
console.log("Session update failed with field errors.");
if (response.errors.bankAccountHolder) {
console.log("Bank account holder invalid.");
}
if (response.errors.bankAccountNummber) {
console.log("Bank account number invalid.");
}
if (response.errors.routingNumber) {
console.log("Routing number invalid.");
}
} else if ("request_timeout" == response.status) {
console.log("Session update failed with request timeout: " + response.errors.message);
} else if ("system_error" == response.status) {
console.log("Session update failed with system error: " + response.errors.message);
}
} else {
console.log("Session update failed: " + response);
}
}
}
});
function pay() {
// UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS
PaymentSession.updateSessionFromForm('ach');
}
</script>
</body>
</html>
- Incluya la biblioteca JavaScript cliente
session.jshospedada por el motor de pagos en su página de pago. La ruta a este campo incluye tanto la versión de la API como el identificador del negocio para la sesión. - Cree el HTML para la página de pago que contiene los campos de pago de <<ach>>.
Para evitar el envío de datos confidenciales al servidor, asegúrese de que estos campos sean dereadonlyy NO tengan el atributoname. - Invoque la función
PaymentSession.configure(configuration).
El objeto
configurationle permite adosar campos hospedado a su página de pago. Debe proporcionar lo siguiente:
- session(optional), si no proporciona una, la biblioteca de cliente crea una sesión de pago.
- selectores de campo para los campos de pago de <<ach>>, los cuales (cuando se proporcionan) se reemplazan con campos proxy correspondientes incrustados en iFrames hospedados por el QNB ALAHLI. Los campos proxy tendrán la misma apariencia que los campos reemplazados.
-
El clickjacking, también conocido como "ataque de rectificación de UI", se produce cuando un atacante usa varias capas transparentes u opacas para engañar al usuario y lograr que haga clic en un botón o vínculo en otra página cuando intenta hacer clic en la página del primer nivel. Para usar Hosted Session, debe implementar una o más de las siguientes defensas contra ataques de clickjacking.
Opción de mitigación de marcos Implementación javascriptIncluya el JavaScript "separador de marcos" en su página de pago. x-frame-optionsSu servidor debe devolver un encabezado de respuesta HTTP de opciones X-Frame. cspSu servidor debe devolver un encabezado de respuesta HTTP de contenido-seguridad-política que contenga una directiva de antecesores de marcos. Debe especificar qué defensas se implementan a través del parámetro
frameEmbeddingMitigationen la llamada dePaymentSession.configure(configuration). Para obtener información sobre cómo defenderse contra ataques de clickjacking, consulte Referencia de defensa contra clickjacking en el sitio web externo OWASP. -
initialized( ): se invoca cuando los campos hospedados se adjuntan a su página de pago.formSessionUpdate( ): se invoca en respuesta a la funciónPaymentSession.updateSessionFromForm('ach')(consulte el paso siguiente).
- Invoque
PaymentSession.updateSessionFromForm('ach')para almacenar los detalles de <<ach>> en una sesión de pago. Una vez finalizada la operación, la devolución de llamadaformSessionUpdate( )se invoca con un parámetro de resultado. Debe comprobar el valorresult.statuspara determinar si la operación fue correcta. Consulte Administrar respuestas de devolución de llamada. - Puede usar la sesión de pago devuelta (session.id) para realizar una tokenización o una transacción de pago cuando se requiere. Para obtener más información, consulte Realizar una operación con la sesión.
Referencia de session.js[JavaScript]
Puede enviar detalles de pago de <<ach>> directamente al QNB ALAHLI mediante las siguientes operaciones.
Usted inicia un pago de <<ach>> al enviar una solicitud de <<webServicesIntegration>>PAY y un reembolso al enviar una solicitud de <<webServicesIntegration>>REFUND.
Asegúrese de incluir la información siguiente en su solicitud:
sourceOfFunds.type = ACH.sourceOfFunds.provided.ach.routingNumber: el número de direccionamiento del banco del pagador.sourceOfFunds.provided.ach.bankAccountNumber: el número de cuenta del banco del pagador.sourceOfFunds.provided.ach.bankAccountHolder: el nombre del titular de la cuenta del pagador.sourceOfFunds.provided.ach.accountType: el tipo de cuenta del banco del pagador.sourceOfFunds.provided.ach.secCode: el código SEC para el pago de <<ach>> aplicable a esta transacción.El código SEC debe ser una de las siguientes opciones:
TEL: una entrada de Débito de <<ach>> para un pago de B2C autorizado por el cliente a través del teléfono. TEL solo se puede usar cuando una relación ya existe entre usted y el pagador o, cuando no hay una relación existente, el pagador inicia el contacto con usted.WEB: una entrada de Débito de <<ach>> para un pago de B2C autorizado a través de Internet o una red inalámbrica.PPD: una entrada de Débito o Crédito de <<ach>> basada en una autorización autenticada proporcionada por el pagador. PPD se usa para pagos de B2C (por ejemplo, nómina de empleados, pagos de hipoteca o reembolso de ganancias).
Puede anular la transacción anterior o un pedido al enviar una solicitud de <<webServicesIntegration>>VOID para el pedido con el parámetro de ID de transacción objetivo que hace referencia a la solicitud de PAY o REFUND.
Para una solicitud exitosa de <<webServicesIntegration>>VOID la transacción objetivo a la que se ha hecho referencia se elimina del lote y, por tanto, no se enviará al adquirente de <<ach>>.
Las transacciones ya no se pueden anular una vez que el lote que contiene la transacción objetivo a que se ha hecho referencia se ha cerrado para liquidación (por ejemplo, la liquidación está en progreso) o bien ya se ha liquidado.
Puede verificar los detalles de pago para un pago de <<ach>> al enviar una solicitud de <<webServicesIntegration>>VERIFY.
Actualmente, el QNB ALAHLI solo admite la verificación semántica de los detalles de pago de ACH, pero no verifica que la cuenta sea una cuenta bancaria válida y que el banco participe en <<ach>>.
Gestión y liquidación de lotes.
Puede controlar el cierre del lote al enviar una solicitud de <<webServicesIntegration>>CLOSE_BATCH con el ID de adquirente para su adquirente de <<ach>>. El ID del adquirente se proporcionó en transaction.acquirer.id, en la respuesta de transacción.
Como resultado, el actual lote del Adquirente de <<ach>> en el QNB ALAHLI se cerrará. Las transacciones de <<ach>> posteriores se agregarán a un lote interno del QNB ALAHLI nuevo.
Conciliación
La respuesta de la operación Retrieve Transaction para transacciones de <<ach>> exitosas contiene el identificador para la transacción que el adquirente usa en transaction.receipt.
Este identificador se usará en el Reporte detallado de excepción proporcionado por el adquirente de <<ach>> de Paymentech Salem. Este contiene todas las transacciones de <<ach>> fallidas y puede usarse para conciliar sus pagos.
El estado de transacción proporcionado por el motor de pagos (response.gatewayCode) no se actualiza con la respuesta real de la red de <<ach>>.
Prueba de transacciones de <<ach>>
Puede probar su integración mediante su perfil de pruebas del negocio.
El QNB ALAHLI proporciona un emulador que devolverá una respuesta con response.gatewayCode=APPROVED para todas las solicitudes válidas para los pagos de <<ach>>.