Documentación técnica

Documentación para la integración de InstantCredit en tu ecommerce.

API

Introducción

La siguiente imagen muestra de forma gráfica el flujo de llamadas que se llevan a cabo para la asignación de un crédito.

Todas las llamadas siguen el formato JSON.

En primer lugar, el comercio envía la petición de crédito a InstantCredit. En este punto, el usuario inicia el proceso de crédito. Cuando finalice la transacción, Instant Credit confirmará al comercio si ha terminado de forma satisfactoria o no.

Signature

Descripción

El uso del campo signature garantiza la integridad de los datos, ya que consiste en un cifrado del cuerpo de la notificación JSON que se envía a InstantCredit. Este mecanismo es útil para evitar un ataque de tipo man-in-the-middle, para así garantizar que los datos recibidos no han sido alterados.

Algoritmo

Para conseguir este objetivo, los datos se cifran usando el algoritmo SHA-256. El SHA-256 convierte una cadena de entrada (los datos que queremos transmitir) en una cadena donde los datos han sido ocultados mediante operaciones matemáticas. Para garantizar la integridad de los datos, el servidor de destino debe comprobar que la signature recibida es idéntica a la generada usando la misma llave (secret key) y cadena de entrada.

La Signature se forma concatenando a la llave secreta (secret key) y el string que contiene el cuerpo de la notificación que se va a encriptar sin espacios en blanco ni tabulaciones.

Código de ejemplo

Imaginemos que queremos transmitir la siguiente información:

{
"amount":"400",
"currency":"EUR",
"country":"ES"
}

Cuerpo del mensaje:

				
					{
"amount":"400",
"currency":"EUR",
"country":"ES"
}
Llave: a09fd33m19rtf
Cadena de entrada: a09fd33m19rtf{"amount":"400","currency":"EUR","country":"ES"}
Tras ejecutar el algoritmo a la entrada anterior, obtenemos la siguiente cadena:
77da5ac0df3cfd7692a1c1646c36e2de08cc74afa700e2f277e5e430f5cd2545

Por lo tanto, cuando el servidor recibe los datos, genera la signature usando la misma llave y cuerpo de la notificación y, comprueba si coincide con la enviada. Si son idénticas, los datos no han sido manipulados y es seguro procesarlos. Este proceso también debe implementarse en el comercio para validar que todas las comunicaciones que recibe de Instant Credit son válidas y no se han manipulado.

Access token request

Este método devolverá el accessToken, refreshToken, scopes permitidos y el tiempo que durará el accessToken.

El accessToken es el atributo que necesitaremos usar para las comunicaciones con las APIs de Instant Credit, entre ellas, la credit request para iniciar una solicitud de financiación.

Esta petición tiene que realizarse siempre antes de cualquier otra comunicación con las APIs de Instant Credit y no puede usarse el accessToken para más de una petición, cada llamada API tiene que ir acompañada de su previa llamada de obtención del accessToken.

Endpoint donde enviar la petición de accessToken mediante POST

				
					https://test.instantcredit.net/api/oauth/token

Attributes

clientIdrequired

string

Identificador de cliente proporcionado por InstantCredit.

324

userNamerequired

string

Usuario del comercio.

MERCHANT_USERNAME

passwordrequired

string

Contraseña del comercio.

MERCHANT_PASSWORD

grantTyperequired

string

Siempre deberá tener el valor “password”.

password

scope

string

En caso de enviarse vacío o no enviarse, se recibirán todos los scopes a los que el usuario tiene acceso.

credit_request

Header

				
					Content-Type: application/json

Body

				
					{
"clientId":"324",
"userName":"MERCHANT_USERNAME",
"password":"MERCHANT_PASSWORD",
"grantType":"password",
"scope":"credit_request"
}

Response

De la respuesta obtenida, el atributo que necesitamos para iniciar una comunicación con las API de Instant Credit, com por ejemplo la credit request, es el atributo accessToken.

Attributes

