Guía Técnica para Crear y Cobrar Tokens de Pago

Esta guía técnica describe los pasos para crear y cargar fichas de pago utilizando el servicio API RESTful de transacciones de CCBill.

Está destinado a programadores, técnicos y otras personas con conocimientos avanzados de codificación.

Requisitos

Terminología

• Cuenta comercial: Cada comerciante de CCBill recibe 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 seis (6) dígitos. Por ejemplo: "999999".
• Subcuenta comercial: Los comerciantes de CCBill pueden abrir una o más subcuentas. La subcuenta es un número de cuatro (4) dígitos. El formato estándar es: xxxx. Por ejemplo: "1234". La subcuenta es parte de la cuenta principal.
• Ficha de pago: Un token de pago identifica una entidad facturable dentro del sistema.
• Identificación de suscripción: Número de identificación de la suscripción a la transacción
• Identificación de la aplicación del comerciante: Esta es la ID de cliente que el comerciante recibió al registrarse para usar la API RESTful de CCBill.
• Secreto del comerciante: Esta es la contraseña que se configuró para la autenticación con la API RESTful de CCBill.
• Autenticación fuerte del cliente (SCA): leyes europeas (PSD2) requieren el uso de SCA, como el 3DS protocolo, para el procesamiento de pagos en línea. La SCA se inicia cuando un titular de tarjeta con sede en la UE realiza un pago en línea. Los comerciantes pueden usar el Widget avanzado de CCBill y sus funciones para facilitar una fuerte autenticación del cliente.

El flujo de pago

A continuación se detallan los 3 pasos esenciales para cobrar al consumidor mediante un token de pago:

1. Genere el token de portador CCBill OAuth

2. Crear el token de pago

3. Cobrar el token de pago

El siguiente diagrama de secuencia describe el flujo para crear y cobrar tokens de pago sin verificación 3DS. Haga clic en la imagen para verla en tamaño completo.

---

Si bien todos los pasos anteriores se pueden completar realizando solicitudes desde su backend a nuestros puntos finales de API, también puede usar el Widget avanzado de CCBill (biblioteca JS) a:

• crear los tokens de pago
• comprobar si se requiere la verificación 3DS o no, y
• realizar una autenticación fuerte del cliente (SCA) desde el navegador

El siguiente diagrama de secuencia describe el flujo para crear y cargar tokens de pago con verificación 3DS. Haga clic en la imagen para verla en tamaño completo.

---

Creación de la CCBill OAuth token y tokens de pago de carga no son compatibles con el Widget avanzado de CCBill y debe realizarse haciendo llamadas a la API desde sus servicios de back-end.

1. Generar token de portador CCBill OAuth

La API de transacción RESTful de CCBill utiliza OAuth autenticación y autorización basadas. Antes de acceder a la API, debe registrar su aplicación con CCBill para recibir un ID de aplicación de comerciante y llave secreta.

Utilice estas credenciales para generar un token al proporcionarlas al servidor de autorización.

Una vez que haya generado un token de acceso (que no debe confundirse con un token de pago), proporciónelo en el encabezado de Autorización de cada solicitud de API. Tendrá acceso hasta que el token de acceso caduque o sea revocado.

URL de punto final

https://api.ccbill.com/ccbill-auth/oauth/token?grant_type=client_credentials

Encabezamiento

Content-Type: application/x-www-form-urlencoded

Authorization: Basic MerchantApplicationID:SecretKey

curl -X POST \

https://api.ccbill.com/ccbill-auth/oauth/token \

--header 'Content-Type: application/x-www-form-urlencoded' \

--header 'Authorization: Basic Merchant_ApplicationID:Merchant_Secret ' \

--data-urlencode 'grant_type=client_credentials'

El token adquirido es una cadena de datos aleatorios que no contiene información o valor confidencial. Es una herramienta de autenticación y autorización que otorga a sus aplicaciones acceso a los recursos de la API RESTful de CCBill.

Ejemplo de token de portador en el encabezado de la solicitud

  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibWNuLXRyYW5zYWN0aW9uLXNlcnZpY2UiLCJtY24tYWRtaW4tc2VydmljZSJdLCJzY29wZSI6WyJjcmVhdGVfdG9rZW4iLCJyZWFkX3Rva2VuIiwiY2hhcmdlX3Rva2VuIiwiY3JlYXRlX3Byb2dyYW0iLCJyZWFkX3Byb2dyYW0iLCJjcmVhdGVfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIiwicmVhZF9wcm9ncmFtX3BhcnRpY2lwYXRpb24iLCJtb2RpZnlfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIl0sImV4cCI6MTUzNzM4MDczNiwiYXV0aG9yaXRpZXMiOlsiTUNOX0FQSV9UT0tFTl9DSEFSR0VSIiwiTUNOX0FQSV9UT0tFTl9DUkVBVE9SIiwiTUNOX0FQSV9BRE1JTiJdLCJqdGkiOiI4YzI2Njg1MC00NjMzLTQzZDMtYjZjOC1lNzIyY2ExNjQ1YTUiLCJjbGllbnRfaWQiOiI1MjE3NjhhYTc1OGQxMWU4YWE2YjAwNTA1NjlkMTU4NSJ9.HRYXZFATkIcI2_LJ1W_xo67IfBnbN9atyYNzyHqseLxYUxzgwBsAV5rNqCixKemOrDIeQLBN4jrwRsBIHDpEvshwBC8XmTodDJzpGmMaU9s1r20RV68X0_d1yTgSDke_Of7VCrVmJRbSuDl7AgsfTqQ1J7nWyu9vcIaER93ms-vadser_Ot9Z68_HAmCJL3DCLpdIFq3PYtBMKKKqXbvhfhSZQZD3b6-aewAnBo0VzpvK6tREqw1rv9_73oAvYcW2aHAj79ILr8viWMM40LyDKMMYOYkneg3hJUQsUVeh9WzztYUJKzERYNXje9fYIGN-eofoLvX7OZJ3eXmIfkrfQ' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

