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
group String Identificador del grupo
name String Nombre del grupo al que pertenece el banco
defaultType String BankId por defecto, identificador del banco.
types Array (BankType) Listado de bancos que pertenecen al grupo.

BankType

Parámetro Tipo Descripción
bankId String Identificador del banco
type Number 0 indica persona física, 1 indica persona jurídica
label String Nombre del banco para mostrar al usuario
active Boolean Indica si el banco se encuentra activo o desactivado por razones de mantenimiento.
defaultLogin String Identificador del login por defecto.
logins Array (LoginType) Listado de los diferentes logins que admite el banco

LoginType

Parámetro Tipo Descripción
loginId String Identificador del tipo de login
label String Nombre del tipo de login que se debe mostrar al usuario
active Boolean Indica si el tipo de login se encuentra activo o desactivado por razones de mantenimiento.
fields Array (FieldBank) Listado de campos que se deben solicitar al usuario para el tipo de login.

FieldBank

Parámetro Tipo Descripción
fieldId 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)
specificType String Validaciones que se deben aplicar al campo por ejemplo que valide que es formato DNI
password Boolean Si es verdadero mostramos los valores introducidos por el usuario ocultos con *.
label String Nombre del campo que se debe mostrar al usuario
testValue String 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 física del usuario de la banca Online.
4 TOKEN Se solicita un token para validar la operación
5 COORDINATES_CARD_SHOWN Se muestra la tarjeta de coordenadas por pantalla
6 INDIRECT_IN_OTHER_DEVICE El usuario firma la operación desde una app móvil, cuando ha firmado la operación se debe notificar vía API que la firma ya se ha realizado.

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

Forzar error en el proceso de pago

Es importante contemplar todos los escenarios posibles que se pueden dar durante el proceso de pago. Para facilitar la integración, existe la posibildad de forzar un error en el entorno de TEST. Para ello, en el momento de la validación de la transacción debemos insertar el valor “0000” en el parámetro value, lo cual provocará que falle la validación y devolverá el código de error correspondiente.

Códigos de respuesta

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

Código Estado Descripción
200 OK_DEFAULT Éxito petición API
228 OK_NEED_MORE_VALIDATION Éxito petición API se requieren validaciones adicionales por parte del usuario
E300 ERROR_DEFAULT Error genérico
E301 INVALID_PARAMS Error parámetros incorrectos
E302 ERROR_ORIGIN_ACCOUNT_EQUALS_DESTINY Error cuenta origen igual a cuenta destino
B100 INVALID_ACCESS Error credenciales banco al realizar login
B101 INVALID_ORIGIN_ACCOUNT Error cuenta especificada como origen inválida
B102 TRANSACTION_NOT_AUTHORIZED Error la entidad financiera no autoriza el pago.
B103 INVALID_VALIDATION Error validación transferencia
B104 ACTION_USER_REQUIRED Error se requiere que el usuario acceda directamente a su banca Online para activar/autorizar un servicio o contrato
B105 NOT_AVAILABLE Error banco no disponible, por razones de mantenimiento.
B106 MULTI_SIGNATURE_REQUIRED Error se requiere multifirma o firma mancomunada para validar la operación.
B107 ERROR_TRANSFER_DISABLED_IN_ORIGIN_ACCOUNT Error no se permite realizar transferencias con la cuenta origen seleccionada.