accessToken

string

86fmxj44rka1j4if

refreshToken

string

23kl09a1hbcnr55js783s

expiresIn

number

3600

grantTyperequired

string

Siempre deberá tener el valor “password”.

password

scope

string

Si en la solicitud del accessToken se ha especificado un scope, en este campo aparecerá el mismo valor indicado. En caso contrario, se devolverá la lista de scopes a los que las credenciales enviadas tienen acceso.

credit_request

Header

				
					Content-Type: application/json

Body

				
					{
"accessToken":"86fmxj44rka1j4if",
"refreshToken":"23kl09a1hbcnr55js783s",
"expiresIn":3600,
"scope":"credit_request"
}

Credit/request

Mediante este método, el comercio inicia el proceso de creación de un nuevo crédito.

En la cabecera de la credit request, deberán incluirse el accessToken obtenido en la petición anterior y la Signature del contenido de la credit request.

Endpoint donde enviar la petición de credit request mediante POST

				
					https://test.instantcredit.net/api/credit/request

Attributes

orderIdrequired

string

ID de la orden en el entorno del comercio.

custom

string

Datos adicionales enviados por el merchant. Esta información se enviará de vuelta en la confirmación del pedido.

amountrequired

string

El separador de decimales debe ser el punto.

240.10

currencyrequired

string

Código ISO de tres letras. Únicamente se acepta como valor de entrada, el siguiente código.

EUR

countryrequired

string

Código ISO de dos letras. Únicamente se acepta como valor de entrada, el siguiente código.

successURLrequired

string

URL a la que se redirigirá al usuario cuando finalice correctamente la transacción.

En esta URL no debe implementarse ninguna lógica de gestión de pedidos, ya que puede ser que el usuario no llegue a este punto. La lógica debe implementarse en la URL de notificationURL donde se recibirá el estado final de cada transacción.

failURLrequired

string

URL a la que se redirigirá al usuario cuando finalice incorrectamente la transacción.

notificationURLrequired

string

URL del comercio donde se enviará la confirmación del estado final del crédito.

En esta URL es donde debe implementarse la lógica de gestión de pedidos, ya que es donde se recibirá el estado final de cada transacción.

endUser

object

endUserIdrequired

String

ID de usuario en el comercio.

En caso de no disponer de ID de usuario porque el comercio no registra usuarios, se deberá usar como valor el mismo que el facilitado en el atributo «orderId».

String

IP del usuario.

firstName

String

Nombre del usuario.

John

lastName

String

Apellidos del usuario.

Doe Smith

personalId

String

DNI o NIE del usuario.

12345678Z

email

String

Email del usuario.

john@doe.com

birthDate

String

Fecha de nacimiento del usuario.

Formato yyyy-MM-dd.

1970-01-01

mobile

String

Móvil del usuario.

674883322

alternativePhoneNumber

String

Número de teléfono fijo o alternativo del usuario.

964337891

address

object

Dirección del usuario.

Este campo es opcional. Si se envía, deberá contener todos los campos especificados.

street

string

Passeig de Gracia

postalCode

string

08020

province

number

La lista de códigos asociados a las provincias puede consultarse en el siguiente enlace: Códigos de provincia.

city

string

Barcelona

country

string

registrationDate

string

Fecha en la que se registró el usuario en el sistema del comercio. Debe seguir el formato yyyy-MM-dd.

1970-01-01

historicOrders

array

Histórico de operaciones realizadas por el usuario dentro del comercio.

Este campo es opcional. Si se envía, deberá contener todos los campos especificados.

object

status

enum

AUTHORIZED

string

FRAUD

string

DECLINED_NOT_FRAUD

string

IN_PROCESS

string

SAMPLE

FRAUD

string

date

string

Formato yyyy-MM-dd hh:mm:ss.

1970-01-01 23:23:23

amount

string

210.25

currency

string

Código ISO de tres letras.

EUR

country

string

Código ISO de dos letras.

