NAV

INESPAY API

The INESPAY API provides a payment gateway service by bank transfer based on the European standard PSD2 (Payment Service Directive 2). Unlike the payment gateways by bank card, the buyer / payer does not need to enter the number of his credit card to initiate a payment, but simply select the bank where he has a bank account and enter the same bank details that he uses in his online banking.

The INESPAY API can be integrated both as a checkout in an online shop (payment button in a shopping cart), as a transfer payment button in online order request platforms, customer areas, etc. It can also be integrated as a service for receiving links or payment URLs that can later be attached to invoices or emails. In the latter case (payment URLs), the INESPAY API sends the client / integrator the payment links that can later be sent to the buyer / payer to open the INESPAY payment gateway to initiate the payment.

The INESPAY API is built as a REST service, so it can be integrated into any platform, regardless of the programming language used.

Estructura Payflow

Security

The INESPAY API requires an authentication process through an API-KEY and an API-TOKEN, which can be obtained from the INESPAY Dashboard. These keys are mandatory for each call and must be provided in the header (Header) of each request. To access the INESPAY Dashboard, the client / integrator must previously register: INESPAY Registration

The secure HTTPS protocol is used for encryption and data exchange, and the JSON format is used for all API requests and responses.

NOTE: INESPAY keys should never be exposed in public sites or in client-side languages, as it represents a security risk.

Environments

In order to facilitate development, a SANDBOX environment identical to the REAL one is provided that will allow the client / integrator to confirm the correct integration of the service. The keys for the SANDBOX environment are automatically provided in the INESPAY Dashboard. However, to access the keys of the REAL environment it is necessary to contact the INESPAY Support team, requesting to pass to Production: support@inespay.com. As they are 2 identical environments, to go from the SANDBOX environment to the REAL environment (or vice versa), simply change the API-KEY and API-TOKEN credentials of the desired environment. Characteristics:

In case the bank requests any additional field in the Login process, use the value user1. To finalize the payment, the bank will request an additional password. Use any combination of numeric or alphanumeric characters. The OK result is displayed with a page that will tell you “Transaction successful.”

Services

Banks

This service allows you to consult the list of banks available on the Inespay platform.

Petición

Environment Type Url
SANDBOX (test) GET https://apiflow.inespay.com/san/banks
REAL (Production) GET https://apiflow.inespay.com/pro/banks
Param Description
X-Api-Key API-KEY provided by INESPAY
Authorization API-TOKEN provided by INESPAY
Content-Type application/json

Respuesta

Param Type Description
total Integer Number of items returned in data
data Array (Bank) banks array
status String Success code (200) or error
description String Description of the status code

Bank

Param Type Description
bankId String Unique identifier of the bank assigned by INESPAY
name String Bank name
bankCodes Array (String) Array containing the codes that identify the bank accounts of the entity
country String Country
enabled Integer enabled (1) / disabled(0) on the INESPAY platform
enabledPeriodicPayment Integer enabled (1) periodic payments on the INESPAY platform
frequencyPeriodicPayment Array(String) Frequency values availables in case the bank supports periodic payments
bankGroupId Integer Group identifier in case the bank belongs to a banking group
bankGroupName String Name of the banking group

It is possible to request filtered queries, the available filters are described below:

Banks enabled by country

Request to get only enabled banks filtered by country on the Inespay platform.

Environment Type Url
SANDBOX (Test) GET https://apiflow.inespay.com/san/banks?enabled=1&country=ES
REAL (Production) GET https://apiflow.inespay.com/pro/banks?enabled=1&country=ES

Banks with active periodic payments by country

Request to get only banks with periodic payments enabled filtered by country.

Environment Type Url
SANDBOX (Test) GET https://apiflow.inespay.com/san/banks?enabledPeriodicPayment=1&country=ES
REAL (Production) GET https://apiflow.inespay.com/pro/banks?enabledPeriodicPayment=1&country=ES

Simple Payments

This service allows the generation of unique payment orders that will include the necessary data to initiate an ordinary bank transfer: Name of the recipient, destination IBAN, Amount and Concept. This service can be integrated as a payment button in any type of access platform for buyers / payers or as a service for generating URLs to attach to invoices or emails. In all cases, the buyer / payer should access the INESPAY payment gateway to select his bank and complete the payment.

Oriented to the following platforms / systems:

Request

Environment Type Url
SANDBOX POST https://apiflow.inespay.com/san/url/signer
REAL POST https://apiflow.inespay.com/pro/url/signer
Parameter Description
X-Api-Key API-KEY provided by INESPAY
Authorization API-TOKEN provided by INESPAY
Content-Type application/json

Body

Parameter Requeested Type Description
subject Yes String Concept that will appear in the payment detail and in the bank statement
amount Yes Number Payment amount multiplied by 100, without decimals. For example: 355.98 Euros = 35598
reference Yes String Internal identifier of the customer / integrator payment, with which you can identify a payment order
customRecipient No String Customizable information field that allows you to enter the data of a recipient. This field is used by billing or similar platforms that need to inform a different recipient for each payment. Within this parameter, for example, the following data of the recipient of the payment can be informed: commercial name; business name; address … The “;” character is used. to indicate line breaks. Once the payment is completed, INESPAY will return this information to the client / integrator via urlNotif
holderDestiny No String Full name of the destination account holder (recipient)
accountDestiny No String Bank account number of the recipient of the bank transfer (IBAN format). Any IBAN informed in this parameter must be previously validated in the INESPAY Dashboard. Otherwise, the call will fail
expireMinutes No Number Time of validity of the payment generated. In case of not being informed, the validity of the payment will be 30 minutes. The maximum possible time will be 259200 minutes (180 days)
customData No String Customizable field that can be used to save any type of data that is required. If the serialized JSON format is used as String type, all the fields are processed and visible from the INESPAY Dashboard
urlOk No String Return URL (URL Redirect) where the buyer / payer returns when the payment has been made successfully. This information is essential when the buyer / payer comes from an online shop or any other type of platform or ERP and must return to the same environment from which it came, where the status of their order / purchase / invoice is shown.
urlError No String Return URL (URL Redirect) where the buyer / payer is redirected when the payment could not be completed. It is advisable to provide the same return URL as the urlOk, but in this case the payment will not have been completed successfully, so the buyer / payer can retry it again or select another payment method
urlNotif No String URL where the result of the transaction is notified, without repercussion for the buyer / payer. It should be taken into account that, for both the SANDBOX and REAL environments, a urlNotif of a different environment than Local must be reported. Otherwise, the notification will not be possible and an error will be generated
partnerId No String Unique partner identifier provided by INESPAY. Only available to specific integrators who have previously established this relationship with INESPAY
bankIdSelected No String Bank identifier that will appear preselected in the INESPAY gateway. This identifier can be obtained by consulting Banks service.

Here is an example of using the customData field in JSON format serialized as String

customData = {“name”:“Bruce Wayne”, “numDoc”:“11111112L”}

Answer

Parameter Type Description
url String Signed URL to access the INESPAY payment gateway
status String Success code (200) or error
description String Description of the status code

Periodic Payments

This service allows you to generate payment orders that will be repeated during a specific period of time. This service is ideal for the sale of products / services in the form of a subscription or as a deferred payment, which enables the buyer / payer to validate a single payment and leave the order signed for future payments. The operation of this service can be integrated as a payment button in an ERP or online platform or as a service for receiving URLs to attach to invoices or emails. In all cases, the buyer / payer will directly access the interface of his bank to authorize the periodic payment.

Oriented to the following platforms / systems:

Request

Environment Type Url
SANDBOX POST https://apiflow.inespay.com/san/url/periodic-payment-signer
REAL POST https://apiflow.inespay.com/pro/url/periodic-payment-signer
Parameter Description
X-Api-Key API-KEY provided by INESPAY
Authorization API-TOKEN provided by INESPAY
Content-Type application/json

Body

