Guía de la API de CCBill

Introducción

Este documento se proporciona como recurso técnico para los comerciantes de CCBill.

La información contenida en este documento se refiere al establecimiento y uso de la Interfaz de Programa de Aplicación (API) del servicio al consumidor del lado del comerciante. La secuencia de comandos de administración de suscripciones reemplaza la secuencia de comandos de cancelación personalizada y proporciona nuevas funciones adicionales. La información contenida en este documento describe la funcionalidad de Gestión de Suscripciones y su interacción con el Sistema de Gestión de Usuarios CCBill. Se requiere una configuración adecuada del sistema de extracción de enlace de datos antes de que se pueda utilizar la API de CCBill.

API CCBill

La gestión de suscripciones.cgi La secuencia de comandos reemplaza la secuencia de comandos customCancel.cgi en el Sistema de extracción de enlace de datos. La API de CCBill tiene características adicionales que no se incluyeron en customCancel.cgi.

Antes de que el gestión de suscripciones.cgi Se puede utilizar el script. Su sistema debe estar configurado para acceder al Sistema de Extracción de Enlace de Datos CCBill.

El sistema de extracción de enlace de datos de CCBill permite a los comerciantes de CCBill acceder a los datos de transacciones de la base de datos de CCBill con un script CGI. Consulta el Guía del usuario de Data Link Extract para obtener más información sobre Data Link Extract.

Parámetros necesarios para la autenticación

clienteAccnum

Este parámetro especifica el número de cuenta comercial CCBill principal del comerciante que solicita los datos. El valor debe ser un número de seis dígitos.

nombre de usuario

Este es el nombre de usuario que se configuró para la autenticación en el sistema Data Link Extract.

la contraseña

Esta es la contraseña que se configuró para la autenticación en el sistema Data Link Extract.

Térmica

Esta es la función que se realizará dentro de la API de CCBill. Consulte Acciones admitidas para obtener una lista completa de las opciones disponibles.

La tabla enumera los parámetros que siempre se requieren independientemente de si la acción se realizará en la cuenta principal o en una subcuenta:

clienteAccnumnombre de usuariola contraseñaTérmica
Cuenta principal XXX
Sub-cuenta XXX

Número de cuenta principal - Todos los comerciantes de CCBill reciben un número de cuenta con fines de seguimiento. El formato estándar es 9xxxxx-xxxx, donde 9xxxxx es la cuenta principal. La cuenta principal es un número de 6 dígitos. Por ejemplo: "900000".

Número de subcuenta - Después de que un comerciante se registra para la facturación del sitio web, puede abrir una o más subcuentas. La subcuenta es un número de 4 dígitos. El formato estándar es: xxxx. Por ejemplo: "0002". La subcuenta es parte de la cuenta principal.

Parámetros opcionales

clienteSubacc

Este es el número de subcuenta específico con el que está relacionada la suscripción; debe tener cuatro dígitos. Si se proporciona este parámetro, se le autenticará en una subcuenta específica y no en la cuenta principal. Cualquier acción solicitada debe pertenecer a esta subcuenta; de lo contrario, la operación fallará.

usandoSubacc

Utilice este parámetro si desea autenticarse en la cuenta principal pero no en una subcuenta específica. Este parámetro especifica una subcuenta en la que se realizará una operación solicitada.

Nota:: Si clientSubacc se pasa junto con usingSubacc, deben tener el mismo valor para una autenticación exitosa. Diferentes valores harían que se autenticara en una subcuenta específica y operar en otra.

retornoXML

Si se pasa este parámetro, recibirá la información en formato XML; de lo contrario, la información se devuelve en formato CSV (valores separados por comas).

Acciones admitidas y parámetros requeridos

viewSubscriptionStatus

Informa el estado de la suscripción de un cliente.

Parámetros obligatorios (X) y opcionales (O)