Header

				
					Content-Type: application/json
Authorization: Bearer [accessToken]
Signature: [signature]

Body

				
					{  
   "orderId":"",
   "custom":"",
   "amount":"240.10",
   "currency":"EUR",
   "country":"ES",
   "successURL":"",
   "failURL":"",
   "notificationURL":"",
   "endUser":{  
      "endUserId":"",
      "ip":"",
      "firstName":"John Doe",
      "lastName":"Doe",
      "personalId":"12345678Z",
      "email":"john@doe.com",
      "birthDate":"1970-01-01",
      "mobile":"674883322",
      "alternativePhoneNumber":"964337891",
      "address":{  
         "street":"Passeig de Gracia",
         "postalCode":"08008",
         "province":8,
         "city":"Barcelona",
         "country":"ES"
      },
      "registrationDate":"1970-01-01",
      "historicOrders":[  
         {  
            "status":"FRAUD",
            "date":"1970-01-01 23:23:23",
            "amount":"240.10",
            "currency":"EUR",
            "country":"FR"
         }
      ]
   }
}

Para mejorar la experiencia de usuario y aumentar la aprobación de créditos, una buena práctica consiste en que el comercio envíe determinadas informaciones del usuario final a la plataforma de Instant Credit, por ejemplo: nombre y apellidos, teléfono móvil, email, etc. Dicha información se va a mostrar pre-cargada en el proceso de solicitud de crédito del usuario. De esta forma, el usuario sólo tendrá que validar sus datos personales, mejorando así su experiencia. Además, ten en cuenta que al tener más datos disponibles del usuario (por ejemplo: la fecha de su registro en el comercio, su histórico de compras en el comercio, etc.) aumentará la tasa de aprobación de créditos y tu conversión.

Response

Attributes

url

string

URL a la que se deberá redirigir al usuario para iniciar el proceso de solicitud de crédito.

result

enum

Resultado de la petición de inicio de financiación. Si el resultado es OK significa que el proceso se ha iniciado correctamente. De lo contrario, si el resultado es FAIL significa que no se ha podido crear una petición de financiación.

Este es el atributo que se debe usar para validar si una petición de credit request ha sido exitosa y, por lo tanto, podemos redireccionar al usuario a la url facilitada en la respuesta de la credit request o, de lo contrario, ha sido una credit request no exitosa.

string

FAIL

string

transactionId

number

Identificador único de la petición en el sistema de Instant Credit.

1234

orderId

string

Identificador único de la petición en el sistema del comercio. Este valor es el mismo que se ha facilitado en la petición de credit request.

resultType

string

Tipo de la respuesta.

SUCCESSFUL (1)

string

INCORRECT_DATE (2)

string

ORDER_ID_ALREADY_EXISTS (3)

string

NO_LENDERS_AVAILABLE (4)

string

INCORRECT_CURRENCY (5)

string

INCORRECT_COUNTRY (6)

string

UNDEFINED (7)

string

resultDescription

enum

Descripción de la respuesta.

Credit request correctly received. (1)

string

The “birthDate” has an invalid format, it should be “yyyy-MM-DD” : 11-11-2001 (2)

string

The “registrationDate” has an invalid format, it should be “yyyy-MM-DD” : 14-04-1995 (2)

string

The “date” has an invalid format, it should be “yyyy-MM-DD hh:mm:ss” : 11-11-2014 23:30:00 (2)

string

The orderId value has been provided before from the same Merchant : 123456 (3)

string

There are no Lenders available to offer that credit. (4)

string

The Currency value is not allowed: EUR (5)

string

The Country value is not allowed: ES (6)

string

Undefined error (7)

string

Header

				
					Content-Type: application/json
Signature: [signature]

Body

				
					{  
   "url":"",
   "result":"OK",
   "transactionId":123,
   "orderId":"",
   "resultType":"SUCCESSFUL",
   "resultDescription":"Credit request correctly received."
}

Credit/confirmation

