Sistema de actualización de suscripción

Introducción

La guía del usuario del sistema de actualización de suscripción se proporciona como un recurso técnico para los comerciantes de CCBill. Está destinado a programadores y técnicos con habilidades de programación avanzadas.

RESUMEN

El sistema de actualización de suscripción permite a los comerciantes de CCBill actualizar una suscripción de consumidor a una nueva suscripción. Esto se puede hacer en la misma subcuenta o en una subcuenta diferente. Las actualizaciones deben estar preconfiguradas para la cuenta. El sistema admite actualizaciones de tarjetas de crédito y ACH (Cámara de compensación automatizada).

El sistema de actualización de suscripción admite el uso de precios regionales. De forma predeterminada, se utilizará la configuración de precios regionales de la cuenta a la que se actualiza la suscripción. Esta configuración se ignorará si los precios regionales no están habilitados en la cuenta. Para obtener más información sobre precios regionales, consulte la Guía del usuario de precios regionales.

La siguiente URL se utilizará para todas las operaciones de actualización que utilicen este sistema:

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

Los valores se pasarán a esta URL según sea necesario.

Requisitos de instalación

Las actualizaciones las configura en su totalidad el personal de CCBill. Los requisitos de configuración para esta funcionalidad se definen a continuación.
Los siguientes requisitos son necesarios para utilizar el sistema de actualización de suscripción al actualizar de un tipo de suscripción a otro:

  • Aprobación de la dirección de CCBill
  • Si actualiza a una subcuenta diferente, debe tener al menos dos subcuentas configuradas; de lo contrario, solo se necesita uno
  • Capacidad para crear URL dinámicas basadas en el suscriptor.
  • Información del suscriptor, como ID de suscripción o nombre de usuario
  • Uno de los siguientes:
    • Cadena de cifrado TripleDES codificada en Base64 (preferido), O
    • Capacidad de publicación backend HTTPS

Formulario de actualización

Las actualizaciones requieren un formulario de actualización, que es utilizado por el consumidor para solicitar la actualización. CCBill proporciona un formulario de actualización predeterminado que se puede personalizar para actualizaciones de tarjeta de crédito o ACH. El formulario de actualización se puede modificar aún más para satisfacer las necesidades específicas del comerciante; sin embargo, debe contener toda la información del formulario de actualización predeterminado. También debe ser fácil de entender y no engañoso para el consumidor, además de estar aprobado por la gerencia de CCBill.

El formulario de actualización de ACH debe contener un campo donde se puede ingresar el número de cuenta bancaria y el formulario de actualización de tarjeta de crédito debe contener un campo donde se puede ingresar el número CVV2.

Implementación

Esta sección describe los métodos de implementación para las actualizaciones de suscripción.

Para configurar una actualización, CCBill necesitará la siguiente información para todas las subcuentas involucradas en la actualización:

  • Cuenta mercantil (por ejemplo, 900000)
  • Subcuenta del comerciante (p. Ej., 0006)
  • Precios (uno de los siguientes)
    • ID de tipo de suscripción (que se encuentra en el área de administración de precios del portal de administración de CCBill)
    • Precio inicial, período inicial, precio recurrente, período recurrente, reembolsos (por ejemplo, “5.00, 5, 29.95, 30, 99”). No se pueden utilizar signos de moneda.
  • Tipo de subcuenta (inicial o actualización)

Proporcione esta información al servicio de asistencia al comerciante para configurar la actualización. Una vez completada, la funcionalidad de actualización de suscripción se puede implementar en el sitio del comerciante.

Método de seguridad de transmisión

Hay dos opciones de seguridad de transmisión disponibles para actualizaciones preconfiguradas. Los comerciantes deben elegir entre dos métodos de autorización diferentes cuando envían a los consumidores al formulario de actualización.
Se puede utilizar cualquiera de las siguientes opciones:

  • Cifrado (preferido)
    • El comerciante deberá obtener una clave de cifrado TripleDES de Merchant Support.
  • Publicación HTTPS de backend
    • Una lista de las direcciones IP del comerciante de CCBill y / o los rangos de IP desde los cuales CCBill recibirá Publicaciones HTTPS de backend. Las direcciones IP deben ser lo más específicas posible; no se aceptarán grandes rangos.

Tecnología

Los parámetros que se pasan al CGI mencionado anteriormente se explican a continuación. Hay dos métodos de transmisión disponibles:

Opción 1: cifrado (preferido)

