NAV

API INESPAY NATIVE

La API INESPAY NATIVE proporciona un servicio de pasarela de pagos basada en la transferencia bancaria, utilizando las credenciales de la banca online de los Clientes Finales. Está construida como un servicio REST, por lo que puede ser integrada en cualquier plataforma, independientemente del lenguaje del programación utilizado.

A diferencia de la API INESPAY PAYFLOW, la API INESPAY NATIVE ofrece una solución personalizada y completa para cualquier plataforma, sin necesidad de saltar o redireccionar al Cliente Final a la pasarela de pagos INESPAY para realizar el pago.

Este tipo de integración requiere la programación a medida de los formularios de pago de cada entidad financiera dentro de la propia plataforma, personalizando por completo el diseño de los campos y objetos. Gracias a este sistema de integración, la plataforma podrá contar con una pasarela de pagos única, otorgándole una sólida imagen corporativa. Para llevar a cabo este desarrollo, debe tenerse en cuenta que todas las entidades financieras solicitan un login, la selección de la cuenta del pago y un sistema de validación único para la operación de pago, por lo que todos los campos requeridos para la formalización de la transferencia bancaria deberán ser visibles por los compradores/pagadores.

Seguridad

La API INESPAY NATIVE requiere un proceso de autenticación mediante una API-KEY y una API-TOKEN, que pueden ser obtenidas desde el Dashboard INESPAY. Estas claves son de envío obligatorio en cada llamada y deben ser proporcionadas en la cabecera (Header) de cada petición.

Se utiliza el protocolo seguro HTTPS para el cifrado e intercambio de datos y el formato JSON para todas las respuestas propocionadas por la API.

Con el objetivo de facilitar la integración se distinguen dos entornos (ENVIROMENT):

Cada entorno tiene asociadas una API-KEY y una API-TOKEN diferentes, además de una URL distinta. Durante la fase inicial de integración únicamente se proprocionan las credenciales de TEST.

NOTA: Nunca se deben exponer las credenciales de INESPAY en sitios públicos o en lenguajes de lado cliente, ya que supone un riesgo de seguridad.

Credenciales Sandbox

Personas físicas

Banco bankId userId userSecret userExtraField
Abanca abanca_natural 11111112L 2233 -
Bankia bankia_natural 11111112L 2233 -
Bankinter bankinter_natural 11111112L 2233 -
BBVA bbva_natural 11111112L 2233 -
CaixaBank caixa_natural 11111112L 2233 -
Ibercaja iberacaja_natural 11111112L 2233 -
ING ing_natural 11111112L 2233 01/01/1971
Kutxabank kutxabank_natural 11111112L 2233 -
Banco Popular popular_natural 11111112L 2233 -
Banco Sabadell sabadell_natural 11111112L 2233 -
Banco Santander santander_natural 11111112L 2233 -
Unicaja unicaja_natural 11111112L 2233 -

Personas jurídicas

Banco bankId userId userSecret userExtraField
Abanca abanca_natural 11111112L 2233 -
Bankia bankia_legal 0001 2233 1111111111111
Bankinter bankinter_natural 11111112L 2233 -
BBVA bbva_legal 11111112L 2233 11111111
CaixaBank caixa_legal 11111112L 223344 -
Ibercaja iberacaja_natural 11111112L 2233 -
ING ing_natural 11111112L 2233 01/01/1971
Kutxabank kutxabank_natural 11111112L 2233 -
Banco Popular popular_legal 11111112L 2233 -
Banco Sabadell sabadell_legal 11111112L 2233 -
Banco Santander santander_legal 11111112L 22334 L11111112
Unicaja unicaja_natural 11111112L 2233 -

Servicios

Bancos

A continuación se detalla el servicio que permite obtener el listado de bancos disponibles en tiempo real, así como su estado actual y su correspondiente bankId.

Petición

POST https://api.inespay.com/ENVIROMENT/banks/list

Body

No se requiere ningún parámetro.

Respuesta

Parámetro Tipo Descripción
listBanks Array (Bank) Listado de bancos disponibles
status String Código de éxito o error
description String Descripción del código status

Bank

Parámetro Tipo Descripción
bankId String Identificador único del banco
name String Nombre del banco
active boolean Estado del banco
order int Orden
type int 0 = banco para persona física, 1 = banco para persona jurídica
fields array (Field) Información sobre los campos requeridos por el banco para login.

Field

Parámetro Tipo Descripción
nameField String Identificador del campo
min Number Longitud mínima
max Number Longitud máxima
valueType String Posibles valores del campo: alfanumeric (cualquier carácter) o numeric (solo números)
password boolean Si es verdadero mostramos los valores introducidos por el usuario ocultos con *.
translate Number Key para traducción
testValue Number Valor para entorno de TEST que produce éxito en la validación

Login

Acceso a la banca online con las credenciales proporcionadas. Debe ser la primera petición antes de realizar las siguientes peticiones a la API.

Petición

POST https://api.inespay.com/ENVIROMENT/login

Body

Parámetro Requerido Tipo Descripción
bankId Si String Identificador único del banco
userId Si String Usuario banca online
userSecret Si String Password banca online
userExtraField No String Código de empresa / contrato / fecha nacimiento

Respuesta