Esta llamada se utiliza para confirmar si la transacción ha finalizado correctamente o no se ha completado.

La credit confirmation se debe contestar siempre para confirmar a la plataforma de Instant Credit que la información sobre la transacción se ha recibido y, por lo tanto, está sincronizada tanto en el entorno de Instant Credit como en el del comercio. En caso de no responder correctamente a la notificación de confirmación, el sistema va a seguir intentando entregar la notificación hasta que la respuesta sea correcta.

Para mayor detalle de cómo contestar a la credit confirmation, por favor, revisar el apartado de credit confirmation response más abajo.

Endpoint donde se va a recibir la petición de credit confirmation mediante POST que enviará Instant Credit a la plataforma del comercio

				
					Url definida en el atributo "notificationUrl" en la petición inicial de credit request.

Attributes

transactionId

string

Identificador único de la petición en el sistema de Instant Credit. Este valor es el mismo que se ha facilitado en la petición de credit request.

orderId

Identificador único de la petición en el sistema del comercio. Este valor es el mismo que se ha facilitado en la petición de credit request.

string

amount

string

El separador de decimales será el punto. Este valor es el mismo que se ha facilitado en la petición de credit request.

240.10

currency

string

Código ISO de tres letras. Este valor es el mismo que se ha facilitado en la petición de credit request.

EUR

country

string

Código ISO de dos letras. Este valor es el mismo que se ha facilitado en la petición de credit request.

result

enum

Resultado de la petición de financiación. Si el resultado es OK significa que la financiación se ha completado correctamente. De lo contrario, si el resultado es FAIL significa que la financiación no se ha podido completar. Se trata de un estado final, con lo que la transacción no cambiará de estado a partir de este punto.

Este es el atributo que se debe usar para validar si una petición ha sido exitosa y, por lo tanto, podemos completar el proceso de pago o, de lo contrario, ha sido una transacción no exitosa con lo que el pago no se completará.

string

FAIL

string

resultType

enum

Tipo de la respuesta.

SUCCESSFUL

string

TIMEOUT

string

UNDEFINED

string

resultDescription

enum

Descripción de la respuesta.

Credit created and successfully assigned

string

The customer didn’t complete the process

string

Undefined reason

string

Header

				
					Content-Type: application/json
Signature: [signature]

Body

				
					{  
   "transactionId":"",
   "orderId":"28",
   "amount":"240.10",
   "currency":"EUR",
   "country":"ES",
   "result":"OK",
   "resultType":"SUCCESSFUL",
   "resultDescription":"Credit created and successfully assigned"
}

Response

La credit confirmation se debe responder siempre, no se trata de generar una nueva petición contra las APIs de Instant Credit sino en contestar a la comunicación iniciada por Instant Credit a la url definida en el atributo «notificationUrl» de la credit confirmation.

La credit confirmation debe ser respondida siempre con un result: OK, ya que el «result OK» significa que el comercio ha recibido correctamente la notificación y que actuará en consecuencia. Si el comercio recibe un result OK significa que la financiación se ha completado correctamente, no obstante, si el comercio recibe un result FAIL significa que esa transacción no se ha completado correctamente.

Es importante que en el «result» el comercio siempre responda con un result OK y se incluya, también, en la respuesta a la credit confirmation la Signature en el header.

Attributes

transactionIdrequired

number

Identificador único de la petición en el sistema de Instant Credit. Este valor es el mismo que se ha facilitado en la petición de credit request.

123

orderIdrequired

string

Identificador único de la petición en el sistema del comercio. Este valor es el mismo que se ha facilitado en la petición de credit request.

resultrequired

string

Confirmación de la recepción de la credit confirmation y su correcto procesamiento.

Único valor disponible.

resultTyperequiered

string

Tipo de la respuesta.

Se usa siempre el mismo valor. Único valor disponible.

SUCCESSFUL

resultDescriptionrequired

string

Descripción de la respuesta.

Se usa siempre el mismo valor. Único valor disponible.