2. Crear token de pago (Widget avanzado de CCBill)

El Widget avanzado de CCBill facilita la creación de tokens de pago al encapsular las llamadas API que deben realizarse en una función de JavaScript que se puede usar desde su página web.

La biblioteca está alojada en la red de distribución de contenido (CDN) de CCBill, lo que hace que la importación a los sitios web de los comerciantes sea rápida y sencilla desde cualquier lugar del mundo.

Las siguientes instrucciones describen cómo configurar y utilizar el Widget avanzado de CCBill biblioteca.

Paso 1. Agregar enlace precargado y elementos HTML

Agregue un enlace precargado y elementos HTML de secuencia de comandos a la página HTML del cliente que se conectará al widget avanzado de CCBill.

<link rel="preload" href="https://js.ccbill.com/v1.2.2/ccbill-advanced-widget.js" as="script"/>
<script type="text/javascript" src="https://js.ccbill.com/v1.2.2/ccbill-advanced-widget.js"></script>

Paso 2. Definir ID de campo

El widget avanzado puede extraer los campos de formulario relevantes basándose en los atributos de ID predeterminados o utilizando el atributo de elemento HTML personalizado data-ccbill. El data-ccbill Se recomienda el atributo ya que es menos intrusivo y proporciona más flexibilidad.

Cuando se usa el atributo personalizado, el formato correcto es:

Formato

<input type="text" data-ccbill="[corresponding field name]" />

Cuando se utilizan los ID predeterminados, el formato correcto es:

<input type="text" id="_ccbillId_[corresponding field name]" />

La tabla muestra los valores que se deben establecer para el data-ccbill atributo o, alternativamente, en los campos de atributos de ID predeterminados.

data-ccbill	ID predeterminados
nombre en la tarjeta	_ccbillId_nameOnCard
número de tarjeta	_ccbillId_cardNumber
expMes	_ccbillId_expMonth
expaño	_ccbillId_expYear
nombre de pila	_ccbillId_nombre
apellido	_ccbillId_apellido
address1 (opcional)	_ccbillId_dirección1 (opcional)
address2 (opcional)	_ccbillId_dirección2 (opcional)
ciudad (opcional)	_ccbillId_ciudad (opcional)
país	_ccbillId_país
estado (opcional)	_ccbillId_estado (opcional)
código postal	_ccbillId_postalCode
número de teléfono (opcional)	_ccbillId_phoneNumber (opcional)
correo electrónico,	_ccbillId_email
código de moneda (Un código de moneda de tres dígitos para la moneda utilizada en la transacción. Obligatorio para SCA).	_ccbillId_currencyCode (Un código de moneda de tres dígitos para la moneda utilizada en la transacción. Obligatorio para SCA).
dirección IP (opcional, campo oculto recomendado autocompletado por JavaScript)	_ccbillId_ipAddress (opcional, campo oculto recomendado autocompletado por JavaScript)
navegadorHttpAceptar (opcional, campo oculto recomendado autocompletado por JavaScript)	_ccbillId_browserHttpAceptar (opcional, campo oculto recomendado autocompletado por JavaScript)
browserHttpAcceptEncoding (opcional, campo oculto recomendado autocompletado por javascript)	_ccbillId_browserHttpAcceptEncoding (opcional, campo oculto recomendado autocompletado por javascript)
navegadorHttpAceptarIdioma (opcional, campo oculto recomendado autocompletado por javascript)	_ccbillId_browserHttpAceptarIdioma (opcional, campo oculto recomendado autocompletado por javascript)

Paso 3. Crear método JavaScript

Cree un método de JavaScript que llamará al widget avanzado de CCBill crearPagoToken() función. El ejemplo proporcionado se puede modificar según sea necesario.

Esta es la función principal que los comerciantes deben incorporar en sus llamadas de JavaScript para crear Tokens de pago.

Para generar un token, se deben pasar varios parámetros mediante la función:

PARÁMETRO	TIPO	DESCRIPCIÓN
token de autorización	cadena (requerido)	Entrada requerida que utiliza un token de Oauth para realizar la creación del token de pago. Debe ser un token de Oauth válido para la cuenta de cliente proporcionada.
clienteAccnum	entero (requerido)	Número de cuenta mercantil.
clienteSubacc	entero (requerido)	Número de subcuenta de comerciante.
clearPaymentInfo	booleano (opcional)	Un indicador opcional que, si se establece en verdadero, dará como resultado la eliminación de los campos de información del cliente cuando el crear el token de pago se llama a la función. Si nulo se proporciona, por defecto será falso y los campos de información de pago no se borrarán. Nota: Aunque este parámetro es opcional, este campo debe establecerse en 'nulo' si no se usa.
clearCustomerInfo	booleano (opcional)	Un indicador opcional que, si se establece en verdadero, dará como resultado la eliminación de los campos de información del cliente cuando el crear el token de pago se llama a la función. Si nulo se proporciona, por defecto será falso y los campos de información del cliente no se borrarán. Nota: Aunque este parámetro es opcional, este campo debe establecerse en 'nulo' si no se usa.
tiempo para vivir	entero (opcional)	El intervalo de tiempo que define cuánto tiempo debe ser válido el token (horas).
numeroDeUso	entero (opcional)	Número total de veces que se puede usar el token de pago para compras. Nota: Aunque este parámetro es opcional, este campo debe establecerse en 'nulo' si no se usa.

