Documentación técnica de integración

Updated on October 16, 2023

Docy

Request token

Estimated reading: 3 minutes

Solicitud de Token

La aplicación cliente realizará una solicitud POST utilizando un servicio web de estilo-REST.

Los objetos intercambiados en esta solicitud se serializarán en formato JSON.

Ubicación del servicio

Estructura de Solicitud del Token


merchant_identifier
amount
currency
locale
operation
description
signature
url_responde
url_ok
url_ko
url_abort
params
target
style_back_boton
style_color_boton
style_back_frame
style_color_label
style_color_borde_boton
style_back_second_boton
style_color_second_boton
redirect
channels
payment_type
amount_min
amount_max
metadata
identifier
label_concept
label_amount
button_label
personal_identity_number
reference_number
payment_strategy
p1c
p1c_text
p1c_link
require_cardholder
card_present
target_ext
concept_transfer
destiny
phone_bc
mail_bc
customer_data
billing.city
billing.country
billing.postcode
billing.street
card.holder
customer.email
customer.phone
show
plan
instalments
attempts
amount
email_plan
phone_plan
fecha_fin_financiacion
redirect_by_message
source_domain

Solicitar parámetros del objeto

Parámetros Descripción Tipo de dato Requerido
Para el usuario, en acuerdo con el módulo ISO-693-1 El Español será usado por defecto
merchant_identifier Código de comercio a través del cual se revisa el pago que se hizo Alfanumérico Sí
amount Cantidad a pagar Numérico. Será multiplicado por 100 para evitar enviar separadores decimales, así que u pago de €145.70 será enviado como 14570 Sí
currency Identificador numérico internacional de la moneda en la que se realiza el pago (Es decir, para el euro será 978) según el estándar ISO-4217 Numérico (3) No, si no se envía, será el euro por defecto.
locale Identificador del lenguaje en el cual la pasarela será mostrada. Alfanumérico(2) No. Si no es indicado, el español será asignado por defecto
operation Identificador del pago. Será único para cada intento de pago Alfanumérico (25) Sí
description Descripción del pago. Aparecerá como un concepto de pago en el POST Caracter (máx. 200) Sólo caracteres en alfabeto español, o los siguientes caracteres: ‘vacío’, ‘guión’, ‘barra baja’, ‘punto y coma’ Sí
url_response URL a la cual se enviará la respuesta del pago, tanto si ha sido OK, como si ha sido KO Caracter (máx. 200) Sí
ul_ok URL donde el usuario es redirigido si el pago resulta como exitoso Caracter (máx. 200) Sí
url_ko URL donde el usuario es redirigido si el pago resulta no exitoso Caracter (máx. 200) Sí
url_abort Usado en el los métodos de pago que tienen un botón para cancelar la operación Caracter (máx. 200) No
signature Firma de los parámetros enviados con contraseña de firma, esta es proporcionda por Kíneox Alfanumérico Sí
params
target Objetivo a aplicar cuando el usuario es redirigido al url_ok, url_ko. Parámetro para indicar si el cliente es redirigido al url_ok directamente, después de realizar el pago o mostrando una pantalla con el resumen anterior. Anulará la configuración global de la aplicación cliente para un pago particular Alfanumérico si se refiere al nombre en el iframe, o uno de los siguientes valores:
_BLANK,
_SELF,
_PARENT,
_TOP 		No. Si no se define tendrá por defecto el valor _TOP.
style_back_boton Color que será aplicado al botón que aparece en el portal de pago. Si se envía el color en el request, se anulará el que se haya asignado en la configuración global, para este pago en particular Numérico (6). Código hexadecimal sin el caracter # No
style_color_borde_boton Define el color para el borde del botón Numérico (6). Código hexadecimal sin el caracter # No
style_back_second_boton El color será aplicado a los botones secundarios que aparecen en la pasarela. Anulará la configuración global de la aplicación cliente para un pago articular Numérico (6). Código hexadecimal sin el caracter # No
style_color_borde_second_boton El color será aplicado al borde de los botones secundarios que aparecen en la pasarela. Anulará la configuración global de la aplicación cliente para un pago particular. Numérico (6). Código hexadecimal sin el caracter # No
style_color_label El color será aplicado a los distintos textos que aparecen en el portal de pago. Anulará la configuración global de la aplicación cliente para un pago particular Numérico (6). Código hexadecimal sin el caracter # No
style_color_boton El color será aplicado a los textos del boton que aparecen en la pasarela de pagos. Anulará la configuración global de la aplicación cliente para este pago en particular Numérico (6) Hexadecimal sin el caracter # No
style_color_frame El color será aplicado a la parte inferior del iframe de la pasarela. Anulará la configuración global de la aplicación cliente para este pago en particular Numérico (6). Código hexadecimal sin el caracter # No
redirect Objetivo a aplicar cuando el usuario es redirigido al url_ok. Parámetro para indicar si el cliente es redirigido al url_ok directamente después de realizar el pago o mostrando una pantalla de resumen anterior. Anulará la configuración global de la aplicación cliente para un pago particular. Caracter. Valores: verdadero o falso No
channels Métodos de pago permitidos para este pago. (Separado por; ) Anulará la configuración global de la aplicación para este pago en específico Caracter. Valores: CARD, CASH, PAYPAL, SOFORT… No
payment_type Tipo de pago que se va a realizar, entre los disponibles para este canal Caracter(2). Valores:
PN (Pago normal),
RI (Pago recurrente)
AU (Autorización) 		No. Si no se define, tendrá el valor «PN» como predeterminado
amount_mix Cantidad mínima aceptada para ese pago Numérico. Será multiplicado por 100 para evitar enviar separadores decimales, así que u pago de €145.70 será enviado como 14570 No. Si no se define, se asume un valor informado e el campo amount
amount_max Cantidad máxima aceptada para este pago Numérico. Será multiplicado por 100 para evitar enviar separadores decimales, así que u pago de €145.70 será enviado como 14570 No. Si no se define, se asume un valor informado e el campo amount
metadata Campo utilizado para reportes y auditorias. Cualquier dato que sirva para rastrear pagos y auditorias, se puede indicar aquí Alfanumérico (160) No
identifier Identificador único para el pago, se utiliza para evitar duplicados de los pagos del integrador Alfanumérico (160) No
label_concept Etiqueta que se muestra al cliente para indicarle el concepto del pago. El concepto se mostrará en caso de no estar informado Alfanumérico (160) No
label_amount Etiqueta que se muestra al cliente para indicarle la cantidad a pagar. La cantidad se mostrará en caso de no estar informado Alfanumérico (160) No
button_label Puede usarse este campo para cambiar el texto que aparece en el botón de pago, puede ser cambiado a «Aprobado», «Validado» o similar. Si se utiliza este campo se necesita controlar el texto para distintos lenguajes Alfanumérico (100) No
personal_identity_number Identificador para la persona que realiza el pago, usualmente se coloca CIF/NF/NIE o pasaporte. Se usa tanto para la identificación como para hacer cumplir las normas antifraude Alfanumérico (50) Sí, para los filtros de seguridad y métodos de pago en efectivo
reference_number Referencia interna del cliente. Se usa para generar el código de barras para el documento de pago para realizar pagos en oficinas bancarias (N57) Numérico (13) No. Sólo es necesario para pagos en efectivo en el banco con la Norma57
payment_strategy Indica la estrategia de seguridad que se tendrá en cuenta para el pago. Puede tomar los valores BLACK y SECURE. Utiliza el valor del Parámetro PERSONAL_IDENTITY_NUMBER para la validación Valores: BACK, deniega los pagos con tarjeta, pero acepta pagos a través de otros canales. SECURE, aplica el 3D security para pagos con tarjeta y permite también pagos por otros canales No. Requerido para las normas de seguridad si está activo.
p1c Indica si el pago puede guardar la tarjeta (para futuros pagos) o mostrar la opción de pago con un solo click True No
p1c_text Texto que muestra si está habilitado guardar los datos de la tarjeta Alfanumérico Obligatorio si está habilitado p1c
p1c_link Enlace para mostrar información extendida si está habilitado guardar los datos de la tarjeta Alfanumérico Obligatorio si está habilitado p1c
require_cardholder Indica si es necesario preguntarle al titular de la tarjeta durante el proceso de pago True / False
card_present Identidad del pagador, si se encuentra presente Verdadero. (Verdadero si es el cliente el que introduce la tarjeta, falso si es el agente o el sistema de IVR quien tiene la tarjeta) No
target_ext Este parámetros es usado para los métodos de pago que necesitan ser ejecutados con redirección como SOFORT, PAYPAL, con este campo se lleva el control de dónde la ventana será abierta. Valores: _blank, _parent, _top. No
concept_transfer Este parámetro es usado para incluir la descripción que aparecerá en la recepción de las transferencias que han sido iniciadas por SOFORT Alfanumérico (máx 200) No
destiny Se usa para identificar el destino del adquiriente. Cuando se trabaja con un multi adquiriente, se puede utilizar este campo para indicar manualmente en donde quieres procesar esta tarjeta. Si es necesario Kineox facilitará los posibles valores para este campo. Alfanumérico (20) No
billing.city Parámetro que indicará la ciudad del cliente
billing.country Con este parámetro se indica el país del cliente. Por defecto se encuentra asignado «ES» para España Alfanumérico (10) No
billing.postcode Código postal del cliente Numérico No
billing.street Dirección de facturación del cliente. Alfanumérico No
card.holder Datos del titular de la tarjeta indicados por el cliente Alfanumérico No
customer.email Email del cliente. Alfanumérico No
customer.phone Número de teléfono del cliente Alfanumérico No
redirect_by_message Enviar a true para indicar a pci y pasarela que la redirección es a través de mensajes entre dominios Verdadero o falso No
source_domain Se indica «https://test.gestionrecibos.online/» para avisar el dominio de origen, donde se enviará la última redirección desde pasarela URL No
show Parámetro para indicar si los datos de facturación serán visibles en la vista de cliente. Verdadero o falso No
plan Pago a plazos Cadena No
instalments Número de cuotas, la próxima cuota será procesada el mismo día del próximo mes (Excepto 29, 30, 31 de Febrero y meses que no tengan 31 días) Numérico No
atempts Número de re intentos en cada cuota Numérico No
instalment_amount Cantidad para la cuota si el primer pago es 0. Para la próxima cantidad en cada cuota, nosotros usamos el valor del AMOUNT, sólo si nosotros no aplicamos la primera cuota, ponemos 0 en AMOUNT, el monto de la cuota en este campo Numérico. Será multiplicado por 100 para evitar enviar separadores decimales, así que u pago de €145.70 será enviado como 14570 No
email_plan Dirección de correo electrónico, está información puede ser utilizada para informar al pagador sobre problemas con la cuota y obtener detalles de una nueva tarjeta Alfanumérico No
phone_plan El número de teléfono del cliente se puede utilizar para enviar un SMS informando sobre problemas con la cuota y obtener detalles de una nueva tarjeta Alfanumérico No
dynamic_parameters Los parámetros dinámicos se usan para formar las notificaciones por sms/email/pdf para pagos en efectivo. La clave debe ser previamente configurada para el comercio Libre. Un posible valor podría ser el nombre del usuario No
fecha_fin_financiacion Si la fecha de caducidad de la tarjeta es anterior a esta fecha retorna un error 730 y no procesa el pag Fecha dd/mm/yyyy No

