API CCBill: actualizaciones dinámicas avanzadas

Introducción

Este documento se publica como un anexo a la documentación de la API de CCBill y analiza la funcionalidad de actualización dinámica avanzada. Este documento está escrito para desarrolladores, técnicos y otras personas con habilidades de codificación avanzadas.

RESUMEN

Las actualizaciones dinámicas avanzadas permiten a los clientes actualizar las suscripciones anteriores de los consumidores a una nueva suscripción sin configurar previamente un precio en el sistema. Las actualizaciones dinámicas avanzadas se pueden realizar en la misma subcuenta o en una subcuenta diferente, y el cliente las configura en su totalidad. Debido a que las actualizaciones dinámicas avanzadas no requieren que el consumidor vuelva a ingresar la información de pago, el cliente es responsable de albergar los términos de la actualización que se ofrece.

Las actualizaciones dinámicas avanzadas no requieren que se configuren actualizaciones preconfiguradas en el sistema de CCBill. Sin embargo, los puntos de precio se pueden crear en el área de precios del administrador del Webmaster de CCBill, al que se producirá la actualización.

El sistema admite actualizaciones de tarjetas de crédito y ACH (Cámara de compensación automatizada).

Soporte de precios regionales

Las actualizaciones dinámicas avanzadas pueden admitir Precios regionales, con un paso adicional. Se realizarán dos solicitudes; la solicitud de actualización inicial calcula el nuevo precio y la segunda solicitud realmente realiza la transacción. Este proceso se describe en detalle más adelante en este documento.

Función de 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 a cada cliente se le asigna una identificación única en función de 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.

Nota: Cada regla se puede configurar en una sola subcuenta o en todas las subcuentas.

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.

Implementación

Las actualizaciones dinámicas avanzadas se crean pasando parámetros a una cadena de consulta. Las solicitudes deben enviarse al siguiente script CGI con valores de variable adjuntos:

https://bill.ccbill.com/jpost/billingApi.cgi

La actualización se realizará pendiente de la validación de CCBill. Dependiendo del resultado de la validación, se devolverán diferentes resultados. Los resultados se pueden devolver en formato de valores separados por comas (CSV) o en formato XML. A continuación, se muestran ejemplos de cadenas de solicitud y su resultado potencial.

Explicaciones de campo

La siguiente lista describe el valor de cada campo para las actualizaciones dinámicas avanzadas.

  • ID de suscripción. El identificador único de la suscripción del consumidor. <strong>Example value: 0108113201000024660</strong>
  • upgradeTypeId. ID de tipo de suscripción válido para la actualización. Este valor es numérico y varía en longitud. Este valor es el identificador de precio único que se puede encontrar en el área de administración de precios del administrador de webmasters de CCBill. (Tenga en cuenta que este valor se puede omitir si desea utilizar el precio de actualización predeterminado. Consulte el Administrador de precios de CCBill página de ayuda para obtener más información sobre las actualizaciones predeterminadas). <strong>Example value: 35160</strong>
  • upgradeClientAccnum. El número de cuenta de cliente CCBill de seis dígitos al que se está actualizando. <strong>Example value: 90000</strong>
  • actualizarClienteSubacc. El número de subcuenta de cliente de CCBill de cuatro dígitos al que se está actualizando. <strong>Example value: 0000</strong>
  • oferta especial. Indica si la actualización es una oferta especial. Un valor de cero (0) significa que la actualización no es una oferta especial y cancelará la suscripción original. Un valor de uno (1) indica una oferta especial y no cancelará la suscripción original. En ambos casos, la nueva suscripción recibirá un número de identificación de suscripción diferente. <strong>Example value: 0 or 1</strong>
  • prorratear. Este valor indica la opción de prorrateo preferida. Un valor de uno (1) prorratea la cantidad y un valor de dos (2) prorratea la cantidad de tiempo. <strong>Example value: 1 or 2</strong>
  • autenticación compartida. Indica si se utiliza la autenticación compartida; un valor de uno (1) significa que las cuentas de origen y destino están usando el mismo archivo de contraseña y / o base de datos, y un valor de cero (0) significa que no se usa la autenticación compartida. Example value: 0 or 1
  • Térmica. Este valor determina el tipo de actualización que se utilizará. Si usa Precios regionales, el valor se establecerá en obtener detalles de actualización. Si NO usa los precios regionales, el valor se establecerá en UpgradeSubscription.
  • anularAfiliado. Utilizado solo con el Sistema de afiliados heredado (LAS), este parámetro se utiliza para anular el pago de afiliados en las actualizaciones. Un valor de 0 le dice al sistema que no acredite a ningún afiliado, se puede pasar una ID de afiliado de LAS válida para indicar el afiliado que debe recibir el crédito, o el parámetro puede estar ausente. Pasar un parámetro en blanco o un ID de afiliado no válido dará como resultado un mensaje de error.
  • anular la participación. Utilizado únicamente con el Servicio de marketing web (WMS), este parámetro se utiliza para anular el pago del afiliado en las actualizaciones. Un valor de 0 le dice al sistema que no acredite a ningún afiliado, se puede pasar un WMS PPID válido para indicar el afiliado que debería recibir el crédito, o el parámetro puede estar ausente. Pasar un parámetro en blanco o un ID de afiliado no válido dará como resultado un mensaje de error.