const widget = new ccbill.CCBillAdvancedWidget(applicationId);
try {
       const result = widget.createPaymentToken(oauthToken, clientAccnum, clientSubacc, clearPaymentInfo, clearCustomerInfo, timeToLive, numberOfUse);
       result.then(
           (data) => {
               console.log("SUCCESS");
               return data.json();
           },
           (error) => {
               console.log("ERROR");
               return error.json();
           }).then(json => {                
               console.log("RESULT :[" + JSON.stringify(json) + "]");
           }).catch((error) => {
           console.error("ERROR2 [" + error + "]");
       });
       console.log(`FINISHED`);
   } catch (error) {
       const errors = [];
       error.forEach(function(item) {
         const msg = item.message.split(".");
         errors.push(msg[1]);
       });
       console.error(`ERROR ` + JSON.stringify(errors));
       alert("ERROR: Unable to generate Payment Token: " + JSON.stringify(errors));
   }

const result = widget.createPaymentToken(oauthToken, clientAccnum, clientSubacc);

const result = widget.createPaymentToken(oauthToken, clientAccnum, clientSubacc, clearPaymentInfo, clearCustomerInfo);

const result = widget.createPaymentToken(oauthToken, clientAccnum, clientSubacc, null, null, timeToLive, numberOfUse);

const result = widget.createPaymentToken(oauthToken, clientAccnum, clientSubacc, clearPaymentInfo, clearCustomer, timeToLive, numberOfUse);

Paso 4. Token de pago generado

El resultado contendrá el token de pago recién creado, que se puede convertir en JSON.

En caso de cualquier entrada no válida, la respuesta incluirá errores de validación que se encontraron durante la validación de la entrada.

También puede incluir cualquier error que haya ocurrido durante el proceso de generación del token de pago.

Validación de datos de campo

El crear el token de pago La función validará los valores de los campos. Si alguno de los valores no pasa la validación, no se creará ningún token. Si ese es el caso, el sistema generar una matriz de violaciones indicando qué campos no son válidos.

PARÁMETRO	TIPO	REQUISITO
clienteAccnum	entero (requerido)	Número de cuenta mercantil. Un rango entre 90000 y 999999 y debe ser un número.
clienteSubacc	entero (requerido)	Número de subcuenta de comerciante. Un rango de 0-9999 y debe ser un número.
tiempo para vivir	entero (opcional)	Tiene un rango de 0-2147483647 y debe ser un número. Si se desea el valor máximo, omita esto (o pase nulo).
numeroDeUso	entero (opcional)	El número total de veces que se puede usar el token de pago para compras. Tiene un rango de 0-2147483647 y debe ser un número. Si se desea el valor máximo, omita esto (o pase nulo).
número de tarjeta	cadena (requerido)	Debe ser un número de tarjeta de crédito válido.
expMes	cadena (requerido)	Mes de caducidad de la tarjeta en mm formato. Se requiere un rango de 1-12, y debe ser un número.
expaño	cadena (requerido)	Año de caducidad de la tarjeta en aaaa formato. Se requiere un rango de 2018-2100, y debe ser un número.
nombre de pila	cadena (requerido)	Nombre del cliente.
apellido	cadena (requerido)	Apellido del cliente.
address1	cadena (opcional)	Dirección del cliente.
ciudad	cadena (opcional)	Ciudad del cliente.
país	cadena (requerido)	País del cliente. Debe estar representado como un código de país de dos letras como se define en ISO-3166 1.
estado	cadena (opcional)	Estado del cliente. Si se proporciona, debe ser un código de estado de dos letras como se define en ISO-3166 2.
código postal	cadena (requerido)	Código postal del cliente. Es un código postal válido para el país proporcionado.
número de teléfono	cadena (opcional)	Número de teléfono del cliente. Si se proporciona, debe ser un número de teléfono válido.
correo electrónico,	cadena (requerido)	Dirección de correo electrónico del cliente.
dirección IP	cadena (opcional)	Dirección IP del cliente.

{
  target: Object,
  message: string,
  propertyName: string
}

En este momento, la página del cliente deberá resolver cualquier error, mostrar el mensaje correcto en el que los campos no eran válidos o usar el nuevo token de pago provisto.

Autenticación fuerte del cliente

CCBill Advanced Widget también permite a los comerciantes integrarse con el proveedor 3DS de CCBill e incorporar una fuerte autenticación de clientes en sus transacciones.

Como alternativa, los comerciantes pueden enviar los resultados de SCA (3DS) obtenidos de un proveedor de 3DS de su elección. Para iniciar cargos con un token de pago, los parámetros SCA deben enviarse junto con otros parámetros obligatorios.

isScaFunción requerida

El isScaRequerido determina si se necesita una fuerte autenticación del cliente. El sistema verifica el número de tarjeta de crédito, el número de cuenta del comerciante, el número de subcuenta y el código de moneda proporcionados.

