API de CCBill: cargo por ID de transacción anterior

Introducción

Este documento es un anexo al API CCBill documentación y analiza la funcionalidad Cargo por ID de transacción anterior. Proporciona parámetros, descripciones y ejemplos para desarrolladores, técnicos y otras personas con conocimientos avanzados de codificación.

RESUMEN

La función Cargo por ID de transacción anterior permite a los comerciantes ofrecer a los consumidores nuevas transacciones sin cancelar su suscripción original. Debido a que esta función no requiere que el consumidor vuelva a ingresar la información de pago en un formulario de pago de CCBill, el cliente es responsable de alojar los términos de la oferta.

El cobro por ID de transacción anterior no requiere que la oferta esté configurada previamente en el sistema de CCBill. Las ofertas se crean dinámicamente pasando variables al gestión de suscripciones.cgi guión, como se explica a continuación.

El sistema admite transacciones con tarjeta de crédito con y sin 3DS información de autenticación, así como Transacciones ACH.

Además de crear nuevas transacciones en otras subcuentas dentro de la misma cuenta principal, también puede usar el newClientAcccnumy nuevoClienteSubacc parámetros para crear transacciones en cuentas y subcuentas comerciales completamente diferentes.

Si está interesado en esta función, póngase en contacto con merchandisingupport@ccbill.com para determinar si es candidato.

Función de controles de velocidad CCBill

CCBill Velocity Controls es una característica avanzada de la API de CCBill. Le permite limitar las transacciones de los consumidores por su número o monto dentro de un período de tiempo específico.

Las reglas se aplican a todos los tipos de pago y 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. De forma individual, permites que los buenos clientes fieles sigan comprando más allá de los límites establecidos.

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

Para cobrar a los consumidores con una identificación de transacción anterior, los comerciantes deben usar una cadena de consulta para pasar variables a los sistemas de CCBill. Las solicitudes que contienen parámetros obligatorios y opcionales deben enviarse al siguiente script CGI:

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

Se cobrará al consumidor en espera de la validación de CCBill. Dependiendo del resultado de la validación, se devolverán resultados diferentes. Los resultados se pueden devolver en formato de valores separados por comas (CSV) o en formato XML.

Los comerciantes también pueden enviar información de 3DS SCA utilizando el chargeByPreviousTransactionId3DS función y parámetros asociados. CCBillis va a realizar la validación y procesar la transacción para cobrar al consumidor.

Explicaciones de campo (sin información de 3DS)

Para realizar un Cargo por transacción anterior, pase los siguientes parámetros y valores asociados a CCBill facturaciónApi:

PARÁMETROTIPO DE DATOS
(Longitud máxima)
DESCRIPCIÓN
Térmica
(requerido)
Función a realizar dentro de la API de CCBill.
Valor: CargoBypreviousTransactionId
ID de suscripción
(requerido)
entero
(20)
ID único de la transacción original del consumidor.
Valor de ejemplo: 0108113201000024660
clienteAccnum
(requerido)
entero
(6)
El número de cuenta comercial de CCBill de seis dígitos.
Valor de ejemplo: 900000
clienteSubacc
(requerido)
entero
(4)
El número de subcuenta de cuatro dígitos con el que está relacionada la suscripción. Se le autenticará en la subcuenta específica si se proporciona este parámetro y no en la cuenta principal. La acción debe pertenecer a esta subcuenta; de lo contrario, fallará.
Valor de ejemplo: 0000
usandoSubacc
(opcional)
entero
(4)
El parámetro especifica una subcuenta en la que se realizará una operación solicitada. Utilice este parámetro si desea autenticarse en la cuenta principal pero no en una subcuenta específica.
nombre de usuario
(requerido)
cadena
(8)
del comerciante Enlace de datos nombre de usuario
Valor de ejemplo: testuser
la contraseña
(requerido)
cadena
(8)
Contraseña de enlace de datos del comerciante.
Valor de ejemplo: prueba de paso
newClientAcccnum (requerido)entero
(6)
El número de cuenta de cliente de CCBill de seis dígitos para el nuevo cargo. Puede ser lo mismo que clientAccnum.
Valor de ejemplo: 900000
nuevoClienteSubacc (requerido)entero
(4)
El número de subcuenta de cliente de CCBill de cuatro dígitos para el nuevo cargo. Puede ser lo mismo que clientSubacc.
Valor de ejemplo: 0000
autenticación compartida (requerido)booleanoIndica si se utiliza la autenticación compartida; un valor de 1 significa que las cuentas de origen y de destino utilizan el mismo archivo de contraseñas y la misma base de datos. un valor de 0 significa que no se utiliza la autenticación compartida.
código de moneda
(opcional)
entero
(3)
Código de moneda de tres dígitos para la moneda
utilizado en la transacción. Si se omite, la transacción se procesa en dólares estadounidenses (USD) de forma predeterminada.
Valor de ejemplo: 840
precio inicial
(requerido)
flotante (decimal)Precio de transacción inicial.
Valor de ejemplo: 5.00
periodo inicial
(requerido)
enteroLa duración (en días) del período de facturación inicial.
Valor de ejemplo: 30
Precio recurrente
(requerido)
flotar
(decimal)
El monto que se le cobrará al consumidor por cada factura recurrente. Para transacciones de facturación única, establezca este valor igual a 0
Valor de ejemplo: 29.95
período recurrente
(requerido)
enteroEl tiempo entre refacturaciones. Para transacciones de facturación única, establezca este valor igual a 0
Valor de ejemplo: 30
refacturaciones
(requerido)
enteroEl número total de veces que se volverá a facturar la suscripción. Para refacturaciones ilimitadas, establezca este valor igual a 99. Para transacciones de facturación única, establezca este valor igual a 0
LifeTimeSubscription (opcional)booleanoLa presencia de esta variable con un valor de 1 indica que la transacción es una suscripción de por vida.
retornoXML
(opcional)
booleano
(Requerido si XML está habilitado).
Si este parámetro se pasa con el valor 1, recibirá la respuesta en formato XML; de lo contrario, la información se devuelve en formato CSV (valores separados por comas).
anularAfiliado
(opcional)
enteroAnular el afiliado (LAS solamente) el pago de las actualizaciones. A 0 value le dice al sistema que no acredite a los afiliados. Se puede pasar una ID de Afiliado válida para especificar el Afiliado que debe recibir el crédito, o el parámetro puede estar ausente. Un parámetro en blanco o una ID de afiliado no válida genera un mensaje de error.
anular la participación
(opcional)
enteroUsado con Conexión comercial para anular el pago del afiliado en las actualizaciones. los 0 value le dice al sistema que no acredite a ningún afiliado. Un PPID válido indica el Afiliado que debe recibir el crédito, o el parámetro puede estar ausente. Un parámetro en blanco o una ID de afiliado no válida genera un mensaje de error.

Ejemplo de versión de CVS

Solicitar cadena

https://bill.ccbill.com/jpost/billingApi.cgi?clientAccnum=900000&username=testuser&password=testpass&action=chargeByPreviousTransactionId&newClientAccnum=900000&newClientSubacc=0001&sharedAuthentication=1&initialPrice=5.00&initialPeriod=30&recurringPrice=29.95&recurringPeriod=30&rebills=99&subscriptionId=0108113201000024660&currencyCode=840

Resultados enviados (para transacciones aprobadas)

Fields: "approved", "subscriptionId" 
Values: "1", "100000000000000000"

Resultados enviados (para transacciones denegadas)

Fields: "approved", "denialId", "declineCode", "declineText" 
Values: "0", "100000000000000000", "15", "declined by bank"

Resultados enviados (cuando ocurre un error)

Fields: "results" 
Values: "-1"

Ejemplo de versión XML

Solicitar cadena

https://bill.ccbill.com/jpost/billingApi.cgi??clientAccnum=900000&username=testuser&password=testpass&action=chargeByPreviousTransactionId&newClientAccnum=900000&newClientSubacc=0000&sharedAuthentication=1&initialPrice=5.00&initialPeriod=30&recurringPrice=29.95&recurringPeriod=30&rebills=99&subscriptionId=0108113201000024660&returnXML=1

Resultados enviados (para transacciones aprobadas)

<?xml version='1.0' standalone='yes'?> 
<results> 
<approved>1</approved> 
<subscriptionId>100000000000000000</subscriptionId> 
</results>

Resultados enviados (para transacciones denegadas)