Parámetro Tipo Descripción
sessionId String Sesión que se debe utilizar en las siguientes peticiones sobre el mismo banco con el mismo usuario
listContracts Contract Solo devuelto por algunos bancos cuyo acceso acceso es multi contrato.
status String Código de éxito o error
descripción String Descripción del código status

Contract

Algunos bancos después de realizar el login devuelven un listado de contratos disponibles, cuando el usuario disponga más de uno, por tanto es necesario indicar el contrato mediante el parámetro contractId en la llamada al servicio de Cuentas.

Parámetro Tipo Descripción
contractId String identificador del contracto, necesario para la obtención de las cuentas asociadas
contractInfo String información del contrato

Cuentas

Obtiene el listado de cuentas bancarias disponibles para realizar una transferencia. Previamente, requiere realizar la llamada al servicio de Login para obtener el sessionId, solo para algunos bancos dependiendo de la respuesta de Login será necesario pasarle como parámetro contractId .

Petición

POST https://api.inespay.com/ENVIROMENT/accounts/list

Body

Parámetro Requerido Tipo Descripción
sessionId Si String Sesión recibida en la petición de Login
contractId No String Solo requerido por algunos bancos cuyo acceso es multi contrato, el servicio de “Login” devuelva un listado de contratos disponibles

Respuesta

Parámetro Tipo Descripción
sessionId String Sesión proporcionada por el Login
listAccounts Array (Account) Listado de cuentas disponibles
status String Código de éxito o error
description String Descripción del código status

Account

Parámetro Tipo Descripción
accountId String Identificador de la cuenta, necesario para iniciar la transferencia
accountInfo String Información relativa a la cuenta para mostrar al usuario
amount Number Saldo, solo disponible para algunos bancos sino devuelve valor con “null”

Transferencia - 1º paso

Inicia la transferencia bancaria. Previamente, requiere realizar la llamada al servicio de Login para obtener el sessionId.

Petición

POST https://api.inespay.com/ENVIROMENT/transfer/init

Body

Parámetro Requerido Tipo Descripción
sessionId Si String Sesión proporcionada por el Login
holderOrigin NO String Nombre del titular de la cuenta origen
accountIdOrigin Si String Identificador de la cuenta origen del pago proporcionado por el servicio “Cuentas”
amount Si Number Importe del pago mutiplicado por 100 sin decimales
subject Si String Concepto
holderDestiny Si String Nombre del titular de la cuenta destino (beneficiario)
accountDestiny Si String Número de cuenta destino de la transferencia (formato IBAN)

Respuesta

Parámetro Tipo Descripción
sessionId String Sesión proporcionada por el login
transactionId String Identificador único de la operación
validations Array (ValidationBank) Listado de las posibles validaciones requeridas por el banco
status String Código de éxito o error
description String Descripción del código status

ValidationBank

Parámetro Tipo Descripción
type String Tipo de validación, consultar la tabla Tipos validación
value String Valor devuelto por el banco, como por ejemplo la coordenada de autenticación, imagen de la tarjeta …
valueFromUser String Validación insertada por el usuario que autorizar el pago

Tipos validación

Type Validación Descripción
0 SIGNATURE Requiere un código de firma para realizar la operación
1 SMS Se solicita un código de firma temporal recibido por SMS
2 COORDINATES Se solicita el valor de la posición de una tarjeta de coordenadas física
3 COORDINATES_BY_SMS Posición de la coordenada recibida por SMS para localizarla en la tarjeta de coordenadas visualizada por pantalla
4 TOKEN Se solicita un token para validar la operación
5 COORDINATES_CARD_SHOWN Se muestra la tarjeta de coordenadas por pantalla

Firma - 2º paso

Todos los bancos generalmente exigen siempre al menos una validación para autorizar la transferencia. Existen múltiples tipos de validaciones que pueden ser solicitadas de forma simultánea o una después de otra. Para responder a estas validaciones existe un tiempo máximo de 90 segundos. Transcurrido dicho período se cancela la operación.

Petición

POST https://api.inespay.com/ENVIROMENT/transfer/validate

Body

Parámetro Requerido Tipo Descripción
sessionId Si String Sesión para todas las operaciones sobre el mismo banco con el mismo usuario
validations Si Array Tipos de validación requeridas por el banco con “valueFromUser” relleno

Respuesta

Parámetro Tipo Descripción
sessionId String Sesión para todas las operaciones sobre el mismo banco con el mismo usuario
transactionId String Identificador único de la operación
validations Array Listado de las posibles validaciones requeridas por el banco, en el caso de que se requiera una validación adicional
status String Código de éxito o error
description String Descripción del código status

Códigos de respuesta

Listado de códigos de estado y error devuelto por el API INESPAY.

Código Descripción
200 Éxito petición
228 Requiere una validación adicional, por lo que la transferencia está pendiente de firma por parte del usuario.
E300 Internal API error
E301 Parámetros incorrectos
B000 Error interno
B100 Credenciales bancarias inválidas
B101 Cuenta origen de la transferencia inválida
B102 Importe incorrecto
B103 Valor de tipo de validación inválido (SIGNATURE, SMS, COORDINATES, COORDINATES_BY_SMS, SIGNATURE_AND_TOKEN, COORDINATES_CARD_SHOWN)