Una entrada válida da como resultado una Promesa, que eventualmente se resolverá en una respuesta con parámetros SCA o se convertirá en un rechazo, debido a un error.

Ejemplo

const result = widget.isScaRequired(authToken, clientAccnum, clientSubacc);

PARÁMETRO	TIPO	DESCRIPCIÓN
token de autorización	cadena (requerido)	Debe ser un token de Oauth válido para la cuenta de comerciante proporcionada.
clienteAccnum	entero (requerido)	Número de cuenta mercantil.
clienteSubacc	entero (requerido)	Número de subcuenta de comerciante.

El formulario de pago del comerciante debe contener un campo de entrada de texto (oculto si es necesario) o un elemento de selección (oculto si es necesario) para el código de moneda valor. El valor representa un código de moneda de tres dígitos (norma ISO 4217) para la moneda utilizada en la transacción.

El widget avanzado recopilará automáticamente la código de moneda valor si sigue las convenciones de nomenclatura estándar. Los comerciantes pueden:

• Utilice el atributo de ID predeterminado.
• Especifique el ID del código de moneda utilizando la biblioteca.
• Utilice la data-ccbill atributo para especificar el campo de código de moneda.

data-ccbill ejemplo de atributo (entrada)

<input data-ccbill="currencyCode" type="text" />

data-ccbill ejemplo de atributo (seleccionar)

<select data-ccbill="currencyCode" />

<option>…</option>
<option>…</option>
…

</select>

Predeterminado _ccbillId_currencyCode ejemplo de atributo (entrada)

<input id="_ccbillId_currencyCode" type="text" />

Predeterminado _ccbillId_currencyCode ejemplo de atributo (seleccionar)

<select id="_ccbillId_currencyCode" />

<option>…</option>
<option>…</option>
…

</select>

Validación de datos de campo

PARÁMETRO	TIPO	DESCRIPCIÓN
clienteAccnum	entero (requerido)	Tiene un rango de 900000-999999 y debe ser un número.
clienteSubacc	entero (requerido)	Tiene un rango de 0-9999 y debe ser un número.
código de moneda	entero (requerido)	Tiene que coincidir con la expresión regular ^ \\ d {3} $
Número de tarjeta de crédito (entrada de formulario)	entero (requerido)	Debe ser un número de tarjeta de crédito válido.

El objeto de violaciones es una matriz del siguiente objeto:

{
  target: Object,
  message: string,
  propertyName: string
}

Función isScaRequiredForPaymentToken

El isScaRequiredForPaymentToken La función determina si se requiere una autenticación fuerte del cliente. basado en la ID del token de pago proporcionado y el código de moneda.

Una entrada válida da como resultado una Promesa, que eventualmente se resolverá en una respuesta con parámetros SCA o se convertirá en un rechazo, debido a un error.

PARÁMETRO	TIPO	DESCRIPCIÓN
token de autorización	cadena (requerido)	Debe ser un token de Oauth válido para la cuenta de comerciante proporcionada.
Id. de token de pago	cadena (requerido)	El identificador del token de pago. Una cadena única que identifica el token de pago, debe coincidir con la expresión regular <strong><em>[a-zA-Z0-9]+$</em></strong>

Ejemplo

const result = widget.isScaRequiredForPaymentToken(authToken, paymentTokenId);

El formulario de pago del comerciante debe contener un campo de entrada de texto o un elemento de selección para el código de moneda valor. El valor representa un código de moneda de tres dígitos (norma ISO 4217) para la moneda utilizada en la transacción.

El widget avanzado recopilará automáticamente la código de moneda valor si sigue las convenciones de nomenclatura estándar. Los comerciantes pueden:

• Utilice el atributo de ID predeterminado.
• Especifique el ID del código de moneda utilizando la biblioteca.
• Utilice la data-ccbill atributo para especificar el campo de código de moneda.

data-ccbill ejemplo de atributo (entrada)

<input data-ccbill=”currencyCode” type=”text” />

data-ccbill ejemplo de atributo (seleccionar)

<select data-ccbill=”currencyCode” />

<option>…</option>
<option>…</option>
…

</select>

Predeterminado _ccbillId_currencyCode ejemplo de atributo (entrada)

<input id=“_ccbillId_currencyCode” type=”text” />

Predeterminado _ccbillId_currencyCode ejemplo de atributo (seleccionar)

<select id=“_ccbillId_currencyCode” />

<option>…</option>
<option>…</option>
…

</select>

Validación de datos de campo

PARÁMETRO	TIPO	DESCRIPCIÓN
Id. de token de pago	cadena (requerido)	Debe coincidir con la expresión regular ^ [a-zA-Z0-9] + $
código de moneda	entero (requerido)	Tiene que coincidir con la expresión regular ^ \\ d {3} $

El objeto de violaciones es una matriz del siguiente objeto:

{
  target: Object,
  message: string,
  propertyName: string
}

función autenticarcliente

El autenticarCliente La función permite a los comerciantes obtener el resultado de la autenticación del cliente antes de iniciar una transacción 3DS y llamar al extremo de la API Merchant Connect (RESTful) de CCBill. Si la llamada falla, devolverá un error.

Se deben pasar varios parámetros para facilitar una autenticación sólida del cliente.