Parameter Requested Type Description
subject Yes String Concept that will appear in the payment detail and in the bank statement
amount Yes Number Payment amount multiplied by 100, without decimals. For example: 355.98 Euros = 35598
reference Yes String Internal identifier of the customer / integrator payment, with which you can identify a payment order
frequency Yes String Periodicity of execution of the periodic payment. Check frequencyPeriodicPayment parameter from Banks to get availables values from each bank.
debtorAccount Yes String IBAN of the buyer / payer who will accept the recurring charge of the payment
startDate Yes String Date from which periodic payments begin (YYYY-MM-DD). The day informed in this parameter will be considered as “execution day”. Therefore, if 2021-01-18 is reported as the payment start date, it will mean that the first payment will be made on January 18, 2021 and from there it will be repeated with the periodicity reported in the frequency field. In the event that the frequency reported was Monthly, the next payment would be executed on February 18, 2021
endDate No String End date of periodic payments (YYYY-MM-DD). If this parameter is not informed, it will be considered an indefinite payment in time
accountDestiny No String Bank account number of the recipient of the bank transfer (IBAN format). Any IBAN informed in this parameter must be previously validated in the INESPAY Dashboard. Otherwise, the call will fail
expireMinutes No Number Time of validity of the payment generated. In case of not being informed, the validity of the payment will be 30 minutes. The maximum possible time will be 259200 minutes (180 days)
customData No String Customizable field that can be used to save any type of data that is required. If the serialized JSON format is used as String type, all the fields are processed and visible from the INESPAY Dashboard
urlOk No String Return URL (URL Redirect) where the buyer / payer returns when the payment has been made successfully. This information is essential when the buyer / payer comes from an online shop or any other type of platform or ERP and must return to the same environment from which it came, where the status of their order / purchase / invoice is shown.
urlError No String Return URL (URL Redirect) where the buyer / payer is redirected when the payment could not be completed. It is advisable to provide the same return URL as the urlOk, but in this case the payment will not have been completed successfully, so the buyer / payer can retry it again or select another payment method
urlNotif No String URL where the result of the transaction is notified, without repercussion for the buyer / payer. It should be taken into account that, for both the SANDBOX and REAL environments, a urlNotif of a different environment than Local must be reported. Otherwise, the notification will not be possible and an error will be generated
customRecipient No String Customizable information field that allows you to enter the data of a recipient. This field is used by billing or similar platforms that need to inform a different recipient for each payment. Within this parameter, for example, the following data of the recipient of the payment can be informed: commercial name; business name; address … The “;” character is used. to indicate line breaks. Once the payment is completed, INESPAY will return this information to the client / integrator via urlNotif
holderDestiny No String Full name of the destination account holder (recipient)
partnerId No String Unique partner identifier provided by INESPAY. Only available to specific integrators who have previously established this relationship with INESPAY

To init a periodic payment in the Sandbox environment, request must be made informing in the debtorAccount parameter one of the following test source accounts:

Answer

Parameter Type Description
url String Signed URL to access the INESPAY payment gateway
status String Success code (200) or error
description String Description of the status code

Transaction Status

All payment transactions, whether successful or failed, have two possibilities to inform the platform that performs the integration:

En ambos casos la petición que se realiza a las URLs informadas es de tipo POST HTTP, con los siguientes parámetros descritos a continuación:

Parameter Type Description
dataReturn String (JSON) It contains the payment parameters:
    status String Success code (200) or error code
    description String Description of the status code
    transactionId String INESPAY payment identifier
    amount Number Payment amount multiplied by 100 without decimals
    reference String Internal identifier of the payment (customizable by the platform)
    dateInitPayment number Timestamp in ms UTC time zone
    accountDestiny String IBAN of the destination account where the payment money has been transferred
signatureDataReturn String DataReturn signature calculated with the HmacSHA256 algorithm, using as key the APIKEY provided by INESPAY and encoded in base64.

Response verification (Signature)

We must always calculate the signature of the data returned in dataReturn and compare it with the signature returned by INESPAY in signatureDataReturn. This ensures that the answer comes from INESPAY. Below we detail the process to perform the signature calculation:

  1. We apply the HmacSHA256 algorithm on dataReturn encoded in Base64, using the API-KEY provided by INESPAY as a key. In this way we get the hash of dataReturn
  2. We convert the hash obtained into a lowercase Hexadecimal text string.
  3. We encode the result of the previous point in Base64 and obtain the calculated signature.
  4. We compare the calculated signature with the signatureDataReturn parameter returned in the payment result response:
    • If calculated signature == signatureDataReturn, we ensure that the response comes from INESPAY (OK).
    • If calculated signature != SignatureDataReturn, the data has been altered by a third party and is not valid (KO).

Response codes

List of status and error codes returned by the INESPAY API.

Code Description Information
200 OK_DEFAULT API request success (OK)
E300 ERROR_DEFAULT Generic error (KO)
E301 INVALID_PARAMS Incorrect parameters error