viewSubscriptionStatusclienteSubaccusandoSubaccID de suscripciónretornoXML
Cuenta principal  OX 
Cuenta principal con XML  OXX
Sub-cuenta X X 
Subcuenta con XML X XX

Información devuelta

  • Si la suscripción está activa o no.
  • La fecha de cancelación de una suscripción cancelada.
  • ¿La suscripción es recurrente o es una suscripción de facturación única?
  • La próxima fecha de facturación para suscripciones recurrentes o la fecha de vencimiento para suscripciones de facturación única.
  • Si la suscripción ha sido anulada, reembolsada o devuelta y el número de cada ocurrencia.
  • El estado de la suscripción.

Códigos de estado:

  • 0: la suscripción está inactiva.
  • 1 - La suscripción está activa pero el cliente ha cancelado la suscripción (se refiere a las suscripciones recurrentes).
  • 2 - La suscripción está activa y el cliente NO ha cancelado su suscripción o la suscripción es una suscripción no periódica.
  • Si falla, se devolverá un código de error.

Ejemplo de versión CSV

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&action=viewSubscriptionStatus&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590

Regreso

"cancelDate","signupDate","chargebacksIssued","timesRebilled","expirationDate","recurringSubscription","subscriptionStatus","refundsIssued","voidsIssued""20050228","20050228170442","0","0","20050228","1","0","1","0"

EJEMPLO DE VERSIÓN XML

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123& returnXML=1&action=viewSubscriptionStatus&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590

Regreso

1.0 20050228 0 20050228 1 1 20050228170442 0 0

verDescuentoInfo

Reporta la información de descuento de una suscripción de consumidor.

Parámetros obligatorios (X) y opcionales (O)

verDescuentoInfoclienteSubaccusandoSubaccID de suscripciónretornoXML
Cuenta principal  O X X
Cuenta principal con XML  O X X
Sub-cuenta X  X 
Subcuenta con XML X  X X

Información devuelta

  • ¿La suscripción es elegible para un descuento?

Nota: Los descuentos solo se pueden configurar para suscripciones recurrentes. Además, para ser elegible para un descuento, el precio recurrente de la suscripción debe ser de al menos $ 5.00.

  • ¿Hay un descuento configurado actualmente para la suscripción?
  • ¿Cuáles son las propiedades del descuento?
  • Si falla, se devolverá un código de error.

Ejemplo de versión CSV

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&action=viewDiscountInfo&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590

Regreso

"startPeriod","amount","discounts","discountInterval","type","startDate""1","1.00","1","1","CANCEL","20050228173436"

EJEMPLO DE VERSIÓN XML

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password =test123&returnXML=1&action=viewDiscountInfo&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590

Regreso

1.0 1.00 1 1 20050228173436 CANCELAR

aplicar descuento

Aplica un descuento por cancelación configurado previamente a una suscripción determinada.

Parámetros obligatorios (X) y opcionales (O)

aplicar descuentoclienteSubaccusandoSubaccID de suscripciónretornoXML
Cuenta principal  O X 
Cuenta principal con XML  O X X
Sub-cuenta X O X 
Subcuenta con XML X O X X

Información devuelta

Se devolverá un código de éxito o error.

EJEMPLO DE VERSIÓN CSV

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientSubacc=&discountType=cancel&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&password=test123&action=applyDiscount&clientAccnum=923590

Regreso

"resultados" "1"

EJEMPLO DE VERSIÓN XML

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientSubacc=&discountType=cancel&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&password=test123&returnXML=1&action=applyDiscount&clientAccnum=923590

Regreso

1.0

voidTransaction

Anula la transacción de un consumidor, si aún es elegible. La transacción del consumidor más actual se puede anular durante un período definido antes de que se liquide la transacción.

No se le cobrará al consumidor.

Parámetros obligatorios (X) y opcionales (O)

voidTransactionclienteSubaccusandoSubaccID de suscripciónretornoXML
Cuenta principal  O X 
Cuenta principal con XML  O X X
Sub-cuenta X  X 
Subcuenta con XML X  X X