PARÁMETRO	TIPO	DESCRIPCIÓN
token de autorización	cadena (requerido)	Debe ser un token de Oauth válido para la cuenta de comerciante proporcionada.
formulario	cadena (opcional)	Una referencia de formulario debe ser un selector válido o un elemento de formulario HTML que exista en la página web del comerciante. Tenga en cuenta que si el no se proporciona formId, el widget encontrará el primer elemento HTML del formulario en la página y supondrá que ese es el formulario de pago.
iframeId	cadena (opcional)	El proceso de autenticación 3DS presenta un iframe en la página web para realizar su funcionalidad. El script Advanced Widget genera un iframe y lo inyecta en la página web del comerciante si el parámetro no está definido. Si el valor proporcionado es nulo o una cadena vacía, se regenera para ajustarse a los requisitos técnicos mínimos.
Id. de token de pago	cadena (opcional)	Utilice este campo opcional en lugar del número de tarjeta, el mes de vencimiento de la tarjeta y el año de vencimiento de la tarjeta. La información de la tarjeta debe estar presente en el formulario HTML asociado si no se proporciona la identificación del token.

Ejemplo usando solo los parámetros requeridos

const result = widget.authenticateCustomer(authToken);

Ejemplo usando formulario

const result = widget.authenticateCustomer(authToken, form);

Ejemplo usando iframeId y formulario

const result = widget.authenticateCustomer(authToken, form, iframeId);

Ejemplo usando todos los parámetros

const result = widget.authenticateCustomer(authToken, form, iframeId, paymentTokenId);

Validación de datos de campo

PARÁMETRO	TIPO	DESCRIPCIÓN
Id. de token de pago	cadena (requerido)	Debe coincidir con la expresión regular ^ [a-zA-Z0-9] + $
formulario	cadena (opcional)	Una referencia de formulario debe ser un selector válido o un elemento de formulario HTML que exista en la página web del comerciante. Si es no siempre, el sistema intentará recopilar las entradas SCA requeridas del primer formulario HTML que encuentre en la página.
iframeId	cadena (opcional)	El proceso de autenticación 3DS presenta un iframe en la página web para realizar su funcionalidad. El script Advanced Widget genera un iframe y lo inyecta en la página web del comerciante si el parámetro no está definido. Si el valor proporcionado es nulo o una cadena vacía, se regenera para ajustarse a los requisitos técnicos mínimos.

Visite el Códigos de error de autenticación de 3DS página para obtener una lista completa de códigos de error.

3. Cobrar token de pago

Después de generar un nuevo token de OAuth y después de generar un token de pago, puede usar esos dos tokens nuevos para cargar la tarjeta de crédito del consumidor.

Cobrar token de pago (sin autenticación 3DS)

URL de solicitud HTTP

https://api.ccbill.com/transactions/payment-tokens/{paymentTokenID}

Encabezamiento

Accept: application/vnd.mcn.transaction-service.api.v.1+json

Parámetros de solicitud

PARÁMETRO	TIPO	DESCRIPCIÓN
clienteAccnum	entero (requerido)	Número de cuenta mercantil.
clienteSubacc	entero (requerido)	Número de subcuenta de comerciante.
precio inicial	flotar (requerido)	Precio de transacción inicial.
periodo inicial	entero (requerido)	La duración (en días) del período de facturación inicial.
Precio recurrente	flotar (opcional)	El monto que se le cobrará al consumidor por cada factura recurrente.
período recurrente	entero (opcional)	El tiempo entre refacturaciones.
refacturaciones	entero (opcional)	El número total de veces que se volverá a facturar la suscripción.
código de moneda	entero (opcional)	Código de moneda de tres dígitos (norma ISO 4217) para la moneda utilizada en la transacción.
LifeTimeSubscription	booleano (opcional)	La presencia de esta variable con un valor de 1 indica que la transacción es una suscripción de por vida.
crear nuevo token de pago	booleano (opcional)	Devuelva un nuevo token de pago para transacciones posteriores o no.
passThroughInfo	Matriz [cualquiera] (opcional)	Pares clave/valor que se pueden pasar al servicio de transacciones y recibir en la respuesta del webhook.