Acknowledgement

Header

El header siempre debe contener la Signature de la respuesta a la credit confirmation.

				
					Content-Type: application/json
Signature: [signature]

Body

				
					{  
   "transactionId":123,
   "orderId":"28",
   "result":"OK",
   "resultType":"SUCCESSFUL",
   "resultDescription":"Acknowledgement"
}

Ejemplos de peticiones de credit confirmation y su respuesta

Ejemplo 1

Credit confirmation request (enviada de Instant Credit al comercio)

				
					{  
	"result": "OK",
	"country": "ES",
	"amount": "144.00",
	"orderId": "00647160",
	"currency": "EUR",
	"resultDescription": "Credit created and successfully assigned",
	"resultType": "SUCCESSFUL",
	"transactionId": 5463
}

Credit confirmation response (la respuesta a la notificación de Instant Credit)

				
					{  
	"transactionId": 5463,
	"orderId": "00647160",
	"result": "OK",
	"resultType": "SUCCESSFUL",
	"resultDescription": "Acknowledgement"
}

Ejemplo 2

Credit confirmation request (enviada de Instant Credit al comercio)

				
					{  
	"result": "FAIL",
	"country": "ES",
	"amount": "423.00",
	"orderId": "00630149",
	"custom": "165442",
	"currency": "EUR",
	"resultDescription": "Undefined reason",
	"resultType": "UNDEFINED",
	"transactionId": 5475
}

Credit confirmation response (la respuesta a la notificación de Instant Credit)

				
					{  
	"transactionId": 5475,
	"orderId": "00630149",
	"result": "OK",
	"resultType": "SUCCESSFUL",
	"resultDescription": "Acknowledgement"
}

Refund/request

Mediante este método, el comercio inicia el proceso de creación de devolución.

Endpoint donde enviar la petición de refund request mediante POST

				
					https://test.instantcredit.net/api/refund/request

Attributes

orderIdrequired

string

ID de la orden en el entorno del comercio. Debe ser un identificador único.

123

refundIdrequired

string

ID de la devolución. Debe ser un identificador único.

amountrequired

string

La candidad a devolver. El separador de decimales debe ser el punto.

240.10

currencyrequired

string

Código ISO de tres letras.

EUR

countryrequired

string

Código ISO de dos letras.

Header

				
					Content-Type: application/json
Authorization: Bearer [accessToken]
Signature: [signature]

Body

				
					{  
   "orderId":"124",
   "refundId":"15",
   "amount":"240.10",
   "currency":"EUR",
   "country":"ES"
}

Response

Attributes

orderIdrequired

string

ID de la orden en el entorno del comercio. Debe ser un identificador único.

123

refundIdrequired

string

ID de la devolución. Debe ser un identificador único.

result

enum

SUCCESSFUL (1)

string

EXCESSIVE_REFUND_AMOUNT (2)

string

DIFFERENT_CURRENCY (3)

string

INCORRECT_COUNTRY (4)

string

NONEXISTENT_ORDER (5)

string

DUPLICATED_REFUND (6)

string

UNDEFINED (7)

string

resultDescription

enum

Credit request correctly received. (1)

string

The “birthDate” has an invalid format, it should be “yyyy-MM-DD” : 11-11-2001 (2)

string

The “registrationDate” has an invalid format, it should be “yyyy-MM-DD” : 14-04-1995 (2)

string

The “date” has an invalid format, it should be “yyyy-MM-DD hh:mm:ss” : 11-11-2014 23:30:00 (2)

string

The orderId value has been provided before from the same Merchant : 123456 (3)

string

There are no Lenders available to offer that credit. (4)

string

The Currency value is not allowed: EUR (5)

string

The Country value is not allowed: ES (6)

string

Undefined error (7)

string

Header

				
					Content-Type:application/json
Signature: [signature]

Body

				
					{  
   "orderId":"124",
   "refundId":"15",
   "result":"OK",
   "resultType":"SUCCESSFUL",
   "resultDescription":"Refund Request Successfully Created."
}