Información devuelta

Se devolverá un código de éxito o error.

EJEMPLO DE VERSIÓN CSV

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientSubacc=&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&password=test123&action=voidTransaction&clientAccnum=923590

Regreso

"resultados" "1"

EJEMPLO DE VERSIÓN XML

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientSubacc=&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&password=test123&returnXML=1&action=voidTransaction&clientAccnum=923590

Regreso

1.0

ReembolsoTransacción

Permite un reembolso total o parcial. Pasar la cantidad reembolsará esa cantidad; tenga en cuenta que no se pueden otorgar reembolsos por un monto superior al de la transacción inicial. Omitir el valor dará un reembolso completo por el monto de la transacción inicial.

Parámetros obligatorios (X) y opcionales (O)

modificarUserCredentialsclienteSubaccusandoSubaccID de suscripciónCantidad
Cuenta principal  O X O
Cuenta principal con XML  O X O
Sub-cuenta X  X O
Subcuenta con XML X  X O

Información devuelta

Se devolverá un código de éxito o error.

EJEMPLO DE VERSIÓN CSV

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&action=refundTransaction&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=900000&amount=5.95

Regreso

"resultados" "1"

EJEMPLO DE VERSIÓN XML

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&returnXML=1&action=refundTransaction&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=900000&amount=5.95

Regreso

1.0

voidOrRefundTransaction

Intentos de anular la transacción. Si la transacción ya no se puede anular porque ha pasado el período definido, se reembolsará la transacción. Los reembolsos parciales se pueden dar pasando en el cantidad parámetro. Si se transfiere el monto pero la transacción puede anularse, la transacción se anulará. Para emitir reembolsos totales o parciales sin intentar anular la transacción, consulte la ReembolsoTransacción sección de este documento.

Parámetros obligatorios (X) y opcionales (O)

voidOrRefundTransactionclienteSubaccusandoSubaccID de suscripciónretornoXMLcantidad
Cuenta principal  O X  O
Cuenta principal con XML  O X X O
Sub-cuenta  X  O
Subcuenta con XML  X X O

Información devuelta

Se devolverá un código de éxito o error.

EJEMPLO DE VERSIÓN CSV

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&action=voidOrRefundTransaction&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590

Regreso

"resultados" "1"

EJEMPLO DE VERSIÓN XML

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&returnXML=1&action=voidOrRefundTransaction&usingSubacc=0005&subscriptionId=1071776966&username=ccbill12&clientAccnum=923590

Regreso

1.0

modificarUserCredentials

Vuelve a agregar o cambia el nombre de usuario y / o contraseña para una suscripción activa.

Parámetros obligatorios (X) y opcionales (O)

modificarUserCredentialsclienteSubaccusandoSubaccID de suscripciónnombre de usuario del clientecontraseña del clienteretornoXML
Cuenta principal  O X O O 
Cuenta principal con XML  O X O O X
Sub-cuenta X  X O O 
Subcuenta con XML X  X O O X

Información devuelta

Se devolverá un código de éxito o error.

EJEMPLO DE VERSIÓN CSV

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?usingSubacc=0005&username=ccbill12&custUsername=randomUN&password=test123&action=modifyUserCredentials&custPassword=randomPW&clientAccnum=923590

Regreso

"resultados" "1"

EJEMPLO DE VERSIÓN XML

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?usingSubacc=0005&username=ccbill12&custUsername=randomUN&password=test123&action=modifyUserCredentials&custPassword=randomPW&clientAccnum=923590&returnXML=1

Regreso

1.0

manualAdd

Agrega manualmente un usuario a la cuenta. El usuario tendrá acceso al sitio hasta la fecha especificada por el 'endDate' parámetro. Esta opción omite el modelo de suscripción.

Parámetros obligatorios (X) y opcionales (O)