El campo «signature» contiene una firma calculada para los parámetros enviados.

El algoritmo y proceso de cálculo de la firma será detallada en el Annexo-1 de este documento. El orden de los campos que forman la firma es el siguiente:

-merchant_identifier, amount, operation, url_response, url_ok, url_ko, signature



El campo signature no viaja en la solicitud. Será facilitado por Kíneox y estará asociado con el campo merchant_identifier

Estructura del objeto de respuesta del token

El objeto de respuesta tiene la siguiente estructura:

  • token
  • token_result
      • code
      • description

Parámetros del objeto de respuesta

Campo CODE, códigos posibles, Objeto de respuesta

Ejemplo de petición 

				
					{
"merchant_identifier": "prb",
"amount": "1000",
"currency": 978,
"locale": "ES",
"operation": "KX001",
"description": "Prueba",
"signature": "139ad56fa3a54cdc12abba56f179e532b9e67fe3b87e06aa0afc88499b7b039a",
"url_response": "https://www.respuesta",
"url_ok": "https://urldeok",
"url_ko": "https://urldeko",
"params": {
 "target": null,
 "style_back_boton": null,
 "style_color_boton": null,
 "require_cardholder": null,
 "payment_strategy": null,
 "payment_channel": "CARD",
 "payment_type": "RI",
 "plan": "{\"attempts\": 2,\"email\": \"prueba@kineox.com\",\"listInstalments\":[{\"date\": \"28-07-2022\",\"amount\": 1400},{\"date\": \"29-07-2022\",\"amount\": 1400}]}"
 }
}

Powered By EazyDocs

en_GBEnglish (UK)
es_ESEspañol en_GBEnglish (UK)