curl -X POST \
  https://api.ccbill.com/payment-tokens/merchant-only \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibWNuLXRyYW5zYWN0aW9uLXNlcnZpY2UiLCJtY24tYWRtaW4tc2VydmljZSJdLCJzY29wZSI6WyJjcmVhdGVfdG9rZW4iLCJyZWFkX3Rva2VuIiwiY2hhcmdlX3Rva2VuIiwiY3JlYXRlX3Byb2dyYW0iLCJyZWFkX3Byb2dyYW0iLCJjcmVhdGVfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIiwicmVhZF9wcm9ncmFtX3BhcnRpY2lwYXRpb24iLCJtb2RpZnlfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIl0sImV4cCI6MTUzNzM4MDczNiwiYXV0aG9yaXRpZXMiOlsiTUNOX0FQSV9UT0tFTl9DSEFSR0VSIiwiTUNOX0FQSV9UT0tFTl9DUkVBVE9SIiwiTUNOX0FQSV9BRE1JTiJdLCJqdGkiOiI4YzI2Njg1MC00NjMzLTQzZDMtYjZjOC1lNzIyY2ExNjQ1YTUiLCJjbGllbnRfaWQiOiI1MjE3NjhhYTc1OGQxMWU4YWE2YjAwNTA1NjlkMTU4NSJ9.HRYXZFATkIcI2_LJ1W_xo67IfBnbN9atyYNzyHqseLxYUxzgwBsAV5rNqCixKemOrDIeQLBN4jrwRsBIHDpEvshwBC8XmTodDJzpGmMaU9s1r20RV68X0_d1yTgSDke_Of7VCrVmJRbSuDl7AgsfTqQ1J7nWyu9vcIaER93ms-vadser_Ot9Z68_HAmCJL3DCLpdIFq3PYtBMKKKqXbvhfhSZQZD3b6-aewAnBo0VzpvK6tREqw1rv9_73oAvYcW2aHAj79ILr8viWMM40LyDKMMYOYkneg3hJUQsUVeh9WzztYUJKzERYNXje9fYIGN-eofoLvX7OZJ3eXmIfkrfQ' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{ "clientAccnum": 900000, "clientSubacc": 0, "customerInfo": { "customerFname": "Tyler", "customerLname": "Thomas", "address1": "Woodland Drive", "address2": "Apt 21", "city": "Tempe", "state": "AZ", "zipcode": "85281", "country": "US", "phoneNumber": "5555555555", "email": "tthomas@xyz.com", "ipAddress": "10.70.60.14'\''", "browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0", "browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", "browserHttpAcceptLanguage": "en-US,en;q=0.5", "browserHttpAcceptEncoding": "gzip, deflate, br" }, "paymentInfo": { "creditCardPaymentInfo": { "cardNum": "4473707989493598", "nameOnCard": "Tyler Thomas", "expMonth": "04", "expYear": "2026" } }, "subscriptionId":900000000000000001, "timeToLive": 30, "validNumberOfUse": 3 }'

var data = JSON.stringify({
  "clientAccnum": 900000,
  "clientSubacc": 0,
  "customerInfo": {
    "customerFname": "Tyler",
    "customerLname": "Thomas",
    "address1": "Woodland Drive",
    "address2": "Apt 21",
    "city": "Tempe",
    "state": "AZ",
    "zipcode": "85281",
    "country": "US",
    "phoneNumber": "5555555555",
    "email": "tthomas@xyz.com",
    "ipAddress": "10.70.60.14'",
    "browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0",
    "browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "browserHttpAcceptLanguage": "en-US,en;q=0.5",
    "browserHttpAcceptEncoding": "gzip, deflate, br"
  },
  "paymentInfo": {
    "creditCardPaymentInfo": {
      "cardNum": "4473707989493598",
      "nameOnCard": "Tyler Thomas",
      "expMonth": "04",
      "expYear": "2026"
    }
  },
  "subscriptionId": 900000000000000000,
  "timeToLive": 30,
  "validNumberOfUse": 3
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.ccbill.com/payment-tokens/merchant-only");
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibWNuLXRyYW5zYWN0aW9uLXNlcnZpY2UiLCJtY24tYWRtaW4tc2VydmljZSJdLCJzY29wZSI6WyJjcmVhdGVfdG9rZW4iLCJyZWFkX3Rva2VuIiwiY2hhcmdlX3Rva2VuIiwiY3JlYXRlX3Byb2dyYW0iLCJyZWFkX3Byb2dyYW0iLCJjcmVhdGVfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIiwicmVhZF9wcm9ncmFtX3BhcnRpY2lwYXRpb24iLCJtb2RpZnlfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIl0sImV4cCI6MTUzNzM4MDczNiwiYXV0aG9yaXRpZXMiOlsiTUNOX0FQSV9UT0tFTl9DSEFSR0VSIiwiTUNOX0FQSV9UT0tFTl9DUkVBVE9SIiwiTUNOX0FQSV9BRE1JTiJdLCJqdGkiOiI4YzI2Njg1MC00NjMzLTQzZDMtYjZjOC1lNzIyY2ExNjQ1YTUiLCJjbGllbnRfaWQiOiI1MjE3NjhhYTc1OGQxMWU4YWE2YjAwNTA1NjlkMTU4NSJ9.HRYXZFATkIcI2_LJ1W_xo67IfBnbN9atyYNzyHqseLxYUxzgwBsAV5rNqCixKemOrDIeQLBN4jrwRsBIHDpEvshwBC8XmTodDJzpGmMaU9s1r20RV68X0_d1yTgSDke_Of7VCrVmJRbSuDl7AgsfTqQ1J7nWyu9vcIaER93ms-vadser_Ot9Z68_HAmCJL3DCLpdIFq3PYtBMKKKqXbvhfhSZQZD3b6-aewAnBo0VzpvK6tREqw1rv9_73oAvYcW2aHAj79ILr8viWMM40LyDKMMYOYkneg3hJUQsUVeh9WzztYUJKzERYNXje9fYIGN-eofoLvX7OZJ3eXmIfkrfQ");
xhr.setRequestHeader("Cache-Control", "no-cache");

xhr.send(data);

<?php
$request = new HttpRequest();
$request->setUrl('https://api.ccbill.com/payment-tokens/merchant-only');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Cache-Control' => 'no-cache',
  'Authorization' => 'Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsibWNuLXRyYW5zYWN0aW9uLXNlcnZpY2UiLCJtY24tYWRtaW4tc2VydmljZSJdLCJzY29wZSI6WyJjcmVhdGVfdG9rZW4iLCJyZWFkX3Rva2VuIiwiY2hhcmdlX3Rva2VuIiwiY3JlYXRlX3Byb2dyYW0iLCJyZWFkX3Byb2dyYW0iLCJjcmVhdGVfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIiwicmVhZF9wcm9ncmFtX3BhcnRpY2lwYXRpb24iLCJtb2RpZnlfcHJvZ3JhbV9wYXJ0aWNpcGF0aW9uIl0sImV4cCI6MTUzNzM4MDczNiwiYXV0aG9yaXRpZXMiOlsiTUNOX0FQSV9UT0tFTl9DSEFSR0VSIiwiTUNOX0FQSV9UT0tFTl9DUkVBVE9SIiwiTUNOX0FQSV9BRE1JTiJdLCJqdGkiOiI4YzI2Njg1MC00NjMzLTQzZDMtYjZjOC1lNzIyY2ExNjQ1YTUiLCJjbGllbnRfaWQiOiI1MjE3NjhhYTc1OGQxMWU4YWE2YjAwNTA1NjlkMTU4NSJ9.HRYXZFATkIcI2_LJ1W_xo67IfBnbN9atyYNzyHqseLxYUxzgwBsAV5rNqCixKemOrDIeQLBN4jrwRsBIHDpEvshwBC8XmTodDJzpGmMaU9s1r20RV68X0_d1yTgSDke_Of7VCrVmJRbSuDl7AgsfTqQ1J7nWyu9vcIaER93ms-vadser_Ot9Z68_HAmCJL3DCLpdIFq3PYtBMKKKqXbvhfhSZQZD3b6-aewAnBo0VzpvK6tREqw1rv9_73oAvYcW2aHAj79ILr8viWMM40LyDKMMYOYkneg3hJUQsUVeh9WzztYUJKzERYNXje9fYIGN-eofoLvX7OZJ3eXmIfkrfQ',
  'Content-Type' => 'application/json'
));