manualAddclienteSubaccusandoSubaccnombre de usuario del clientecontraseña del clientefecha finalgenerarRandomretornoXML
Cuenta principal  X X X X  
Cuenta principal con XML  X X X X  X
Sub-cuenta X  X X X  
Subcuenta con XML X  X X X  X
Cuenta principal con aleatorio  X   X X 
Cuenta principal con XML y aleatorio  X   X X
Subcuenta con aleatorio X    X X 
Subcuenta con XML y aleatorio X    X X X

Parámetros opcionales

generarRandom

Cuando se utiliza esta opción, el nombre de usuario y la contraseña se generarán de forma aleatoria y, por lo tanto, no se requieren los parámetros nombre de usuario y contraseña.

custUsername / custPassword

Cuando se pasan estos parámetros, el nombre de usuario y la contraseña se establecerán en los valores respectivos y, por lo tanto, no se generarán aleatoriamente.

Información devuelta

  • El nombre de usuario que se agregó.
  • La contraseña que se agregó.
  • EndDate es la fecha en la que se eliminará el acceso del consumidor.
  • Si falla, se devolverá un código de error.

EJEMPLO DE VERSIÓN CSV

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?usingSubacc=0005&username=ccbill12&custUsername=manualAdd1&password=test123&endDate=20050330&action=manualAdd&custPassword=manualAdd2&clientAccnum=923590

Regreso

"EndDate", "nombre de usuario", "contraseña" 20050330, manualAdd1, test123

EJEMPLO DE VERSIÓN XML

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?usingSubacc=0005&username=ccbill12&custUsername=manualAdd1&password=test123&returnXML=1&endDate=20050330&action=manualAdd&custPassword=manualAdd2&clientAccnum=923590

Regreso

1.0 manualAdd20050330 test1

manualEliminar

Elimina la capacidad de un consumidor para acceder a su sitio.

Parámetros obligatorios (X) y opcionales (O)

manualEliminarclienteSubaccusandoSubaccnombre de usuario del clienteretornoXML
Cuenta principal  X X 
Cuenta principal con XML  X X X
Sub-cuenta X  X 
Subcuenta con XML X  X X

Información devuelta

Se devolverá un código de éxito o error.

EJEMPLO DE VERSIÓN CSV

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&custUsername=quarter&action=manualRemove&usingSubacc=0005&username=ccbill12&clientAccnum=923590

Regreso

"resultados" "1"

EJEMPLO DE VERSIÓN XML

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&returnXML=1&custUsername=quarter&action=manualRemove&usingSubacc=0005&username=ccbill12&clientAccnum=923590

Regreso

1.0

extender suscripción

Extiende la duración de una suscripción de consumidor existente. los ‘extendLength’ El parámetro se usa para extender la suscripción por varios días.

Parámetros obligatorios (X) y opcionales (O)

manualEliminarclienteSubaccusandoSubaccretornoXMLextenderLongitud
Cuenta principal  X  X
Cuenta principal con XML  X X X
Sub-cuenta X   X
Subcuenta con XML X  X

Información devuelta

Se devolverá un código de éxito o error.

EJEMPLO DE VERSIÓN CSV

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&username=test123&clientAccnum=999999&clientSubacc=0000&action=extendSubscription&subscriptionId=1234567890&extendLength=30

Regreso

"resultados" "1"

EJEMPLO DE VERSIÓN XML

Solicitar cadena

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?password=test123&username=test123&clientAccnum=999999&clientSubacc=0000&action=extendSubscription&subscriptionId=1234567890&extendLength=30&returnXML=1

Regreso

1.0

Códigos de éxito y fracaso

Códigos de éxito
1La acción solicitada fue un éxito.

Códigos de error