<?xml version='1.0' standalone='yes'?> 
<results> 
<approved>0</approved> 
<denialId>100000000000000000</denialId> 
<declineCode>15</declineCode> 
<declineText> declined by bank </declineText> 
</results>

Resultados enviados (cuando ocurre un error)

<?xml version='1.0' standalone='yes'?> 
<results>-1</results>

Explicaciones de campo (incluida la información de 3DS)

Pase los siguientes parámetros al facturaciónApi para realizar una función de Cargo por ID de transacción anterior que incluye información de 3DS:

PARÁMETROTIPO DE DATOS
(Longitud máxima)
DESCRIPCIÓN
Térmica
(requerido)
Función a realizar dentro de la API de CCBill.
Valor: CargoBypreviousTransactionId
ID de suscripción
(requerido)
entero
(20)
ID único de la transacción original del consumidor.
Valor de ejemplo: 921201201000001032
clienteAccnum
(requerido)
entero
(6)
El número de cuenta comercial de CCBill de seis dígitos.
Valor de ejemplo: 900000
clienteSubacc
(requerido)
entero
(4)
El número de subcuenta de cuatro dígitos con el que está relacionada la suscripción. Se le autenticará en la subcuenta específica si se proporciona este parámetro y no en la cuenta principal. La acción debe pertenecer a esta subcuenta; de lo contrario, fallará.
Valor de ejemplo: 0000
usandoSubacc
(opcional)
entero
(4)
El parámetro especifica una subcuenta en la que se realizará una operación solicitada. Utilice este parámetro si desea autenticarse en la cuenta principal pero no en una subcuenta específica.
nombre de usuario
(requerido)
cadena
(8)
del comerciante Enlace de datos nombre de usuario
Valor de ejemplo: testuser
la contraseña
(requerido)
cadena
(8)
Contraseña de enlace de datos del comerciante.
Valor de ejemplo: prueba de paso
newClientAcccnum (requerido)entero
(6)
El número de cuenta de cliente de CCBill de seis dígitos para el nuevo cargo. Puede ser lo mismo que clientAccnum.
Valor de ejemplo: 900000
nuevoClienteSubacc (requerido)entero
(4)
El número de subcuenta de cliente de CCBill de cuatro dígitos para el nuevo cargo. Puede ser lo mismo que clientSubacc.
Valor de ejemplo: 0000
autenticación compartida (requerido)booleanoIndica si se utiliza la autenticación compartida; un valor de 1 significa que las cuentas de origen y de destino utilizan el mismo archivo de contraseñas y la misma base de datos. un valor de 0 significa que no se utiliza la autenticación compartida.
código de moneda
(opcional)
entero
(3)
Código de moneda de tres dígitos para la moneda
utilizado en la transacción. Si se omite, la transacción se procesa en dólares estadounidenses (USD) de forma predeterminada.
Valor de ejemplo: 840
precio inicial
(requerido)
flotante (decimal)Precio de transacción inicial.
Valor de ejemplo: 5.00
periodo inicial
(requerido)
enteroLa duración (en días) del período de facturación inicial.
Valor de ejemplo: 30
Precio recurrente
(requerido)
flotar
(decimal)
El monto que se le cobrará al consumidor por cada factura recurrente. Para transacciones de facturación única, establezca este valor igual a 0
Valor de ejemplo: 29.95
período recurrente
(requerido)
enteroEl tiempo entre refacturaciones. Para transacciones de facturación única, establezca este valor igual a 0
Valor de ejemplo: 30
refacturaciones
(requerido)
enteroEl número total de veces que se volverá a facturar la suscripción. Para refacturaciones ilimitadas, establezca este valor igual a 99. Para transacciones de facturación única, establezca este valor igual a 0
LifeTimeSubscription (opcional)booleanoLa presencia de esta variable con un valor de 1 indica que la transacción es una suscripción de por vida.
retornoXML
(opcional)
booleano
(Requerido si XML está habilitado).
Si este parámetro se pasa con el valor 1, recibirá la respuesta en formato XML; de lo contrario, la información se devuelve en formato CSV (valores separados por comas).
anularAfiliado
(opcional)
enteroAnular el afiliado (LAS solamente) el pago de las actualizaciones. A 0 value le dice al sistema que no acredite a los afiliados. Se puede pasar una ID de Afiliado válida para especificar el Afiliado que debe recibir el crédito, o el parámetro puede estar ausente. Un parámetro en blanco o una ID de afiliado no válida genera un mensaje de error.
anular la participación
(opcional)
enteroUsado con Conexión comercial para anular el pago del afiliado en las actualizaciones. los 0 value le dice al sistema que no acredite a ningún afiliado. Un PPID válido indica el Afiliado que debe recibir el crédito, o el parámetro puede estar ausente. Un parámetro en blanco o una ID de afiliado no válida genera un mensaje de error.
threedsClientTransactionId
(requerido)
cadena
(36)
tresdsCantidad
(requerido)
flotar
(decimal)
La cantidad a cobrar (igual que precio inicial).
Valor de ejemplo: 3.00
tresdsCardToken
(opcional)
cadena
(16)
Número de tarjeta de crédito.
Valor de ejemplo: 4111111111111111
versión de threeds
(opcional)
number
(20)
La versión del protocolo 3DS que se seguirá para esta tarjeta y transacción específicas.
Las versiones disponibles son 1.0.2 y 2.1.0
tresdsmoneda
(opcional)
entero
(3)
El código de moneda de 3 dígitos para la moneda que se utilizará en esta transacción.
Valor de ejemplo: 840
estado de tresds
(opcional)
personaje
(1)
El estado de la verificación 3DS ('Y','N','A', etc.)
tresdséxito
(opcional)
booleanoVerificación de éxito o fracaso.
tipo de autenticación de threeds
(opcional)
cadena
(36)
Una firma digital que prueba que la transacción ha sido verificada en 3DS. La firma se obtiene a través de un flujo de verificación 3DS (v2.1).
valor de autenticación de threeds
(opcional)
cadena
(256)
Una firma digital que prueba que la transacción ha sido verificada en 3DS. La firma se obtiene a través de un flujo de verificación 3DS (v2.1).
tresdscavv
(opcional)
cadena
(256)
Una firma digital que prueba que la transacción ha sido verificada en 3DS. La firma se obtiene a través de un flujo de verificación 3DS (v1.0.2).
algoritmo threedsCavv
(opcional)
cadena
(10)
Una firma digital que prueba que la transacción ha sido verificada en 3DS. La firma se obtiene a través de un flujo de verificación 3DS (v1.0.2).
tresdsEci
(requerido)
entero
(2)
Un Indicador de Comercio Electrónico (ECI).
Valores: '0','1','2','5','6', o'7'.
tresdsDsTransId
(opcional)
cadena
(36)
ID de transacción del servidor de directorio.
tresdsAcsTransId
(opcional)
cadena
(36)
ID de transacción del servidor de control de acceso.
tresdsSdkTransId
(opcional)
cadena
(36)
El ID de transacción del proveedor de 3DS.
tresdsXid
(opcional)
cadena
(50)
El identificador de la transacción (XID) es un número de seguimiento único establecido por el comerciante para 3DS 1.0. Base codificada 64.
tresdsError
(opcional)
cadena
(256)
Error recibido del proveedor de 3DS durante el proceso de autenticación sólida del cliente.
tresdsErrorDetalle
(opcional)
cadena
(256)
Detalles del error relacionados con el tresdsError.
tresdsErrorCode
(opcional)
cadena
(10)
Código de error.
respuesta de tresds
(opcional)
cadena
(400)
La respuesta completa en caso de error.