$request->setBody('{ "clientAccnum": 900000, "clientSubacc": 0, "customerInfo": { "customerFname": "Tyler", "customerLname": "Thomas", "address1": "Woodland Drive", "address2": "Apt 21", "city": "Tempe", "state": "AZ", "zipcode": "85281", "country": "US", "phoneNumber": "5555555555", "email": "tthomas@xyz.com", "ipAddress": "10.70.60.14'", "browserHttpUserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:60.0) Gecko/20100101 Firefox/60.0", "browserHttpAccept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", "browserHttpAcceptLanguage": "en-US,en;q=0.5", "browserHttpAcceptEncoding": "gzip, deflate, br" }, "paymentInfo": { "creditCardPaymentInfo": { "cardNum": "4473707989493598", "nameOnCard": "Tyler Thomas", "expMonth": "04", "expYear": "2026" } }, "subscriptionId":900000000000000001, "timeToLive": 30, "validNumberOfUse": 3 }');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
?>

Parámetros de respuesta de rechazo

Parámetro	Tipo	Descripción
decliveCode	cadena	El código de error se refiere al error que ha causado la falla de la transacción.
declinarTexto	booleano	Descripción de la decadencia.
ID de rechazo	cadena	GUID generado aleatoriamente.
aprobado	booleano	Estado de aprobación de la transacción.
pagoUniqueId	cadena	Clave única conectada a la cuenta de pago.
ID de sesión	cadena	Valor de ID de sesión único para la transacción.
ID de suscripción	entero	ID de suscripción al que pertenece la transacción.
newPaymentTokenId	cadena	Nuevo token de pago para transacciones posteriores.

Respuesta de ejemplo

{"declineCode":null,"declineText":null,"denialId":null,"approved":true,"paymentUniqueId":"dG4P1t8dL58pA3rNxE+Phw","sessionId":null,"subscriptionId":121095101000018190,"newPaymentTokenId":null}

Token de pago de cargo (con autenticación 3DS)

URL de punto final

https://api.ccbill.com/transactions/payment-tokens/threeds/{paymentTokenId}

Encabezados

Accept: application/vnd.mcn.transaction-service.api.v.1+json

Parámetros de solicitud