Refund/confirmation

Esta llamada se utilizará para confirmar si la devolución ha finalizado correctamente o ha fallado.

Endpoint donde se va a recibir la petición de refund confirmation mediante POST que enviará Instant Credit a la plataforma del comercio

				
					Url que se deberá facilitar al equipo de Instant Credit para configurar en la cuenta del comercio.

Attributes

orderIdrequired

string

ID de la orden en el entorno del comercio. Este valor es el mismo que se ha facilitado en la petición de refund request.

124

refundIdrequired

string

ID de la devolución. Este valor es el mismo que se ha facilitado en la petición de refund request.

amountrequired

string

La candidad a devolver. Este valor es el mismo que se ha facilitado en la petición de refund request.

240.10

currencyrequired

string

Código ISO de tres letras. Este valor es el mismo que se ha facilitado en la petición de refund request.

EUR

countryrequired

string

Código ISO de dos letras. Este valor es el mismo que se ha facilitado en la petición de refund request.

result

enum

Resultado de la petición de devolución. Si el resultado es OK significa que la devolución se ha completado correctamente. De lo contrario, si el resultado es FAIL significa que la devolución no se ha podido completar.

string

FAIL

string

resultType

enum

Tipo de la respuesta.

SUCCESSFUL (1)

string

UNDEFINED (2)

string

resultDescription

enum

Descripción de la respuesta.

Refund successfully confirmed. (1)

string

Undefined error (2)

string

Header

				
					Content-Type: application/json
Signature: [signature]

Body

				
					{
   "result": "OK",
   "country": "ES",
   "amount": "516.17",
   "orderId": "318078",
   "currency": "EUR",
   "resultDescription": "Refund successfully confirmed",
   "resultType": "SUCCESSFUL",
   "transactionId": 12345
}

Response

La refund confirmation se debe responder siempre, no se trata de generar una nueva petición contra las APIs de Instant Credit sino en contestar a la comunicación iniciada por Instant Credit a la url definida como Url de devolución en la configuración de la cuenta del comercio.

La refund confirmation debe ser respondida siempre con un result: OK, ya que el «result OK» significa que el comercio ha recibido correctamente la notificación y que actuará en consecuencia. Si el comercio recibe un result OK significa que la devolución se ha completado correctamente, no obstante, si el comercio recibe un result FAIL significa que esa devolución no se ha completado correctamente.

Es importante que en el «result» el comercio siempre responda con un result OK y se incluya, también, en la respuesta a la credit confirmation la Signature en el header.

Attributes

orderIdrequired

string

ID de la orden en el entorno del comercio. Este valor es el mismo que se ha facilitado en la petición de refund request.

124

refundIdrequired

string

ID de la devolución. Este valor es el mismo que se ha facilitado en la petición de refund request.

result

string

Confirmación de la recepción de la refund confirmation y su correcto procesamiento.

Único valor disponible.

resultTyperequiered

string

Tipo de la respuesta.

Se usa siempre el mismo valor. Único valor disponible.

SUCCESSFUL

resultDescription

string

Descripción de la respuesta.

Se usa siempre el mismo valor. Único valor disponible.

Acknowledgement

Header

				
					Content-Type: application/json
Signature: [signature]

Body

				
					{
   "result": "OK",
   "orderId": "318078",
   "resultDescription": "Order processed successfully",
   "resultType": "SUCCESSFUL",
   "transactionId": 12345
}

Clientes

Comercios

InstantCredit

Legal

Síguenos en

Sabadell Consumer Finance S.A.U con domicilio social en Pl. Catalunya, 1, 08201 SABADELL, NIF A63574719, inscrito en el R. Mercantil de Barcelona, tomo 42.960, folio 80, hoja B295423, inscripción 73.
Correo electrónico AtencionAlClienteSCF@bancsabadell.com.
Todos los derechos reservados.