Nota: If oferta especial se establece en cero (0), se debe incluir el parámetro de prorrateo. De lo contrario, no se utiliza el parámetro de prorrateo.

Parámetros obligatorios (✔) y opcionales

Todos los parámetros explicados anteriormente son obligatorios además de los campos obligatorios enumerados en la documentación principal de la API de CCBill. La siguiente tabla indica qué campos son obligatorios u opcionales:

Parámetros principales de la API de CCBill

clienteAccnumnombre de usuarioContraseñaclienteSubaccusandoSubaccretornoXMLTérmica
Cuenta principal✔ ✔     ✔
Cuenta principal con XML✔ ✔    ✔ ✔
Sub-cuenta✔ ✔ ✔    ✔
Subcuenta con XML✔ ✔ ✔   ✔ ✔

Parámetros de actualización adicionales

ID de suscripciónupgradeTypeIdupgradeClientAccnumactualizarClienteSubacc
Cuenta principal ✔ ✔ ✔
Cuenta principal con XML ✔ ✔ ✔
Sub-cuenta ✔ ✔ ✔
Subcuenta con XML ✔ ✔ ✔
Cuenta principal con oferta especial ✔ ✔ ✔
Cuenta principal con XML ✔ ✔ ✔
y oferta especial ✔ ✔ ✔
Subcuenta con oferta especial ✔ ✔✔ 
Subcuenta con XML y oferta especial ✔ ✔ ✔
oferta especialprorratearanularAfiliadoanular la participación
Cuenta principal ✔  
Cuenta principal con XML ✔  
Sub-cuenta ✔  
Subcuenta con XML ✔  
Cuenta principal con oferta especial   
Cuenta principal con XML   
y oferta especial   
Subcuenta con oferta especial   
Subcuenta con XML y oferta especial   

Ejemplos de código

Los siguientes ejemplos de código usan el UpgradeSubscription acción, que no admite precios regionales.

Ejemplo de versión de CVS

Solicitar cadena

https://bill.ccbill.com/jpost/billingApi.cgiclientAccnum=900100&username=testUser&password=testPass&action=upgradeSubscription&subscriptionId=18902345789012343781&upgradeTypeId=14&upgradeClientAccnum=900100&upgradeClientSubacc=0000&specialOffer=1&sharedAuthentication=1

Resultados enviados (para transacciones aprobadas):

Campos: "aprobado", "subscriptionId" Valores: "1", "100000000000000000"

Resultados enviados (para transacciones denegadas):

Campos: "aprobado", "denialId", "decliveCode", "decliveText" Valores: "0", "100000000000745921", "15", "rechazado por el banco"

Resultados enviados (cuando ocurre un error)

Campos: "resultados" Valores: "-1"

Ejemplo de versión XML

Solicitar cadena

https://bill.ccbill.com/jpost/billingApi.cgi?clientAccnum=900100&username=testUser&password=testPass&action=upgradeSubscription&subscriptionId=0108114301000018799&upgradeTypeId=14&upgradeClientAccnum=900100&upgradeClientSubacc=0000&specialOffer=1&sharedAuthentication=1&returnXML=1

Resultados enviados (para transacciones aprobadas)

1.0 1

Resultados enviados (para transacciones denegadas):

1.0 0 100000000000000000 rechazado por el banco

Resultados enviados (cuando ocurre un error)

-1.0

Implementación mediante precios regionales

Para utilizar los precios regionales con actualizaciones dinámicas avanzadas, se deben realizar dos solicitudes. La primera solicitud es una solicitud de actualización dinámica avanzada estándar utilizando el obtener detalles de actualización acción. La primera solicitud solo devuelve datos; no se procesa ninguna transacción hasta que se envía la segunda solicitud. La primera solicitud devolverá datos que se utilizarán en la segunda solicitud como se describe a continuación.

La segunda solicitud se enviará mediante el CargoBypreviousTransactionId acción. Esta solicitud procesa la transacción de actualización.

Nota:: Este documento solo describe el CargoBypreviousTransactionId acción con suficiente detalle para su uso con actualizaciones dinámicas avanzadas. Para obtener más información sobre esta acción, consulte el chargeByPreviousTransactionId apéndice a la Guía de la API de CCBill.

Devolver datos