Ejemplo CSV

Solicitar cadena

https://bill.ccbill.com/jpost/billingApi.cgi?action=chargeByPreviousTransactionId3DS&subscriptionId=921201201000001032&clientAccnum=900000&clientSubacc=0000&newClientAccnum=900000&newClientSubacc=0000&username=testuser&password=testpass&sharedAuthentication=1&currencyCode=840&initialPrice=3.00&initialPeriod=30&recurringPrice=29.95&recurringPeriod=30&rebills=99&lifetimeSubscription=0&threedsClientTransactionId=idtestCase1&threedsAmount=3.00&threedsCardToken=4111111111111111&threedsVersion=1.0.2&threedsCurrency=840&threedsStatus=Y&threedsSuccess=1&threedsCavv=cGFzc3dvcmQxMjM0NTZwYXNzd28=&threedsCavvAlgorithm=SHA-256&threedsEci=02&threedsXid=aWQteWo4M3lnb21xZCAgICAgICA=&threedsSdkTransId=testSdkTransId&threedsAcsTransId=testAcsTransId&threedsDsTransId=testDsTransId

Resultados enviados (para transacciones aprobadas)

Fields: "approved", "subscriptionId" 
Values: "1", "100000000000000000"

Resultados enviados (para transacciones denegadas)

