API CCBill: un clic
Introducción
Este documento es un anexo a la API de CCBill y analiza la configuración del comerciante patrocinador y del comerciante afiliado de las funciones de la API de CCBill necesarias para la implementación de la función de venta cruzada con un clic que ahora es compatible con la API de CCBill. Asegúrese de leer la sección de Mejores prácticas al final de este documento para minimizar el riesgo de contracargos y pérdida de ingresos.
Este documento también debe ser utilizado por los comerciantes que utilizan la red OneClick para ayudar a los desarrolladores con los métodos de integración de API necesarios para implementar ese sistema tanto por los comerciantes patrocinadores como por los comerciantes afiliados.
Alcance
La API de CCBill se considera una función avanzada. Como tal, este documento asume lo siguiente:
- El usuario ya ha habilitado la API de CCBill.
- El usuario posee habilidades de programación de nivel intermedio a avanzado.
- El usuario posee las habilidades de programación necesarias para crear scripts e implementarlos en el contexto de este documento.
- El usuario posee conocimientos de SOAP, HTML, XML y otras tecnologías de desarrollo web.
- El usuario ya ha recibido permiso y habilitado el Servicio de marketing web (WMS) y las ventas cruzadas con un clic en su cuenta (estos requisitos se describen más adelante en el Manual del usuario de la venta cruzada con un clic).
- El usuario ya ha configurado la Gestión de usuarios, si lo desea.
Terminología
La función Venta cruzada con un clic coloca a los comerciantes en roles que antes no estaban disponibles para los comerciantes de CCBill, lo que requiere la introducción de dos nuevos términos de la siguiente manera:
- Comerciante patrocinador. El comerciante patrocinador es un comerciante que desea que otros comerciantes les recomienden ventas mediante la función Venta cruzada con un clic.
- Comerciante afiliado. El comerciante afiliado es un comerciante que asume el papel de un afiliado con el fin de utilizar las ventas cruzadas con un clic para referir a sus consumidores existentes a un comerciante patrocinador a cambio de una parte de los ingresos generados por esa venta.
Soporte para controles de velocidad CCBill
Controles de velocidad CCBill es una característica avanzada de la API de CCBill y le permite limitar las transacciones de los clientes por el número de transacciones y / o por el monto en efectivo de las transacciones dentro de un período de tiempo específico. Esto significa que puede establecer el número de transacciones para un cliente específico dentro de un período de tiempo determinado. Las reglas se aplican a todos los tipos de pago y se pueden implementar en una sola subcuenta o en todas las subcuentas.
Cuando se aplica, a cada cliente se le asigna una identificación única basada en su información financiera y antecedentes de seguridad. Al configurar CCBill Velocity Controls, limita las posibilidades de fraude y, de manera individual, permite que los buenos clientes leales continúen comprando más allá de los límites establecidos.
Si está interesado en esta función avanzada, comuníquese con merchandisingupport@ccbill.com para configurar controles de velocidad de acuerdo con los requisitos de su negocio.
Descripción
La API de CCBill agrega una funcionalidad que permite a los comerciantes afiliados referir ventas a los comerciantes patrocinadores. La implementación adecuada de la API de ventas cruzadas con un clic tendrá como resultado que el comerciante afiliado pueda referir a los consumidores actuales a través del área de miembros, lo que permitirá al consumidor realizar la compra en el sitio del comerciante patrocinador sin tener que ingresar información de pago o de usuario. en la mayoria de los casos.
Implementación
La implementación de la API de venta cruzada con un clic será diferente para casi todas las situaciones. Este documento tiene la intención de brindarle una descripción general del proceso y las llamadas necesarias para los métodos admitidos de envío y recuperación; Deberá utilizar la información proporcionada y adaptarla a su propia configuración.
Métodos
Hay dos métodos básicos de implementación de venta cruzada con un clic:
- Método avanzado. Se prefiere este método. El método avanzado requiere la integración completa del comerciante afiliado con la API de CCBill y la gestión de usuarios, pero proporciona la experiencia más fluida para los consumidores.
- Método simple. El método simple es más fácil de implementar para los comerciantes afiliados, pero puede resultar en una mayor intervención del consumidor; incluyendo verificación de identificación y / o reingreso de pago e información de usuario. Hay dos subopciones disponibles para el método simple:
- Con ID de suscripción requiere la menor intervención del comerciante afiliado
- Con el nombre de usuario se requiere la integración del comerciante afiliado con la gestión de usuarios
Método avanzado
El método avanzado requiere que los comerciantes afiliados se integren completamente con la API de CCBill. Luego, el Afiliado utiliza las llamadas "Obtener token de venta cruzada" en la API de CCBill para generar y devolver un token autenticado a través de un script que realiza estas llamadas cada vez que se presenta al consumidor el material de marketing del programa. WMS luego reemplaza ese token con una versión modificada que contiene el ID de participación de WMS. El sitio del comerciante patrocinador utilizará la API de CCBill para realizar una llamada de "Cargo por token" a la API de CCBill para completar la compra. En el caso de que el token no esté autenticado (el período de autenticación ha caducado), el consumidor deberá proporcionar alguna verificación de identidad para obtener un token verificado y volver a enviar la llamada "Cargo por token".
Este método, aunque requiere más programación, crea una experiencia más fluida para el usuario. Sin embargo, requiere más trabajo por parte de sus comerciantes afiliados.
Método simple
El método simple requiere menos programación de los comerciantes afiliados para implementar, pero resulta en más información del consumidor para completar la compra.
En el método simple, los comerciantes afiliados adjuntan información de identificación sobre el titular de la suscripción al código de enlace de WMS en lugar de generar un token de API de CCBill. El consumidor es dirigido a través de WMS donde se crea un token no autenticado que incluye la información del comerciante afiliado y la información de identificación del consumidor y se envía al sitio del comerciante patrocinador. El consumidor hace clic para confirmar la compra, lo que activa la llamada "Cargo por token" a la API de CCBill, que a su vez reconoce el estado no autenticado del token y solicita al consumidor la verificación de identidad. Si la identidad se verifica con éxito, la API de CCBill redirigirá al parámetro "url" pasado por el comerciante patrocinador (también se puede proporcionar una "URL de falla" para los casos en los que el consumidor no se identifica correctamente).
El método simple tiene dos "subopciones" disponibles. La única diferencia entre los dos son los parámetros que deben enviarse del comerciante afiliado a WMS.
Integración API
- La API de venta cruzada con un clic se implementa como llamada SOAP. El punto de acceso es https://bill.ccbill.com/dss.
- Las respuestas están en formato SOAP y contienen errorCode y errorDesc junto con información adicional, si corresponde.
- Todas las operaciones incluyen los siguientes parámetros para fines de autenticación:
| información de autenticación | ||
|---|---|---|
| MerchantAccnum | Entero | Número de cuenta comercial de CCBill |
| ComercianteSubacc | Short | Número de subcuenta del comerciante de CCBill |
| usandoMerchantSubacc | Short | Número de subcuenta del comerciante de CCBill (cuando corresponda y MerchantSubacc es nulo) |
| nombre de usuario | Cordón | Nombre de usuario de la API de CCBill |
| la contraseña | Cordón | Contraseña de la API de CCBill |
Funciones del comerciante patrocinador
getCrossSaleSessionInfo / getCrossSaleTokenInfo
| IN | información de autenticación | ||
| IN | sessionId / tokeninfo | cadena | sessionId representa un identificador único para la relación de consumidor entre el comerciante afiliado y el comerciante patrocinador; tokeninfo es un objeto de datos transitorio que incluye información que se utilizará para crear o buscar una sesión. |
| OUT | correo electrónico, | cadena | Dirección de correo electrónico registrada para el consumidor del comerciante afiliado. |
| OUT | isAuthLocked | byte | 1 = El consumidor ha fallado demasiadas veces para ser autenticado y debe intentarlo de nuevo más tarde; 0 = El consumidor no ha agotado sus intentos de autenticación |
| OUT | está autenticado | byte | 1 = El consumidor ha validado su código postal o se trata de un token avanzado; 0 = El consumidor no ha validado su código postal, su ventana de validación ha expirado o un token avanzado ha expirado. |
| OUT | URL de autenticación | cadena | Si isAuthenticated = 0, el usuario deberá ser redirigido a esta URL para validar su identidad; Los siguientes parámetros se pueden transferir a este sistema: * url = URL para redirigir a una validación exitosa (si no se proporciona, redirigirá a HTTP_REFERER) * failureUrl = URL a la que redirigir tras una validación fallida (si no se proporciona, se redirigirá al parámetro "url") |
| OUT | esUsuarioCreado | byte | 1 = El patrocinador ha registrado correctamente un usuario para el consumidor utilizando el método createUserForCrossSale; 0 = El patrocinador aún no ha registrado un usuario para el consumidor mediante el método createUserForCrossSale. |
| OUT | pagoUniqueId | cadena | Identifica de forma única una cuenta de pago en particular (tarjeta de crédito / fecha de vencimiento, cuenta ACH / número de ruta) utilizando un algoritmo hash. Usado a menudo por los comerciantes patrocinadores con fines de fraude. |
| OUT | ID de participación del programa | entero | El identificador único que indica la relación entre un comerciante afiliado y el programa de un comerciante patrocinador. |
| OUT | ID de sesión | cadena | Lo mismo que arriba. |
| OUT | código de error | entero | 0 = No hubo error; consulte el Apéndice A: Códigos de error y descripciones para obtener una lista de otros códigos posibles. |
| OUT | errorDesc | cadena | Descripción del error devuelto; consulte el Apéndice A: Códigos de error y descripciones para obtener una lista de posibles descripciones. |
| OUT | ID de suscripción | entero | Si esto está presente, el comerciante patrocinador ha procesado al menos una venta con esta sesión. El subscriptionId proporcionado fue la primera venta procesada. |
Ejemplo
0 usuario test9000000 1234OJ4K3i6IOtc63Czanbz0m5boEiaFf + lE2prv2bPkXQ =
Respuesta:
0 xxxx@ccbill.com 0 1 0 / PvvoUQCmc3WoTssCZawbQ 4240 kmEEyxSst43rIx0Quj4RyA 0106100101000000001
información de pago
| IN | información de autenticación | |||
| IN | sessionId / tokeninfo | cadena | sessionId representa un identificador único para la relación de consumidor entre el comerciante afiliado y el comerciante patrocinador; tokeninfo es un objeto de datos transitorio que incluye información que se utilizará para crear o buscar una sesión. | |
| IN | precio inicial | entero | Importe del cargo inicial. Basado en dos decimales implícitos. Por ejemplo, $ 2.95 deben pasarse como 295. | |
| IN | periodo inicial | entero | Duración del plazo inicial de suscripción en días. | |
| IN | Precio recurrente | entero | Opcional | Monto de cada cargo recurrente. Basado en dos decimales implícitos. Por ejemplo, se deben pasar $ 29.95 2995. |
| IN | período recurrente | entero | Opcional | Duración del plazo recurrente de la suscripción en días. |
| IN | refacturaciones | Corto | Opcional | Número de veces que se debe volver a facturar la suscripción antes de que finalice (99 para ilimitado). |
| IN | código de moneda | Corto | Opcional | Código de moneda numérico ISO 4217 (es decir, dólares estadounidenses = 840); Predeterminado a 840. |
chargeCrossSaleBySession / chargeCrossSaleByToken
| IN | pares de paso | pares nombre / valor | Opcional | Datos misceláneos que el Patrocinador puede pasar durante el proceso de registro que se les proporcionará en las publicaciones de antecedentes de aprobación / rechazo. |
| OUT | aprobado | byte | 0 = Rechazado, 1 = Aprobado. | |
| OUT | pagoUniqueId | cadena | Identifica de forma única una cuenta de pago en particular (es decir, tarjeta de crédito / fecha de vencimiento, cuenta ACH / número de ruta) utilizando un algoritmo hash. Algunos comerciantes utilizan esto con fines de fraude de su lado. | |
| OUT | ID de sesión | cadena | ID de sesión representa un identificador único para la relación de consumidor entre el comerciante afiliado y el comerciante patrocinador. | |
| OUT | ID de suscripción | cadena | El ID de suscripción de la transacción recién procesada (asumiendo que fue aprobada). | |
| OUT | ID de negación | entero | El descriptor único del ID. | |
| OUT | decliveCode | entero | El código de rechazo proporcionado por el procesador de la tarjeta de crédito. | |
| OUT | declinarTexto | cadena | Presente si se rechaza la transacción; proporciona una descripción de por qué se rechazó la transacción. | |
| OUT | AuthenticateUrl | cadena | Presente si el token / sesión no está autenticado. Si isAuthenticated = 0, el usuario deberá ser redirigido a esta URL para validar su identidad; Los siguientes parámetros se pueden transferir a este sistema: * url = URL para redirigir a una validación exitosa (si no se proporciona, redirigirá a HTTP_REFERER) * errorUrl = URL a la que redirigir tras una validación fallida (si no se proporciona, se redirigirá al parámetro "url") |
Ejemplo
0 900000 testuser test0000 kmEEyxSst1234rIx43Quj0RyA 4 1000 campo30 valor1
Respuesta:
0 1 / PvvoUQCmc3WoTssCZawbQ kmEEyxSst43rIx0Quj4RyA 910089201000000023
createUserForCrossSaleSession / createUserForCrossSaleToken
| IN | información de autenticación | |||
| IN | sessionId / tokeninfo | cadena | ID de sesión representa un identificador único para la relación de consumidor entre el comerciante afiliado y el comerciante patrocinador; tokeninfo es un objeto de datos transitorio que incluye información que se utilizará para crear o buscar una sesión. | |
| IN | Patrocinador Miembro Nombre de usuario | cadena | Opcional | El nombre de usuario que el comerciante patrocinador agregó a su sitio web y nos proporcionó utilizando el createUserForCrossSaleToken or createUserForCrossSaleSession métodos. |
| IN | Patrocinador Miembro Contraseña | cadena | Opcional | Igual que Patrocinador Miembro Nombre de usuario, excepto la contraseña. |
| OUT | ID de sesión | cadena | ID de sesión representa un identificador único para la relación de consumidor entre el comerciante afiliado y el comerciante patrocinador. |
Ejemplo
0 testuser test900000 kmEEyxSst1234rIx43Quj0RyA PRUEBA PRUEBA
Respuesta:
0 kmEEyxSst43rIx0Quj4RyA
Funciones de comerciantes afiliados
generar sesión para venta cruzada
| IN | información de autenticación | |||
| IN | ID de suscripción | entero | Opcional | El ID de suscripción desde el que el comerciante afiliado desea crear el token. |
| IN | AfiliadoMiembroNombre de usuario | cadena | Opcional | El nombre de usuario que el comerciante afiliado desea incluir en el token (se anulará con el que tenemos registrado si está utilizando nuestra gestión de usuarios). |
| IN | Afiliado Miembro Contraseña | cadena | Opcional | La contraseña que el comerciante afiliado desea incluir en el token (se anulará con lo que tenemos registrado si está utilizando nuestra gestión de usuarios). |
| OUT | tokeninfo | cadena | El token autenticado que se crea en base a la información anterior que utilizarán para reenviar al consumidor a través de WMS al sitio web del Patrocinador. |
Ejemplo
0 testuser test900000 1234
Respuesta:
0 4OJ3K6i63IOtc0Czanbz5thajxTbspyOu7DBqLoLt9w% 3D
Diagramas de flujo de API de venta cruzada con un clic
Método simple
Método avanzado
Apéndice A: Códigos de error y descripciones
| Código de error | Error de descripción |
|---|---|
| -101 | ID de suscripción no válido |
| -102 | ID de participación en el programa no válido |
| -103 | Sesión no encontrada |
| -104 | La sesión no está autenticada |
| -105 | ID de suscripción no presente |
| -106 | Error del sistema |
| -107 | Usuario ya creado |
| -108 | Transaccion rechazada |
| -109 | Suscripción inválida |
| -110 | No se puede verificar la suscripción |
| -111 | No se puede encontrar la información del cliente |
| -112 | Subcuenta de comerciante no válida |
| -113 | Información recurrente no válida |
Buenas Prácticas
API de 1 clic de CCBill Permitir a los comerciantes ofrecer a sus clientes una conveniente solución de facturación de actualización lo que permite a los clientes tener que volver a introducir sus datos de pago en compras posteriores. Las API son administradas por el comerciante y las transacciones las inician los consumidores dentro del sitio web del comerciante o del área de miembros. Si bien estas pueden ser herramientas muy convenientes y útiles, no vienen sin riesgo añadido. Se requiere que el comerciante administre gran parte de la experiencia del consumidor, y las API están diseñadas para evitar el sistema de autenticación de CCBill, V-Scrub.
Como resultado, es imperativo que el comerciante comprenda sus responsabilidades e implemente un sistema de controles diseñado para gestionar la experiencia del consumidor y minimizar el riesgo de devoluciones de cargo y pérdida de ingresos.
Si bien el modelo comercial de cada comerciante es inherentemente único y los controles que implementan pueden diferir, lo siguiente y las mejores prácticas actuar como una guía para los comerciantes que procesan Transacciones con 1 clic.
- Divulgación del consumidor: Aumentar la educación y la conciencia del consumidor durante todo el proceso de pago y el sitio web.
- Descripciones claras de precios durante todo el proceso de actualización. Los precios deben incluir la moneda adecuada, el valor exacto de los créditos / tokens y deben mostrar cualquier otro término relevante para la compra.
- El botón de compra debe estar orientado a la acción para garantizar que el consumidor sepa que está iniciando una compra.
- Mensajes claros de aprobación / denegación: El consumidor debe ser informado de la aprobación / denegación inmediatamente. dentro del área de miembros, y se deben enviar correos electrónicos de confirmación.
- Educación ambiental con 1 clic: Los consumidores deben comprender que pueden iniciar cargos contra su cuenta con solo hacer clic en un botón. Además de la mensajería clara, algunos comerciantes pueden querer asegurarse de que sus clientes puedan optar por participar y no participar en el entorno de 1 clic.
- Política de Devolución: La política de reembolso del comerciante debe ser fácil de localizar en el sitio web, y debe indicar claramente a los consumidores qué problemas pueden resultar en un reembolso si tienen problemas con su compra.
- Descriptores de facturación debe reforzarse en el proceso de actualización y en los correos electrónicos de confirmación. La página de soporte del comerciante también debe proporcionar un refuerzo de los descriptores.
- Información de soporte debe prevalecer en todo el sitio web para garantizar que los clientes puedan ponerse en contacto con el soporte para cualquier problema con su servicio.
- Controles de velocidad: Las API de 1 clic no limitan el volumen de transacciones y las transacciones no se eliminan por riesgo.
- Clientes nuevos versus existentes: Trate a los nuevos clientes con mayor escrutinio al limitar sus transacciones en un período de tiempo determinado. Por ejemplo, a un nuevo cliente solo se le debe permitir comprar 4 transacciones dentro de los primeros 30 días.
- Clientes existentes que han demostrado ser de bajo riesgo también se les puede pedir que revalidar sus datos después de un mayor número de transacciones. Por ejemplo, el cliente tiene que volver a aceptar el acuerdo de 1 clic después de 20 transacciones.
- Monitoreo de fuentes de tráfico / afiliados: El comerciante debe informar la actividad de reembolso y devolución de cargo a sus fuentes de tráfico para asegurarse de que se administren de manera adecuada de un mes a otro.
- Los afiliados / fuentes de tráfico con altas tasas de contracargo deben cancelarse.
- Retrasar los pagos con nuevas fuentes de afiliado / tráfico para garantizar que las transacciones se puedan revisar antes de pagar al afiliado. Si se detectan patrones de alto riesgo, retrase el pago para garantizar que los reembolsos y las devoluciones de cargo puedan compensarse.
Nota:: Esto puede tardar hasta 120 días.
- Monitoreo de estudio de modelo / cámara: El comerciante debe informar la actividad de reembolso y contracargo a las fuentes de su modelo y estudio de cámara para asegurarse de que se administren de manera adecuada de mes a mes.
- Las fuentes de Model / Cam Studio con altas tasas de contracargo deben finalizar.
- Retrasar los pagos con nuevas fuentes de estudio de modelos / cámaras para garantizar que las transacciones se puedan revisar antes de pagar al afiliado. Si se detectan patrones de alto riesgo, retrase el pago para garantizar que los reembolsos y las devoluciones de cargo puedan compensarse.
Nota:: Esto puede tardar hasta 120 días.
- Monitoreo posterior a la transacción: El comerciante debe verificar a un consumidor si detecta patrones o comportamientos de mayor riesgo.
- Revisar el crédito / token de los clientes patrones de uso. Los nuevos clientes que no utilicen tokens o créditos en el momento del pago deben considerarse de alto riesgo.
- Revisar IP asociados con los inicios de sesión y comparar con la compra de IP. Las diferencias deben considerarse de alto riesgo.
- Cantidades altas en dólares gastados en períodos de tiempo más cortos deben revisarse para garantizar su legitimidad.