PARÁMETRO	TIPO	DESCRIPCIÓN
crear nuevo token de pago	booleano (opcional)	Devuelva un nuevo token de pago para transacciones posteriores o no.
clienteAccnum	entero (requerido)	Número de cuenta mercantil.
clienteSubacc	entero (requerido)	Número de subcuenta de comerciante.
precio inicial	flotar (requerido)	Precio de transacción inicial.
periodo inicial	entero (requerido)	La duración (en días) del período de facturación inicial.
Precio recurrente	flotar (opcional)	El monto que se le cobrará al consumidor por cada factura recurrente.
período recurrente	entero (opcional)	El tiempo entre refacturaciones.
refacturaciones	entero (opcional)	El número total de veces que se volverá a facturar la suscripción.
código de moneda	entero (opcional)	Código de moneda de tres dígitos (norma ISO 4217) para la moneda utilizada en la transacción.
LifeTimeSubscription	booleano (opcional)	La presencia de esta variable con un valor de 1 indica que la transacción es una suscripción de por vida.
crear nuevo token de pago	booleano (opcional)	Devuelva un nuevo token de pago para transacciones posteriores o no.
passThroughInfo	Matriz [cualquiera] (opcional)	Información emparejada que se pasa al servicio de transacciones.
tresdsCardToken	entero (requerido)	El número de tarjeta de pago (PAN).
tresdsEci	cadena (requerido)	Un Indicador de Comercio Electrónico (ECI). Valores: '0','1','2','5','6', o'7'.
estado de tresds	cadena (requerido)	El estado de la verificación 3DS ('Y','N','A', etc.)
versión de threeds	cadena (requerido)	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
tresdsXid	cadena (opcional/requerido)	El identificador de la transacción (XID) es un número de seguimiento único establecido por el comerciante para 3DS. Es un parámetro requerido para threedsVersion 1.0.2
tresdscavv	cadena (opcional/requerido)	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 y es un parámetro requerido para threedsVersion 1.0.2
algoritmo threedsCavv	cadena (opcional/requerido)	Algoritmo CAVV para solicitud de threeds. Se requiere el parámetro threedsCavvAlgorithm para threedsVersion 1.0.2
tresdsDsTransId	cadena (opcional/requerido)	ID de transacción del servidor de directorio. El parámetro threedsDsTransId es necesario para threedsVersion 2.1.0
tresdsAcsTransId	cadena (opcional/requerido)	ID de transacción del servidor de control de acceso. Se requiere el parámetro threedsAcsTransId para threedsVersion 2.1.0
tresdsSdkTransId	cadena (opcional)	El ID de transacción del proveedor de 3DS.
tipo de autenticación de threeds	cadena (opcional)	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.0).
valor de autenticación de threeds	cadena (opcional)	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.0).
threedsClientTransactionId	cadena (requerido)	El widget avanzado genera automáticamente el parámetro. Su propósito es identificar el origen de la transacción de autenticación 3DS.
tresdséxito	booleano (opcional)	Verificación del éxito o fracaso de la autenticación 3DS.
tresdsCantidad	entero (opcional)	La cantidad a cobrar (igual que precio inicial).
tresdsmoneda	entero (opcional)	El código de moneda de 3 dígitos para la moneda que se utilizará en esta transacción. Valor de ejemplo: 840
tresdsError	cadena (opcional/requerido)	Error recibido del proveedor de 3DS durante el proceso de autenticación sólida del cliente. El parámetro es obligatorio si no se proporciona threedsVersion.
tresdsErrorDetalle	cadena (opcional)	Detalles del error relacionados con el tresdsError.
tresdsErrorCode	cadena (opcional)	Código de error.
respuesta de tresds	cadena (opcional)	La respuesta completa en caso de error.

Parámetros de respuesta de rechazo

Parámetro	Tipo	Descripción
código de error	entero	Valor de condición de error de la transacción.
aprobado	booleano	Estado de aprobación de la transacción.
pagoUniqueId	cadena	Clave única conectada a la cuenta de pago.
ID de sesión	cadena	Valor de ID de sesión único para la transacción.
ID de suscripción	entero	ID de suscripción al que pertenece la transacción.
newPaymentTokenId	cadena	Nuevo token de pago para transacciones posteriores.

Respuesta de ejemplo

{
  "errorCode": "integer",
  "approved": "boolean",
  "paymentUniqueId": "string",
  "sessionId": "string",
  "subscriptionId": "integer",
  "newPaymentTokenId": "string"
}

Una vez que se ha cargado el token de pago, un Notificación HTTP POST de webhooks se activará para que pueda capturar la información de la transacción. Este evento de webhooks será un “UpSaleÉxito.

Leer ID de token de pago

Utilice esta llamada a la API para obtener datos sobre un cargo realizado anteriormente. Deberá identificar el cargo por la ID del token de pago e incluir la ID como un elemento URI.

Solicitud de ejemplo

GET 'https://api.ccbill.com/payment-tokens/{{PAYMENT_TOKEN_ID}}' \

--header 'Authorization: Bearer {{BACKEND_ACCESS_TOKEN}}' \

--header 'Accept: application/vnd.mcn.transaction-service.api.v.2+json'

URL de solicitud HTTP

https://api.ccbill.com/payment-tokens/{paymentTokenId}

Encabezamiento

Accept: application/vnd.mcn.transaction-service.api.v.2+json

Parámetros de respuesta

PARÁMETRO	TIPO	DESCRIPCIÓN
Id. de token de pago	cadena (requerido)	Representación compleja de ID de token de pago.
ID de participación del programa	entero (requerido)	El Programa conectado al Token de Pago.
originalPagoTokenId	cadena (opcional)	Referencia a un ID de token anterior.
clienteAccnum	entero (requerido)	Número de cuenta mercantil.
clienteSubacc	entero (requerido)	Número de subcuenta de comerciante.
Fecha y hora de creación	solo fecha y hora (requerido)	Fecha y hora de creación del token de pago.
tiempo para vivir	entero (requerido)	Tiempo de existencia del token (horas).
NúmeroVálidoDeUso	entero (requerido)	Número total de veces que se puede usar el token de pago para compras.
PaymentInfoId	cadena (opcional)	Información asociada al pago.
ID de suscripción	entero (requerido)	Identificación de la suscripción asociada a la transacción.

{"paymentTokenId":"01390f2aae864749a6437e007936529b","programParticipationId":null,"originalPaymentTokenId":null,"clientAccnum":999999,"clientSubacc":0,"createdDatetime":"2021-04-02T23:09:02","timeToLive":30,"validNumberOfUse":3,"paymentInfoId":null,"errors":null,"subscriptionId":"121092501000146223"}

Visite la siguiente página para obtener una lista completa de Códigos de error de la API RESTful de CCBill.