Integración de Click to Pay en Hosted Session
Utilice los siguientes pasos para agregar Click to Pay (C2P) a su Hosted Session integración mediante el SDK Click to Pay y la API de JavaScript (JS). Puede encontrar un ejemplo HTML de una integración básica al final de este tema.
Para obtener más información sobre C2P, las pruebas para la integración completa y algunas preguntas frecuentes, consulte Click to Pay.
Paso 1: Crear y actualizar una sesión
Crear una sesión mediante la operación CREATE SESSION. La respuesta devuelve un ID de sesión que debe utilizar en los pasos siguientes para hacer referencia a la sesión.
Puede agregar o actualizar campos en una sesión existente usando la operación UPDATE SESSION. Al menos los siguientes campos son obligatorios en una sesión:
session.id
Identificador de la sesión de pago.order.amount
Monto total del pedido.order.currency
Moneda del pedido.
CREATE SESSION y UPDATE SESSION son operaciones API del lado del servidor que son un requisito previo para la integración con la API de JS. Utilice WS API v62 o superior con JS API.
Para ver ejemplos de solicitudes de operaciones API del lado del servidor, descargue la colección de Postman.
Paso 2: Incluir el API de JavaScript de Click to Pay en su página de pago
Incluya el SDK de JavaScript para C2P (click-to-pay.js) proporcionado por Mastercard Gateway en su página de pago agregando un elemento de script dentro del elemento head en su código HTML. Esto coloca un objeto ClickToPay en el espacio de nombres de la ventana.
<script type="text/javascript" src="https://ap-gateway.mastercard.com/form/static/click-to-pay/click-to-pay.min.js"></script>
Paso 3: Configurar la interacción de Click to Pay
El objeto de configuración le permite configurar la interacción entre el pagador y C2P en su página de pago. Cuando el pagador esté listo para pagar su pedido y usted esté cargando su página de pago, inicie la interacción C2P invocando la función ClickToPay.configure(). Para obtener detalles adicionales y un ejemplo de la función, consulte la Referencia de API.
La biblioteca C2P puede tardar unos segundos en inicializarse. Inicialice los componentes lo antes posible durante la carga de la página para que el pagador pueda finalizar la compra rápidamente utilizando C2P.
En la función ClickToPay.configure(), configure los parámetros, los componentes de la página de pago y las devoluciones de llamada para la interacción de C2P, como se define en las siguientes secciones.
Parámetros de configuración
Utilice los parámetros para definir los detalles de su interacción C2P.
Tabla: Parámetros de configuración
| Campo | Obligatorio | Tipo | Descripción |
|---|---|---|---|
merchant.id |
Sí | Cadena | Su ID de negocio, utilizado por el motor de pagos para determinar sus opciones de pago. |
merchant.name |
Sí | Cadena | Su nombre comercial, por ejemplo, el nombre conocido por su pagador. |
merchant.url |
Obligatorio | Cadena URL | URL de su sitio web que el pagador está utilizando. |
session.id |
Sí | Cadena | ID de sesión devuelto por la operación CREATE SESSION en el Paso 1. |
session.wsVersion |
Sí | int | Versión de la API de WS utilizada al enviar la operación CREATE SESSION en el Paso 1. El valor debe ser >= 62. |
order.amount |
Sí | Cadena | Monto del pedido. El valor se utiliza únicamente para visualización y no para procesar el pago. |
order.currency |
Sí | Cadena | Moneda del pedido. El valor se utiliza únicamente para visualización y no para procesar el pago. |
interaction.billingPreference |
No | Cadena de enumeración | Si se recopila una dirección de facturación durante la interacción C2P. Los valores posibles son:
|
interation.collectShippingAddress |
No | Booleano | Si se recopila una dirección de envío durante la interacción C2P. El valor predeterminado es false. De forma predeterminada, el pagador puede seleccionar cualquier país para la dirección de envío. Para restringir la lista de países a los que envía mercancías, debe configurar su perfil del negocio para C2P por medio de Merchant Administration (MA) con una lista de países permitidos o una lista de países excluidos. Si ha definido alguna restricción, el pagador solo puede seleccionar un país de dirección de envío permitido. No puede anular los países admitidos de direcciones de envío para una solicitud específica, solo para todas las solicitudes dentro de su perfil del negocio. |
interation.locale |
No | Cadena | Lenguaje utilizado durante la interacción C2P. De forma predeterminada, se utiliza el idioma configurado en el explorador del pagador. Si no se puede determinar el idioma del pagador o no se admite, se utiliza en_US a menos que proporcione un valor diferente en este parámetro.
|
interation.country |
No | Cadena | Contenido específico del país, como Términos y condiciones, presentado al pagador durante la interacción C2P. El valor que configuró con respecto a su perfil del negocio en el motor de pagos se utiliza de forma predeterminada. Si desea anular este valor para esta interacción, establezca este parámetro en un valor de país ISO 3166 alfa-3 válido. |
interaction.cardSelectionAction |
No | Cadena | Acción que se debe realizar cuando el pagador realiza la selección de tarjeta. Los valores posibles son:
|
interaction.skipDCFInteraction |
No | Booleano | Si el pagador debe confirmar manualmente su dirección de correo electrónico y número de teléfono. Esto solo se aplica a la inscripción de la tarjeta Mastercard en este momento. Los parámetros customer.email y customer.mobilePhone son necesarios dentro de la función configure() para que esta característica surta efecto.Si se configura como true, al pagador no se le solicita un mensaje de Confirmar en el componente DCF (interfaz de usuario del facilitador de tarjetas digitales) y aparece una breve pantalla de carga. Si no se proporciona, el valor se configura de manera predeterminada en "false". |
customer.email |
Sí | Cadena | Correo electrónico del pagador. C2P utiliza el valor para buscar el perfil del pagador dentro del sistema SRC (Secure Remote Commerce). La búsqueda de correo electrónico se inicia solo si no se reconoce el dispositivo. Si se reconoce el dispositivo, este campo se ignora. Incluya información en su sitio que indique que el correo electrónico del pagador se usa con fines de búsqueda, a menos que ya haya informado al pagador que su dirección de correo electrónico se usa para buscar su perfil de C2P. Puede incluir un aviso informando que se asocia con esquemas de tarjetas participantes para ofrecer C2P para un pago más rápido y que la dirección de correo electrónico del pagador se comparte de forma segura con esquemas de tarjetas participantes para verificar si ya tienen un perfil C2P. |
customer.mobilePhone |
No | Número de teléfono | Número de teléfono móvil o celular del pagador en formato ITU-T E123, por ejemplo +1 607 1234 5678 El número consta de:
|
customer.firstName |
No | Cadena | Nombre del pagador. |
customer.lastName |
No | Cadena | Apellido del pagador. |
srcDCFCancel |
Sí (solo si tiene la intención de admitir tarjetas Visa) | - | El diseño actual de Visa para C2P cierra su sesión C2P si el pagador selecciona la "X" que se muestra en la esquina superior derecha del componente Visa DCF. Cuando se envía este evento, se recomienda reinicializar C2P (llamar a la función configure()) para garantizar sesiones abiertas para todos los esquemas de tarjetas. |
Componentes de la página de pago
C2P proporciona varios componentes que pueden integrarse en su página de pago para mejorar la interacción C2P. Cree elementos div en la ubicación de su página de pago donde desea que se muestren estos componentes e identifique los elementos div dentro de la sección de elementos del objeto de configuración.
Tabla: Componentes disponibles de la página de pago
| Campo | Obligatorio | Descripción |
|---|---|---|
cardList |
Sí | ID del elemento DOM donde se muestra el componente Lista de tarjetas. |
otp |
No | ID del elemento DOM donde se muestra el componente Contraseña de un solo uso (OTP). Si no se proporciona, la OTP se muestra como una superposición. |
dcf |
Sí | ID del elemento DOM donde se muestra el componente DCF. Si no se proporciona, el componente DCF se muestra como una superposición. |
Devoluciones de llamada
Debe definir las acciones que se invocarán durante la interacción C2P como devoluciones de llamada.
Devolución de llamada de onStateChange
El flujo inicial se determina después de llamar a la función configure():
- Si se detecta una cookie C2P válida, se utiliza el flujo "Usuario que regresa con cookie" y se muestra el componente de lista de tarjetas.
- Si se detecta un correo electrónico C2P válido, se utiliza el flujo "Usuario que regresa con correo electrónico" y se solicita al pagador una OTP antes de que se muestre el componente de la lista de tarjetas.
- Si no se detecta ninguna cookie o correo electrónico válido, se utiliza el flujo de "Nuevo usuario".
La devolución de llamada onStateChange se activa cuando cambia el estado de interacción de C2P. Puede usarlo para determinar qué componentes son visibles y en qué etapa se encuentra el pagador dentro del flujo.
Ejemplo de objeto de devolución de llamada onStateChange
oldState : {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email if not supplied in customer.email
},
elementState: {
cardList: {selector: 'cardListContainer', visible: true},
otp: {selector:'otpContainer', visible: false},
dcf: {selector:'dcfContainer', visible: false}
}
},
newState: {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: 'cardListContainer', visible: false},
otp: {selector:'otpContainer', visible: false},
dcf: {selector:'dcfContainer', visible: true}
}
},
diffState: {
elementState: {
dcf: {selector:'dcfContainer', visible: true}
}
}
La siguiente tabla proporciona ejemplos de cómo gestionar los cambios de estado con los diferentes flujos.
Tabla: Cambios de estados
| Estado | Valor de campo Estado anterior | Valor de campo Estado nuevo | Comentarios |
|---|---|---|---|
| Carga de página (antes de que se muestre cardList) después de isRecognized y antes de que se muestre cardList | {} | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
- |
| Después de hacer clic en la tarjeta y antes de redirigir a DCF | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
{
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
} |
- |
| Después de completar el pago | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
} |
{
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
} |
La devolución de llamada onComplete devuelve correlationId, esquema, digitalCardId. Vaya al paso 6 |
Usuario recurrente con flujo de cookies
| Estado | Valor de campo Estado anterior | Valor de campo Estado nuevo | Comentarios |
|---|---|---|---|
Carga de página después de isRecognized() y antes de que se muestre la lista de tarjetas |
{} | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
- |
| Después de hacer clic en una tarjeta y antes de redirigir al componente DCF | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
{
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
- |
| Después de completar el pago | {
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
{
payerState: {
deviceRecognized: true,
email: ‘payer@test.com’, //masked email
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
La devolución de llamada onComplete devuelve el ID de correlación, el esquema y el ID de la tarjeta digital. Continúe desde el paso 6. |
| Después de ingresar una OTP válida | {
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: true},
dcf: {selector:'#dcfContainer', visible: false}
}
}
} |
{
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
- |
| Después de hacer clic en una tarjeta antes de redirigir al componente DCF | {
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: true},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
{
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
- |
| Después de completar el pago | {
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
{
payerState: {
email: ‘payer@test.com’,
emailEnrolled: true,
emailVerified: true
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
La devolución de llamada onComplete devuelve el ID de correlación, el esquema y el ID de la tarjeta digital. Continúe desde el paso 6. |
| Carga de página con correo electrónico | {
} |
{
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrolled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
Dado que no se reconoce el perfil C2P del pagador, puede mostrar los campos de entrada de la tarjeta, recopilar los detalles del pagador y actualizar la sesión. El correo electrónico está en blanco si no se proporciona dentro de los parámetros de configuración. |
Llame a la función checkoutWithNewCard() antes de que se muestre el componente DCF |
{
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrolled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
{
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrolled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
- |
| Después de completar el pago | {
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrollled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: true}
}
}
|
{
payerState: {
deviceRecognized: false,
email: ‘payer@test.com’,
emailEnrollled: false,
emailVerified: false
},
elementState: {
cardList: {selector: '#cardListContainer', visible: false},
otp: {selector:'#otpContainer', visible: false},
dcf: {selector:'#dcfContainer', visible: false}
}
}
|
La devolución de llamada onComplete devuelve el ID de correlación, el esquema y el ID de la tarjeta digital. Continúe desde el paso 6. |
Devolución de llamada onComplete
La devolución de llamada onComplete se activa cuando el pagador ha completado la interacción con el componente DCF.
Esta función utiliza dos argumentos:
scheme: esquema de tarjeta- correlationId: identificador único para la interacción C2P (para este esquema)
Estos detalles deben usarse en el paso 6 para recuperar los detalles de pago para esta interacción C2P.
Devolución de llamada onError
La devolución de llamada onError devuelve un objeto de error si se produce un error durante la interacción de C2P. Contiene dos campos:
{
errorCode: 'INVALID_INPUT',
errorMessage: 'session id is required'
}
Tabla: Códigos de error de integración
| Código de error | Mensaje de error | Su acción |
|---|---|---|
CALLBACKS_ONCOMPLETE_ERROR |
Falta un argumento: la devolución de llamada onComplete es obligatoria | Incluya la función de devolución de llamada onComplete en la función configure(). |
CALLBACKS_ONERROR_ERROR |
Falta un argumento: la devolución de llamada onError es obligatoria | Incluya el método de devolución de llamada onError en la función configure(). |
MERCHANT_ID_ERROR |
Falta un argumento: el D de negocio es obligatorio | Incluya el campo merchant.id en la función configure(). |
MERCHANT_NAME_ERROR |
Falta un argumento: el nombre del negocio es obligatorio | Incluya el campo merchant.name en la función configure(). |
MERCHANT_URL_ERROR |
Falta un argumento: la URL del negocio es obligatoria | Incluya el campo merchant.url en la función configure(). |
SESSION_ID_ERROR |
Falta un argumento: el ID de sesión es obligatorio | Incluya el campo session.id en la función configure(). |
MISSING_API_VERSION_ERROR |
Falta un argumento: la versión de la API es obligatoria | Incluya el campo wsVersion en la función configure(). |
ORDER_AMOUNT_ERROR |
Falta un argumento: el monto del pedido es obligatorio | Incluya el campo order.amount en la función configure(). |
ORDER_CURRENCY_ERROR |
Falta un argumento: la moneda del pedido es obligatoria | Incluya el campo order.currency en la función configure(). |
MIN_API_VERSION_ERROR |
La versión de la API debe ser mayor o igual a 62 | Cambie el valor del campo wsVersion a al menos 62, todas las operaciones deben realizarse con 62 o superior. |
CARD_LIST_ERROR |
Falta un argumento: elements.cardList es obligatorio | Incluya el campo elements.cardList que se vincula con el div del componente de lista de tarjetas. |
DCF_ERROR |
Falta un argumento: elements.dcf es obligatorio | Incluya el campo elements.dcf que se vincula con el div del componente de lista de tarjetas. |
MISSING_EMAIL_ERROR |
Falta un argumento: el correo electrónico es obligatorio | Incluya el campo customer.email en la función configure(). |
CUSTOMER_EMAIL_ERROR |
Error de formato de correo electrónico del cliente | Asegúrese de que su sitio solo acepte direcciones de correo electrónico válidas del pagador. |
INTERACTION_LOCALE_ERROR |
Error de formato de configuración regional de interacción | Proporcione una configuración regional válida utilizando el formato <language>_<country>, como en_US. |
INTERACTION_COUNTRY_ERROR |
Error de formato de país de interacción | Proporcione un valor de país ISO 3166 alfa-3 válido en el campo interaction.country. |
Tabla: Códigos de error de pago
| Código de error | Mensaje de error | Acción necesaria |
|---|---|---|
CARD_MISSING |
Se requería el ID de la tarjeta digital o el objeto de la tarjeta cifrada, pero falta. | C2P no está disponible, vuelva al flujo de pago para usuarios invitados. |
CARD_ADD_FAILED |
No se puede agregar la tarjeta cuando se ejecuta el flujo combinado | C2P no está disponible, vuelva al flujo de pago para usuarios invitados. |
CARD_SECURITY_CODE_MISSING |
La seguridad de la tarjeta debe proporcionarse cuando se ejecuta el flujo combinado. | Asegúrese de que el campo cardSecurityCode en la función ClickToPay.checkoutWithNewCard() contenga un valor de 3 dígitos (o 4 dígitos para Amex). |
CARD_INVALID |
Número de tarjeta no válido cuando se ejecuta el flujo combinado. | Asegúrese de que el campo primaryAccountNumber en la función ClickToPay.checkoutWithNewCard() sea una tarjeta válida. |
CARD_NOT_RECOGNIZED |
La tarjeta especificada no fue reconocida. | Asegúrese de que el campo primaryAccountNumber en la función ClickToPay.checkoutWithNewCard() sea una tarjeta válida. |
CARD_EXP_INVALID |
Fecha de vencimiento de la tarjeta no válida. | Asegúrese de que los campos panExpirationYear y panExpirationMonth en la función ClickToPay.checkoutWithNewCard() sean válidos. |
MERCHANT_DATA_INVALID |
Los datos del negocio no son válidos | C2P no está disponible, vuelva al flujo de pago para usuarios invitados. |
UNABLE_TO_CONNECT |
No se puede conectar a / iniciar DCF. | C2P no está disponible, vuelva al flujo de pago para usuarios invitados. |
AUTH_INVALID |
Token de identificación federado no válido. | C2P no está disponible, vuelva al flujo de pago para usuarios invitados. |
Códigos de error C2P estándar
| Código de error | Mensaje de error | Acción necesaria |
|---|---|---|
REQUEST_TIMEOUT |
La solicitud tardó más del tiempo permitido en completarse. Esto podría significar que el servicio está experimentando un alto volumen de llamadas. Debería intentarlo de nuevo más tarde. También puede deberse a que el SDK no puede comunicarse con su iframe. | C2P no está disponible, vuelva al flujo de pago para usuarios invitados. |
SERVER_ERROR |
Esto indica que el servidor encontró una condición inesperada que le impidió cumplir con la solicitud. | C2P no está disponible, vuelva al flujo de pago para usuarios invitados. |
INVALID_PARAMETER |
El valor proporcionado para uno o más parámetros de solicitud se considera no válido. Este error también se genera cuando falta un campo obligatorio. Nota: Siempre que sea posible, debe proporcionar validación del lado del cliente para evitar un viaje de ida y vuelta innecesario al servidor. Las restricciones de validación simples están documentadas como parte de la especificación API. | C2P no está disponible, vuelva al flujo de pago para usuarios invitados. |
INVALID_REQUEST |
El servidor no pudo entender la solicitud. Por lo general, esto significa que un campo de datos debe estar en un formato particular, pero no lo está. Por ejemplo, la decodificación base64 puede haber fallado. El campo de mensaje puede proporcionar aclaraciones adicionales sobre qué parte/campo de la solicitud se considera incorrecto. | C2P no está disponible, vuelva al flujo de pago para usuarios invitados. |
AUTH_ERROR |
El servidor entiende la solicitud, pero no puede autenticarse. | C2P no está disponible, vuelva al flujo de pago para usuarios invitados. |
NOT_FOUND |
El recurso/la entidad comercial solicitada no existe. El recurso también podría estar oculto por motivos de seguridad. | C2P no está disponible, vuelva al flujo de pago para usuarios invitados. |
TERMS_AND_CONDITIONS_NOT_ACCEPTED |
Términos y condiciones no aceptados. | Vuelva al flujo de pago para usuarios invitados. |
IS_CONFIGURED_ERROR |
configure() no se completó. La configuración debe inicializarse primero. | Asegúrese de que su integración haya llamado a la función configure(). Asegúrese de dejar tiempo suficiente para que se complete la función antes de hacer visibles los componentes C2P. |
SRCI_ID_MISSING |
Falta el identificador del iniciador SRC. | C2P no está disponible, vuelva al flujo de pago para usuarios invitados. |
DPA_ID_MISSING |
Falta el identificador del DPA | C2P no está disponible, vuelva al flujo de pago para usuarios invitados. |
SRCI_TXID_MISSING |
Falta el identificador de transacción del iniciador SRC. | C2P no está disponible, vuelva al flujo de pago para usuarios invitados. |
DPA_TXOPT_MISSING |
Falta la estructura de opciones de transacción de DPA. | C2P no está disponible, vuelva al flujo de pago para usuarios invitados. |
INVALID_STATE |
La cuenta existe pero no está en estado "activo" para este programa. | Vuelva al flujo de pago para usuarios invitados. |
CONSUMER_ID_MISSING |
La identidad del consumidor era obligatoria, pero no se proporcionó. | Vuelva al flujo de pago para usuarios invitados. |
FRAUD |
La cuenta de usuario fue bloqueada o deshabilitada. | Vuelva al flujo de pago para usuarios invitados. |
ID_FORMAT_UNSUPPORTED |
ID de sesión no válido | C2P no está disponible, vuelva al flujo de pago para usuarios invitados. |
Retraso del OTP para usuarios recurrentes reconocidos por correo electrónico (opcional)
Si C2P reconoce al pagador según su correo electrónico, el comportamiento predeterminado es mostrar automáticamente la OTP proporcionada por C2P.
Si, por algún motivo, desea iniciar la interacción de C2P pero suprimir la OTP proporcionada por C2P hasta una ocasión posterior (mientras muestra pantallas adicionales al pagador antes de continuar), agregue el campo interaction.suppressPayerInteraction en la función ClickToPay.configure().
Si configura el campo interaction.suppressPayerInteraction en true, la función configure() configura la interacción C2P y verifica si el pagador es reconocido mediante su correo electrónico o una cookie o si es un usuario nuevo. Sin embargo, la función no activa la interacción C2P con el pagador (muestra cualquier componente relacionado).
Si el campo se omite o se establece en false, la función configure() configura la interacción de C2P, verifica si el pagador se reconoce mediante su correo electrónico o una cookie o si es un usuario nuevo, y desencadena inmediatamente la interacción de C2P con el pagador.
Si el campo interaction.suppressPayerInteraction está configurado en true, debe realizar las siguientes acciones según el estado de reconocimiento del pagador. Si el pagador es:
- Reconocido según su correo electrónico (
emailEnrolled = trueyemailVerified = false), la aplicación del negocio puede implementar pasos adicionales dentro de su flujo antes de iniciar la verificación OTP de C2P. Luego, debe llamar a la funciónClickToPay.initiatePayerInteraction()para mostrar la OTP al pagador. - No reconocido según su correo electrónico (es un usuario nuevo o se reconoce mediante una cookie), la aplicación del negocio debe llamar a la función
initiatePayerInteraction()inmediatamente.
Paso 4: Actualizar los cambios de dirección de correo electrónico
Si el pagador puede cambiar su dirección de correo electrónico en la misma página que muestra los componentes de C2P, cualquier cambio en la dirección de correo electrónico del pagador debe enviarse al SDK de C2P. Cada vez que el pagador actualice su dirección de correo electrónico, llame a la función ClickToPay.lookupCustomer(email) para actualizar el SDK de C2P. El correo electrónico del pagador se utiliza para buscar si este pagador tiene un perfil C2P existente asociado con su dirección de correo electrónico.
Si recopila la dirección de correo electrónico del pagador en su sitio, infórmele que su correo electrónico se utiliza para buscar su perfil C2P. Puede incluir una información de herramienta junto al cuadro de entrada de correo electrónico que notifique al pagador que "usted se asocia con los esquemas de tarjetas participantes para ofrecer C2P para un pago más rápido y que el correo electrónico se comparte de forma segura con los esquemas de tarjetas participantes para verificar si el pagador ya tiene un perfil de C2P".
Si la dirección de correo electrónico actualizada:
-
- Está vinculada a un perfil de C2P existente:
- La devolución de llamada
onStateChangese activa connewState.payerState.emailEnrolled = true. - El SDK de JavaScript de C2P muestra el formulario de entrada de OTP.
- La devolución de llamada
- No está vinculada a un perfil de C2P existente, la devolución de llamada
onStateChangese activa con elnewState.payerState.emailEnrolled = false.
Paso 5: Implementar pago
Si el pagador decide realizar el pago utilizando una tarjeta existente de su perfil C2P, llame a la función ClickToPay.checkoutWithExistingCard() después de que el pagador seleccione la tarjeta de la lista de tarjetas. La función lleva al pagador a la pantalla de confirmación de la tarjeta en el componente DCF.
Si el pagador decide inscribir una nueva tarjeta en su perfil C2P o no tiene un perfil:
- Muestre el formulario de entrada de la tarjeta como campos de Hosted Session para que el pagador pueda ingresar sus detalles de pago y hacer clic en Pay. Debe mostrar los campos para lo siguiente:
- Número de tarjeta
- Código de seguridad
- Mes y año de vencimiento
- Nombre en la tarjeta
- Recupere el esquema de tarjeta de la Hosted Session usando la devolución de llamada
PaymentSession.onCardTypeChange, que se activa cuando el pagador completa el número de tarjeta en el campo alojado. - Llame a la función
ClickToPay.isEnrollmentAvailableForScheme()usando el esquema.
La función compara el esquema proporcionado conpaymentTypes.card.walletProviders[n].secureRemoteCommerce.scheme[n].nameen la respuesta a la operación PAYMENT OPTIONS INQUIRY para determinar si está habilitado para el esquema.
Si la función devuelvefalse, salga de este flujo y utilice el flujo de pago de invitado para procesar la tarjeta normalmente sin C2P. - Mostrar y obtener consentimiento:
- Si se encuentra en los EE. UU., incluya información de que, si el pagador decide continuar, compartirá los detalles de la tarjeta, la dirección de facturación y el correo electrónico del pagador con los esquemas de tarjetas participantes para permitir la inscripción del pagador en C2P para que los procesos de pago sean más rápidos.
- Si se encuentra fuera de los EE. UU., muestre:
- La casilla de consentimiento sin marcar.
- La notificación de consentimiento donde el pagador acepta compartir los detalles de la tarjeta, la dirección de facturación y el correo electrónico con los esquemas de tarjetas participantes para permitir la inscripción del pagador en C2P para que los pagos se realicen con mayor rapidez.
- Cuando el pagador hace clic en el botón Pay en su página de pago para avanzar a la siguiente etapa:
- Si se encuentra fuera de los EE. UU. y la casilla de consentimiento no está marcada, el pagador no ha dado su consentimiento para compartir datos con C2P. Siga el flujo de pago como usuario invitado y procese la tarjeta normalmente sin C2P.
- Si se encuentra dentro o fuera de EE. UU. y el usuario ha marcado la casilla de consentimiento, actualice la sesión mediante la función
PaymentSession.updateSessionFromForm().
También puede actualizar la sesión con una dirección debillingopcional utilizando el objeto de facturación en una solicitud de UPDATE SESSION. Si inserta los detalles de facturación del pagador en la sesión de pago, el pagador no necesita volver a escribirlos durante la inscripción C2P.
- Después de actualizar la sesión, llame a la función
ClickToPay.checkoutWithNewCard(), que lleva al pagador a la pantalla de inscripción de la tarjeta en el componente DCF:
- Si la función falla, se invoca la devolución de llamada
onError. Tome las medidas necesarias para resolver el error. - Si la función tiene éxito, el pagador es redirigido al componente DCF.
- Si la función falla, se invoca la devolución de llamada
- El pagador interactúa con el componente DCF para facilitar la inscripción. Una vez que se invoca la devolución de llamada
onComplete, la interacción de C2P se completa y puede continuar con el paso 6 para actualizar la sesión con los detalles de C2P.
Paso 6: Actualizar la sesión con los detalles de pago de Click to Pay
Una vez que su pagador haya completado con éxito la interacción de C2P, debe solicitar al motor de pagos que recupere los detalles de pago para la interacción de C2P y los almacene en la sesión.
Envíe una solicitud de API UPDATE SESSION FROM WALLET del lado del servidor con lo siguiente:
- ID de sesión en la URL de solicitud.
- ID de correlación y esquema tal como se devuelven en la devolución de llamada
onComplete.
| Ejemplo de solicitud UPDATE SESSION FROM WALLET |
|---|
URL: "https://ap-gateway.mastercard.com/form/version/<version>/merchant/<merchant_ID>/session/<session_ID>
HTTP Method POST
{
"apiOperation":"UPDATE_SESSION_FROM_WALLET",
"order":{
"walletProvider":"SECURE_REMOTE_COMMERCE"
},
"wallet":{
"secureRemoteCommerce":{
"srcCorrelationId":"<correlationId_provided_in_payloadCallback>,
"scheme":"<scheme_provided_in_payloadCallback>"
}
}
}
|
Si la sesión se actualiza correctamente con los detalles de pago de la interacción C2P, muestre una pantalla de confirmación de pago para confirmar que todos los detalles sean correctos antes de que el pagador se comprometa con el pago. Si la sesión no se actualizó correctamente, pídale a su pagador que seleccione otra opción de pago.
Paso 7: Realizar autenticación 3D Secure (opcional)
Si desea autenticar al pagador, ejecute la Autenticación 3-D Secure mediante la sesión. Para obtener instrucciones detalladas, consulte 3DS con la API JavaScript de 3DS.
Paso 8: Realizar la operación de pago
Debido a una limitación de la funcionalidad DCF de Visa, si el pagador elige regresar a la página de entrada/selección de la tarjeta original para usar una tarjeta diferente para el pago después de haber completado la parte DCF del flujo, deberá reinicializar el SDK. El enfoque recomendado es llamar nuevamente a la función configure().
Después de que el pagador se comprometa con el pago (y la autenticación 3D Secure se realice correctamente, si se realiza), utilice la sesión para enviar el pago para su procesamiento desde su servidor. Por ejemplo, puede enviar una solicitud AUTHORIZE.
Los detalles de pago almacenados en la sesión de la interacción de C2P se utilizan para procesar el pago. Puede utilizar la misma sesión para varias operaciones de API. Para obtener más información sobre cómo realizar solicitudes de pago dentro de una sesión, consulte Conceptos básicos de las sesiones.
Para los flujos de pago como usuario invitado, utilice la implementación de Hosted Session básica para recopilar los detalles de la tarjeta de los campos alojados y agregarlos a la sesión antes de enviar la operación de pago.
| Ejemplo de solicitud AUTHORIZE |
|---|
URL: "https://ap-gateway.mastercard.com/form/version/{version}//merchant/<merchant_ID>/order/<order_ID>/transaction/<transaction_ID>
HTTP Method PUT
{
"apiOperation":"AUTHORIZE",
"session": {
"id": "<session_ID>"
}
}
|
Ejemplo HTML para la integración.
En esta sección se describe una integración simple para que la Hosted Session recopile los detalles de la tarjeta de crédito del pagador y configure C2P.
Hosted SessionEjemplo de integración
Ejemplo
<html>
<head>
<!-- INCLUDE SESSION.JS JAVASCRIPT LIBRARY -->
<script src="https://ap-gateway.mastercard.com/form/version/<Version>/merchant/<Merchant ID>/session.js"></script>
<!-- INCLUDE CLICK-TO-PAY.MIN.JS JAVASCRIPT LIBRARY -->
<script type="text/javascript" src="https://ap-gateway.mastercard.com/form/static/click-to-pay/click-to-pay.min.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 payment details:</div>
<h3>Credit Card</h3>
<div>Card Number: <input type="text" id="card-number" class="input-field" title="card number" aria-label="enter your card number" value="" tabindex="1" readonly></div>
<div>Expiry Month:<input type="text" id="expiry-month" class="input-field" title="expiry month" aria-label="two-digit expiry month" value="" tabindex="2" readonly></div>
<div>Expiry Year:<input type="text" id="expiry-year" class="input-field" title="expiry year" aria-label="two-digit expiry year" value="" tabindex="3" readonly></div>
<div>Security Code:<input type="text" id="security-code" class="input-field" title="security code" aria-label="three-digit CCV security code" value="" tabindex="4" readonly></div>
<div>Cardholder Name:<input type="text" id="cardholder-name" class="input-field" title="cardholder name" aria-label="enter name on card" value="" tabindex="5" readonly></div>
<div><button id="payButton" onclick="pay('card');">Pay Now</button></div>
<!-- CREATE THE HTML FOR THE CLICK-TO-PAY INTERACTION -->
<div>C2P Fields Below------</div>
Email: <input id="payerEmail" onblur="updateEmail();" /><br/>
<div id="cardListContainer" ></div><br/>
<div id="otpContainer"></div><br/>
<div id="cardFacilitator" ></div><br/>
<div id="coid" ></div><br/>
<!-- 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({
session: "<your_session_ID>",
fields: {
// ATTACH HOSTED FIELDS TO YOUR PAYMENT PAGE FOR A CREDIT CARD
card: {
number: "#card-number",
securityCode: "#security-code",
expiryMonth: "#expiry-month",
expiryYear: "#expiry-year",
nameOnCard: "#cardholder-name"
}
},
//SPECIFY YOUR MITIGATION OPTION HERE
frameEmbeddingMitigation: ["javascript"],
callbacks: {
initialized: function(response) {
console.log('initialized: ' + response)
if(response.status === 'ok') {
//configure C2P
configure()
}
},
formSessionUpdate: function(response) {
// HANDLE RESPONSE FOR UPDATE SESSION
if (response.status) {
if ("ok" == response.status) {
console.log("Session updated with data: " + response.session.id);
//CHECK IF SECURITY CODE WAS PROVIDED BY THE USER
if (response.sourceOfFunds.provided.card.securityCode) {
console.log("Security code was provided.");
}
//CHECK IF THE USER ENTERED A MASTERCARD CREDIT CARD
if (response.sourceOfFunds.provided.card.scheme == 'MASTERCARD') {
console.log("The user entered a Mastercard credit card.")
}
ClickToPay.isEnrollmentAvailableForScheme(response.sourceOfFunds.provided.card.scheme, function (canEnroll) {
console.log('Card can be enrolled', canEnroll)
if(canEnroll) {
ClickToPay.checkoutWithNewCard();
}
});
} else if ("fields_in_error" == response.status) {
console.log("Session update failed with field errors.");
if (response.errors.cardNumber) {
console.log("Card number invalid or missing.");
}
if (response.errors.expiryYear) {
console.log("Expiry year invalid or missing.");
}
if (response.errors.expiryMonth) {
console.log("Expiry month invalid or missing.");
}
if (response.errors.securityCode) {
console.log("Security code 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);
}
}
},
interaction: {
displayControl: {
formatCard: "EMBOSSED",
invalidFieldCharacters: "REJECT"
}
}
});
function pay() {
// UPDATE THE SESSION WITH THE INPUT FROM HOSTED FIELDS
PaymentSession.updateSessionFromForm('card');
}
</script>
<script type="text/javascript">
var payloadCallback = function (correlationId, scheme) {
console.log('Payload callback complete with correlation id %s and scheme %s', correlationId, scheme);
};
var errorCallback = function (error) {
console.log('Error callback triggered with error ' + error);
console.log(error);
};
var cancelCallback = function () {
console.log('Cancel callback triggered');
};
function configure() {
ClickToPay.configure({
merchant: {
id: "<your_gateway_merchant_ID>",
name: "<your_gateway_name>",
url: "<your_web_site_URL>"
},
session: {
id: "<your_session_ID>",
wsVersion: <api_version>
},
order: {
amount: <amount>,
currency: "<currency>"
},
interaction: {
//BILLING PREFERENCE WITH ONE OF THE FOLLOWING VALUES: NONE, FULL, POSTAL_COUNTRY
billingPreference: "FULL",
collectShippingAddress: true,
locale: "<locale>",
country: "<country code>"
},
customer: {
email: "<payers_email_address>"//OPTIONAL
},
elements: {
cardList: "cardListContainer",
otp: "otpContainer", // OPTIONAL
dcf: "cardFacilitator"
},
callbacks: {
onComplete: function(correlationId, scheme) {
console.log("onComplete fired");
console.log("Correlation ID: " + correlationId);
console.log("Scheme: " + scheme);
document.getElementById("coid").innerHTML = 'Correlation ID: ' + correlationId + ', Scheme: ' + scheme
},
onStateChange: function(changeInfo) {
console.log("onStateChange fired");
console.log(changeInfo);
},
onError: function(errInfo) {
console.log("onError fired");
console.log(errInfo);
}
}
});
}
function updateEmail() {
ClickToPay.lookupCustomer(document.getElementById("payerEmail").value);
}
</script>
</body>
</html>