Fields: "approved", "denialId", "declineCode", "declineText" 
Values: "0", "100000000000000000", "15", "declined by bank"

Resultados enviados (cuando ocurre un error)

Fields: "results" 
Values: "-1"

Ejemplo de versión XML

Solicitar cadena

https://bill.ccbill.com/jpost/billingApi.cgi?action=chargeByPreviousTransactionId3DS&subscriptionId=921201201000001032&clientAccnum=900000&clientSubacc=0000&newClientAccnum=900000&newClientSubacc=0000&username=testuser&password=testpass&sharedAuthentication=1&currencyCode=840&initialPrice=3.00&initialPeriod=30&recurringPrice=29.95&recurringPeriod=30&rebills=99&lifetimeSubscription=0&threedsClientTransactionId=idtestCase1&threedsAmount=3.00&threedsCurrency=840&threedsEci=02&returnXML=1

Resultados enviados (para transacciones aprobadas)

<?xml version='1.0' standalone='yes'?> 
<results> 
<approved>1</approved> 
<subscriptionId>100000000000000000</subscriptionId> 
</results>

Resultados enviados (para transacciones denegadas)

<?xml version='1.0' standalone='yes'?> 
<results> 
<approved>0</approved> 
<denialId>100000000000000000</denialId> 
<declineCode>15</declineCode> 
<declineText> declined by bank </declineText> 
</results>

Resultados enviados (cuando ocurre un error)

<?xml version='1.0' standalone='yes'?> 
<results>-1</results>

Códigos de error

Para obtener una lista completa de códigos de error y explicaciones, consulte el Guía de la API de CCBill.

Buenas Prácticas

API de 1 clic de CCBill permitir a los comerciantes ofrecer a sus consumidores una conveniente solución de facturación de actualización. Los consumidores no tienen que volver a ingresar sus detalles de pago en compras posteriores. Las API son administradas por el comerciante y los consumidores inician transacciones dentro del sitio web del comerciante o del área de miembros. Si bien estas pueden ser herramientas muy convenientes y valiosas, no vienen sin riesgo añadido. El comerciante debe administrar gran parte de la experiencia del consumidor, y las API están diseñadas para eludir el sistema de autenticación de CCBill, V-Scrub.

Como resultado, el comerciante debe comprender sus responsabilidades e implementar 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 único y los controles que implementan pueden diferir, los siguientes y las mejores prácticas guiar a 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 y 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: se debe notificar inmediatamente al consumidor sobre la aprobación/denegación 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 en su cuenta con solo hacer clic en un botón. Además de mensajes claros, algunos comerciantes pueden querer asegurarse de que sus clientes puedan optar por participar y optar por 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 instruir 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 debe reforzar 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 determinado. Por ejemplo, a un cliente nuevo solo se le debe permitir realizar 4 transacciones dentro de los 30 días iniciales.
    • 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.
    • Retrasa los pagos con nuevos afiliados/fuentes de tráfico para garantizar que las transacciones puedan revisarse antes de pagar al afiliado. Si se detectan patrones de alto riesgo, retrase el pago para garantizar que se puedan liquidar los reembolsos y las devoluciones de cargo.
      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.
    • Retrasa los pagos con nuevas fuentes de modelos/estudios de cámaras para revisar las transacciones antes de pagar al afiliado. Si se detectan patrones de alto riesgo, retrase el pago para asegurarse de que se puedan liquidar los reembolsos y las devoluciones de cargo. Esto puede tomar hasta 120 días
  5. Monitoreo posterior a la transacción: El comerciante debe verificar a un consumidor si se detectan 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 compararlos con IP de compra. Las diferencias deben considerarse de alto riesgo.
    • Cantidades altas en dólares gastado en períodos más cortos debe ser revisado para garantizar la legitimidad.