La primera solicitud devuelve los siguientes valores:

  • precio inicial. El precio de la factura inicial.
  • Precio recurrente. El precio recurrente de cada refacturación.
  • periodo inicial. La duración del período inicial (en días).
  • período recurrente. El período de tiempo (en días) entre refacturaciones.
  • refacturaciones. Número total de veces que se volverá a facturar la suscripción. Un valor de "99" significa que la suscripción se volverá a facturar indefinidamente.
  • precioinicialDescripción. Descripción de texto del precio inicial.
  • preciorecurrenteDescripción. Descripción de texto del precio recurrente.
  • código de moneda. Código de moneda de tres dígitos en el que se procesa la transacción.
  • URL de transacción de proceso. La cadena completa para la segunda solicitud.

Una vez que los datos se hayan devuelto, envíe el URL de transacción de proceso valor como la segunda solicitud. Esto procesará la transacción.

Ejemplos de código

Los siguientes ejemplos de código usan el obtener detalles de actualización acción para respaldar los precios regionales. Debido a que esta acción requiere una segunda solicitud para procesar realmente la transacción, se proporcionan ejemplos de código para ambas solicitudes.

Tenga en cuenta que la primera solicitud devuelve un valor llamado URL de transacción de proceso que contiene la cadena exacta necesaria para la segunda solicitud. Esta URL procesará la transacción real. La segunda solicitud devuelve datos que describen los resultados de la transacción.

Ejemplo de versión de CVS

Primera cadena de solicitud

https://bill.ccbill.com/jpost/billingApicgi?clientAccnum=999999&clientSubacc=0000&username=q atest1&password=testing1&action=getUpgradeDetails&prorate=2&subscriptionId=090826720100 0000008&upgradeClientAccnum=999999&upgradeClientSubacc=0000&specialOffer=1&sharedA uthentication=0&upgradeTypeId=0000060948

Datos devueltos de la primera solicitud

Campos: "currencyCode", "recurringPriceDescription", "initialPriceDescription", "initialPeriod", "initialPrice", "recurringPrice", "recurringPeriod", "processTransactionUrl", "refacturación" Valores: "840", "", "$ 19.95 (USD ) durante 30 días "," 30 "," 19.95 "," 12.95 "," 30 "," [enlace a continuación] "," 99 "

Segunda cadena de solicitud

https://bill.ccbill.com/jpost/billingApi.cgiclientAccnum=999999&clientSubacc=0000&username=qatest1&password=testing1&action=chargeByPreviousTransactionId&subscriptionId=0908267201000000008&newClientAccnum=999999&newClientSubacc=0000&specialOffer=1&sharedAuthentication=0¤cyCode=840&initialPrice=19.95&initialPeriod=30&recurringPrice=12.95&recurringPeriod=30&rebills=99

Resultados enviados desde la segunda solicitud (para transacciones aprobadas)

Campos: "aprobado", "subscriptionId" Valores: "1", "1234567890"

Resultados enviados desde la segunda solicitud (para transacciones denegadas):

Campos: "aprobado", "denialId", "decliveCode", "decliveText" Valores: "0", "100000000000000000", "15", "rechazado por el banco"

Resultados enviados desde la segunda solicitud (cuando ocurre un error)

Campos: "resultados" Valores: "-1"

Ejemplo de versión XML

Primera cadena de solicitud

https://bill.ccbill.com/jpost/billingApi.cgiclientAccnum=999999&clientSubacc=0000&username=qatest1&password=testing1&action=getUpgradeDetails&prorate=2&subscriptionId=0908267201000000008&upgradeClientAccnum=999999&upgradeClientSubacc=0000&specialOffer=1&sharedAuthentication=0&upgradeTypeId=0000060948

Datos devueltos de la primera solicitud

840 30 19.95 $ 19.95 (USD) por 30 días [enlace debajo] 99 30 12.95

Segunda cadena de solicitud

https://bill.ccbill.com/jpost/billingApi.cgiclientAccnum=999999&clientSubacc=0000&username=qatest1&password=testing1&action=chargeByPreviousTransactionId&subscriptionId=0908267201000000008&newClientAccnum=999999&newClientSubacc=0000&specialOffer=1&sharedAuthentication=0¤cyCode=840&initialPrice=19.95&initialPeriod=30&recurringPrice=12.95&recurringPeriod=30&rebills=99

Resultados enviados desde la segunda solicitud (para transacciones aprobadas):

1.0 1

Resultados enviados desde la segunda solicitud (para transacciones denegadas):

1.0 0 100000000000000000 rechazado por el banco

Resultados enviados desde la segunda solicitud (cuando ocurre un error):

-1.0

Códigos de error

Independientemente de la acción que se utilice, se devolverán códigos numéricos si la solicitud falla debido a un error. Para obtener una lista completa de códigos de error y explicaciones, consulte la Guía de API de CCBill.

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.

  1. 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.
    • Los programas 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.