CódigoDescripción
0La acción solicitada falló.
-1Los argumentos proporcionados para autenticar al comerciante no eran válidos o faltaban.
-2El ID de suscripción proporcionado no es válido o el tipo de suscripción no es compatible con la acción solicitada.
-3No se encontró ningún registro para la suscripción dada.
-4La suscripción dada no era para la cuenta en la que el comerciante estaba autenticado.
-5Los argumentos proporcionados para la acción solicitada no eran válidos o faltaban.
-6La acción solicitada no es válida
-7Hubo un error interno o un error en la base de datos y la acción solicitada no se pudo completar.
-8La dirección IP en la que el comerciante intentaba autenticarse no estaba en el rango válido.
-9La cuenta del comerciante se ha desactivado para su uso en el sistema de enlace de datos o el comerciante no está autorizado a realizar la acción solicitada.
-10El comerciante no está configurado para usar el sistema Datalink.
-11La suscripción no es elegible para un descuento, precio recurrente menor a $ 5.00.
-12El comerciante ha iniciado sesión sin éxito en el sistema 3 o más veces en la última hora. El comerciante debe esperar una hora antes de intentar iniciar sesión nuevamente y se le recomienda que revise la información de inicio de sesión.
-15Comerciante por encima del umbral de reembolso
-16Comerciante por encima del umbral nulo
-23Se alcanzó el límite de transacciones
-24Se alcanzó el límite de compra

Ejemplo 1: Versión XML - Suscripción cancelada

Solicite

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=900100&username=myusername&password=mypassword&action=cancelSubscription&subscriptionId=1000000000&returnXML=1

Descripción

El comerciante está intentando autenticarse en la cuenta principal 900100. El clienteSubacc El parámetro no se pasa y, por lo tanto, la autenticación se llevará a cabo en la cuenta principal. La solicitud es para ver el estado de suscripción del ID de suscripción 1000000000. Desde el clienteSubacc no se pasó el parámetro, el ID de suscripción puede ser de cualquier subcuenta de la cuenta 900100. Si se hubiera pasado, el ID de suscripción tendría que ser para la subcuenta especificada. El comerciante solicita que la información se devuelva en formato XML.

Respuesta

1.0 20050223 0 20050324 1 0 20050222162551 1 0

Descripción

La fecha y hora de registro inicial de la suscripción fue el 02/22/2005 a las 04:25:51 PM. Es una suscripción recurrente. La fecha de vencimiento de la suscripción es el 03/24/2005. La suscripción está en estado activo; sin embargo, ha sido cancelado por el cliente el 02/23/2005. No hubo reembolsos, anulaciones, reembolsos o devoluciones de cargo para la suscripción.

Ejemplo 2: Versión CSV - Suscripción con descuento

Solicite

https://datalink.ccbill.com/utils/subscriptionManagement.cgi?clientAccnum=900000&username=myusername&password=mypassword&action=discountSubscription&discountAmount=2.00&subscriptionId=0012946984374168

Descripción

El comerciante está intentando autenticarse en la subcuenta 0002 que está bajo la cuenta 900100. La solicitud es ver la información de descuento para el ID de suscripción 1000000002. Debido a que el comerciante se está autenticando en la subcuenta 0002, la suscripción debe ser para esa subcuenta. No se pasó un returnXML y, por lo tanto, la información se devolverá en formato CSV.

Respuesta

"startPeriod","amount","discounts","discountInterval","type","startDate"
"3","5.00","2","1","LOYALTY","20050222162551"

Descripción

La información informa que hay un descuento configurado para la suscripción. El tipo de descuento que se configuró para el tipo de suscripción es un descuento por lealtad. El descuento comenzará después de 3 refacturaciones. El descuento es de $ 5.00 (el precio recurrente será de $ 5.00 menos). Se puede aplicar un máximo de 2 descuentos a la suscripción. El intervalo entre los descuentos aplicados es 1 refacturación; este es el número de refacturaciones que deben producirse antes de aplicar descuentos sucesivos. El registro de suscripción inicial se produjo el 02/22/2005.

Funciones especiales de la API de CCBill:

API CCBill: Cancelar suscripción
API CCBill: actualizaciones dinámicas avanzadas
API CCBill: un clic
API de CCBill: cargo por ID de transacción anterior