Documentación técnica de integración

Updated on octubre 16, 2023

Docy

Respuesta con información de pago

Lectura estimada: 3 minutos

De forma asincrónica e inmediatamente después de cada intento de pago a través de la pasarela de pago,  se envía una solicitud de tipo POST a través del servicio web de tipo REST, a la url pasada en el campo URL_RESPONSE.

Los objetos intercambiados en esta petición están serializados en formato JSON. El objeto de esta solicitud es informar al comerciante del resultado del pago o pagos realizados en la TPV .

Por cada carga del iframe de la pasarela puede haber varias solicitudes de respuesta, una para cada intento de pago, pero solo un máximo de uno relativo a un pago OK.

Dicha solicitud debe responderse con el texto “ok” si la solicitud ha sido recibida y tratada correctamente o el texto “KO” en caso de no ser tratada adecuadamente.

Cuando el POST no recibe una respuesta o recibe un “KO”, se activará un cierto número de re-intentos de envío de la respuesta. Esto consiste en 9 intentos espaciados tantos segundos como indica la serie de Fibonacci. Después de estos 9 intentos habrá una notificación cada una hora por un máximo de 12 horas. En caso de agotar todos los intentos anteriores y no tener un “OK” de respuesta, se enviará un correo electrónico con los resultados del pago al administrador del comercio para que el cargue manualmente el estado del pago en su sistema

Solicitud de estructura del objeto

  • merchant_identifier
  • amount
  • merchant_operation
  • payment_operation
  • channel
  • payment_date
  • payment__code
  • signature
  • currency
  • params( mapa donde la clave y el valor son cadenas)
      • authorisation_code
      • pan
      • expiry_date
      • card_token
      • card_type
      • card_country
      • bank_operation
      • payment_secure
      • currency_payment
      • currency_rate
      • payment_secure_reason
      • mandate
      • recurrent
      • mandate_identifier
      • iban
      • email
      • phone_number
      • name
      • personal_identity_number
      • cardholder
      • metadata
      • plan
    • instalments
    • attempts
    • instalment_amount
    • email
    • phone_number

Parámetros del objeto de respuesta

Parámetro Descripción Tipo de dato
merchant_identifier Código del comercio que realizó el pago Alfanumérico
amount Cantidad del pago Numérico. Será multiplicado por 100 para evitar enviar separadores decimales, así que un pago de €145.70 será enviado como 14570
operation Identificador de pago enviado por el comerciante con solicitud de TOKEN en el campo operation Alfanumérico(25)
payment_operation Identificador de pago realizado dentro del iframe del portal. El operation puede tener cero o más socios payment_operation Alfanumérico (25)
channel Canal por el cual el informa de pago ha sido hecho Caracter(3)
payment_date Fecha en la que el pago ha sido realizado YYYYMMDDHHmmss
payment_code Código que indica el status del pago. 000 será pago OK, cualquier otro valor indicará que el pago ha sido KO Caracter(3)
signature Firma de los parámetros enviados junto con la firma de la contraseña proporcionada por Kíneox Caracter
currency Código de la moneda en la que se realiza el pago, de acuerdo a lo establecido en la normal ISO-421 Numérico (3)
params
authorisation_code Código asociado únicamente a pagos con resultado OK. El código no es único Numérico(6)
pan Número de tarjeta enmascarada utilizada para el pago a través del canal CARD. Formato 12345xxxxxxxx1234
expiry_date Fecha de expiración de la tarjeta usada para el pago a través del canal CARD yyyyMM
card_token Identificación de la tarjeta utilizada en el pago Caracter(20)
card_type Tipo de tarjeta utilizada para el pago Valores: CARD- No se recibió información desde el banco CREDIT_CARD CREDIT_CARD
card_country País donde se expidió la tarjeta. Código de país según identificación de los caracteres en la tabla ISO 3166-1 Caracter (2)
bank_operation Código de operación bancaria. Es el código asignado al pago por parte de la entidad que lo procesa Caracter(20)
payment_secure Indica si el pago ha sido procesado aplicando la verificación 3D Secure Valores: -TRUE -FALSE
currency_payment Moneda en la que se realizó el pago. Este campo será devuelto, si se realiza con otra moneda diferente a la indicada al inicio del pago
currency_rate Razón aplicada en el cambio de moneda Númerico (10,2)
payment_secure_reason Motivo por el que se utiliza el pago seguro. Valores: -STRATEGY, pago estrategia -AMOUNT, importe superior al límite configurado -ALWAYS, la configuración requiere de pago seguro siempre. -FIRST, primer pago -BLACK, lista negra
mandate Mandato firmado Bytes en formato Base64 con contenido del documento
recurrent Indica si el método de pago puede ser utilizado para otros pagos Valores -Verdadero, puede ser usado. -Falso, no puede ser usado
mandate_identifier Identificador del mandato Caracter (100)
iban Número de cuenta bancaria utilizada para el pago SEPA Caracter (24)
email Correo electrónico de la persona que solicita información para los canales CASH y VENTANILLA Caracteres(160)
phone_number Número de teléfono de la persona que solicita información para los canales CASH Y VENTANILLA Caracter (9)
name Nombre en el formulario del mandato SEPA Caracteres(160)
personal_identity_number Número de identificación personal de la persona que firmó el mandato SEPA Caracter (24) NIF/CIF/NIE/Passport
card_holder Datos del titular de la tarjeta indicados por el cliente Caracter
metadata Es la misma entrega de información en la captura del método de pago. Este campo puede ser utilizado por el cliente para pasar información de captura a respuesta. Alfanumérico(160)
plan Detalles para el plan de pagos. Pago a plazos
instalments Número de plazos del plan de pagos Numérico
attempts Número de reintentos por cuota Numérico
instalment_amount La cantidad de la cuota con el valor asignado a cobrar Numérico. Será multiplicado por 100 para evitar enviar separadores decimales, así que un pago de €145.70 será enviado como 14570
email Dirección de correo electrónico del cliente Caracteres(160)
phone_number Número telefónico del cliente Caracteres(160)
card_present Identificar si el pagador, está presente Verdadero o falso

El campo SIGNATURE contendrá una firma calculada a partir de 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 componen la firma es el siguiente:

  • merchant_identifier, amount, operation, payment_operation, channel, payment_date, paymet_code, signature.
El campo signature no viaja en la solicitud. Será facilitado por Kíneox y estará asociado con el campo merchant_identifier

Ejemplo de respuesta de pago

				
					  "merchant_identifier" : "PRB",
  "payment_amount" : "5500",
  "merchant_operation" : "prueba01",
  "payment_operation" : "369645464050",
  "payment_channel" : "card",
  "payment_date" : "2023-10-05 00:04:08",
  "payment_code" : "000",
  "signature" : "ed23784b5e8853c9672b989b634b2e729d3539e3e8ad6958dd6a21bd87a1ea60",
  "currency" : "978",
  "params" : {
    "bank_pay_code" : "0000",
    "card_country" : "es",
    "bank_operation" : "332700944249",
    "recurrent" : "true",
    "payment_secure" : "false",
    "authorisation_code" : "123456",
    "card_token" : "4411162746447165",
    "card_type" : "debit_card",
    "bank_code" : "0000",
    "expiry_date" : "202707",
    "card_number" : "123456xxxxxx7165"
  }
}

Powered By EazyDocs

es_ESEspañol
en_GBEnglish (UK) es_ESEspañol