El método de cifrado es un proceso de un solo paso que utiliza cifrado TripleDES. Se debe configurar una clave TripleDES y obtenerla de CCBill Merchant Support. Una vez que los datos están encriptados, la cadena de encriptación debe estar codificada en Base64 para que pueda usarse en una URL. La cadena de cifrado se utilizará como valor para el parámetro "enc". Realice los siguientes pasos para obtener el valor enc:

  1. Inicie sesión en el portal de administración de CCBill y vaya a Información de cuenta-> Administrador de cuenta-> Avanzado.
  2. En la sección Actualizar información de configuración de seguridad, asegúrese de que Cifrado se selecciona como el Tipo de seguridad.
  3. Seleccione TripleDES como el Tipo de cifrado.
  4. Escriba su clave de cifrado en el campo proporcionado. Esta clave debe obtenerse de Merchant Support.
  5. Haga clic en Noticias para guardar la clave.
  6. Con el cifrado TripleDES y su herramienta de codificación Base64 preferida, codifique el nombre de usuario o el ID de suscripción del usuario utilizando la clave de cifrado. El valor codificado se utilizará como valor para el parámetro enc.

Los siguientes parámetros son obligatorios y deben pasarse al siguiente script:

https://bill.ccbill.com/jpost/upgradeSubscription.cgi
Nombre de la variableDescripciónValor de ejemplo
clienteAccnumCuenta de comerciante CCBill (de la suscripción original)900100
clienteSubaccSubcuenta de comerciante de CCBill (de la suscripción original)0006
encCadena cifrada TripleDES, codificada en Base64. Incluirá el subscriptionId o el nombre de usuario.subscriptionId = 1234567890 O username = johnDoe (antes del cifrado)

Las siguientes variables son necesarias solo cuando se configura más de una actualización:

Variable
Nombre
DescripciónValor de ejemplo
upgradeClientAccnumSe actualizará la cuenta de comerciante de CCBill.900100
actualizarClienteSubaccSe actualizará la subcuenta de comerciante de CCBill.0006
upgradeTypeIdID de tipo de suscripción que se utilizará para la actualización. Este valor identifica la actualización y se obtiene al configurar la actualización.0015

Estas tres variables se pueden omitir si solo se configura una actualización. En este caso, ese precio será el que se utilice para la actualización.

El siguiente ejemplo utiliza los valores de muestra mostrados arriba y un TripleDES clave de "8745921457." Los campos opcionales están en letras en negrita:

<form method="POST"
action="https://bill.ccbill.com/jpost/upgradeSubscription.cgi">
<input type="hidden" name="clientAccnum" value="900100">
<input type="hidden" name="clientSubacc" value="0006">
<input type="hidden" name="enc" value="sysl4wpcOfdF80ghzxJ0H/8YVuBGxA+4wqZqXHS48l8=">
<input type="submit" name="submit" value="Upgrade Subscription">
<strong><input type="hidden" name="upgradeClientAccnum" value="900100">
<input type="hidden" name="upgradeClientSubacc" value="0006">
<input type="hidden" name="upgradeTypeId" value="0015"></strong>
</form>

Este código mostrará un botón de formulario. Al hacer clic, se realizará la actualización y el consumidor será enviado a la página de Aprobación o denegación de redireccionamiento, según el resultado de la transacción.

Opción 2: Publicación HTTPS de backend

El método Backend HTTPS Posting es un proceso de dos pasos. El primer proceso es la publicación de backend desde el servidor del comerciante a la URL de actualización de CCBill. Esto devolverá un valor que indica si la actualización se puede realizar o no (ver Valores de retorno La mesa debajo).

El segundo paso es enviar al consumidor al formulario de actualización. El consumidor debe ser enviado al formulario de actualización dentro de los 30 minutos posteriores a la publicación Backend HTTPS. Si no se envía al consumidor dentro de los 30 minutos, la publicación HTTPS de backend debe enviarse nuevamente.

Tenga en cuenta que al pasar el ID de suscripción o el nombre de usuario, el valor no es un hash cifrado, ya que se usaría el método de cifrado definido anteriormente en este documento.

Paso 1: publicación HTTPS de backend

Los parámetros requeridos enviados son:

Nombre de la variableDescripciónValor de ejemplo
clienteAccnumCuenta de comerciante CCBill (de la suscripción original)900100
clienteSubaccSubcuenta de comerciante de CCBill (de la suscripción original)0006
TérmicaEl valor siempre será "allowUpgrade". Esto significa que la solicitud entrante preparará el sistema para que un consumidor pueda actualizar.permitirActualizar
ID de suscripción
OR
nombre de usuario
El subscriptionId o el nombre de usuario al que se le permitirá actualizar.1234567890

Las siguientes variables son necesarias solo cuando se configura más de una actualización:

Nombre de la variableDescripciónValor de ejemplo
actualizarclienteAccnumSe actualizará la cuenta de comerciante de CCBill.900000
actualizarclienteSubaccSe actualizará la subcuenta de comerciante de CCBill.0006
upgradeTypeIDTipo de suscripción que se utilizará para la actualización0015

Estas tres variables se pueden omitir si solo se configura una actualización; en este caso, ese precio será el que se utilice para la actualización.

Ejemplo usando los datos anteriores (las líneas nuevas se usan para mayor claridad; los campos opcionales están en negrita):

https://bill.ccbill.com/jpost/upgradeSubscription.cgi?
clientAccnum=900100&
clientSubacc=0006&
action=allowUpgrade&
subscriptionId=1234567890<strong>&
upgradeClientAccnum=900100&
upgradeClientSubacc=0006&
upgradeTypeId=0015</strong>

Nota: Esta publicación debe provenir de una dirección IP permitida en el servidor del comerciante. No se debe dirigir al consumidor a esta URL.

Valores devueltos:

Los posibles valores devueltos se incluyen en la siguiente tabla:

ValorDescripción
 Éxito
 Autorización denegada (la cuenta no está configurada para actualizar o la dirección IP no está permitida)
 Nombre de usuario (nombre de usuario) o ID de suscripción (subscriptionId) no proporcionado
 No se encontraron suscripciones activas
 ID de suscripción no válido
 Error interno, póngase en contacto con CCBill

Si se devuelve un valor de "1", se aprueba la actualización y puede comenzar el paso 2.

Paso 2: envío del consumidor al formulario de actualización

Los parámetros requeridos enviados son:

Nombre de la variableDescripciónValor de ejemplo
clienteAccnumCuenta de comerciante CCBill (de la suscripción original)900100
clienteSubaccSubcuenta de comerciante de CCBill (de la suscripción original)0006
TérmicaEl valor siempre será "upgradeSubscription". Esto significa que la solicitud entrante mostrará al consumidor el formulario de actualización.UpgradeSubscription
ID de suscripción
OR
nombre de usuario
El subscriptionId o el nombre de usuario al que se le permitirá actualizar.1234567890

Las siguientes variables son necesarias solo cuando se configura más de una actualización:

Nombre de la variableDescripciónValor de ejemplo
actualizarclienteAccnumSe actualizará la cuenta de comerciante de CCBill.900100
actualizarclienteSubaccSe actualizará la subcuenta de comerciante de CCBill.0006
upgradeTypeIDTipo de suscripción que se utilizará para la actualización0015

Estas tres variables se pueden omitir si solo se configura una actualización; en este caso, ese precio será el que se utilice para la actualización.

Ejemplo utilizando los datos anteriores (los campos opcionales están en negrita):

<form method="POST"
action="https://bill.ccbill.com/jpost/upgradeSubscription.cgi">
<input type="hidden" name="clientAccnum" value="900100">
<input type="hidden" name="clientSubacc" value="0006">
<input type="hidden" name="action" value="upgradeSubscription">
<input type="hidden" name="subscriptionId" value="1234567890">
<input type="submit" name="submit" value="UpgradeSubscription">
<strong><input type="hidden" name="upgradeClientAccnum" value="900100">
<input type="hidden" name="upgradeClientSubacc" value="0006">
<input type="hidden" name="upgradeTypeId" value="0015"></strong>
</form>

Postback

Los valores de las variables se contabilizan mediante el sistema de Contabilización de antecedentes de CCBill. Los siguientes valores se enviarán a la URL de aprobación o la URL de denegación cuando se haya realizado o denegado la actualización, respectivamente:

  • originalClientAccnum. El número de cuenta comercial de seis dígitos desde donde se originó la actualización.
  • originalClientSubacc. El número de subcuenta de comerciante de cuatro dígitos desde donde se originó la actualización.
  • originalSubscriptionId. El número de identificación de suscripción de la suscripción original.

Para obtener más información sobre el uso de la publicación en segundo plano, consulte el Guía del usuario de la publicación en segundo plano de CCBill.