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.
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:
SANDBOX : Allows the realization of fictitious payments to verify the adequate integration of the service. Once the service is integrated, to make test payments you must open the gateway and select a bank from the list. Then use the following bank details:
User: user1 Password: 1234
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.”
- REAL : All payments made will be real. It is recommended to the customer / integrator to make a real payment by himself to verify that the integration process has been carried out satisfactorily. In this case, you must open the INESPAY gateway and select a bank from the list of banks, incorporating the bank details requested by your bank.
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 |
Header
| 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:
- Online shops selling products or services.
- Online platforms or ERPs that need to integrate the bank transfer payment method for buyers / payers.
- System for receiving payment links or URLs for subsequent sending by email or as a payment button on an invoice (pdf, etc.)
Request
| Environment | Type | Url |
|---|---|---|
| SANDBOX | POST | https://apiflow.inespay.com/san/url/signer |
| REAL | POST | https://apiflow.inespay.com/pro/url/signer |
Header
| 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 |
| idDebt | String | Payment order identifier |
| 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:
- Online shops selling products or services with a deferred payment system.
- ERP or online platforms that need to integrate a subscription payment method.
- System for receiving payment links or URLs for subsequent sending by email or as a payment button on an installment invoice (pdf, etc.).
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 |
Header
| 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) |
| 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 |
| 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:
- BBVA: ES2501822200160201933547
- Arquia: ES5031831357110123456789
- Cajamar: ES7930580022842720010677
Answer
| Parameter | Type | Description |
|---|---|---|
| url | String | Signed URL to access the INESPAY payment gateway |
| idDebt | String | Payment order identifier |
| status | String | Success code (200) or error |
| description | String | Description of the status code |
Cancel periodic payments
This service allows you to cancel periodic payment orders that have been previously executed with the periodic payments service
Request
| Environment | Type | Url |
|---|---|---|
| SANDBOX | POST | https://apiflow.inespay.com/san/url/cancel-periodic-payment-signer |
| REAL | POST | https://apiflow.inespay.com/pro/url/cancel-periodic-payment-signer |
Header
| 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 |
|---|---|---|---|
| transactionId | Yes | String | Parameter returned in the notification received when a periodic payment is executed correctly, this parameter is returned in transaction result |
| reference | Yes | String | Internal identifier of the customer / integrator payment, with which you can identify a payment order |
| 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 |
| 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 |
| partnerId | No | String | Unique partner identifier provided by INESPAY. Only available to specific integrators who have previously established this relationship with INESPAY |
Transaction Status
All payment transactions, whether successful or failed, have two possibilities to inform the platform that performs the integration:
- urlOk / urlError: the INESPAY payment gateway performs a Web redirection in the buyer / payer’s browser to the reported URLs. That is, the buyer / payer is redirected to urlOk / urlError, depending on the result of the transaction.
- urlNotif: the INESPAY payment gateway makes the call from its servers to the URL provided in the urlNotif parameter. This call is invisible to the user making the payment. ATTENTION: It is highly recommended to inform the urlNotif and use it to receive the transaction Status provided by INESPAY. In this way, the urlOk / urlError will be used only to redirect the buyer / payer to some web pages of the client / integrator, where they can see the result of the payment. In short, the urlNotif is used to send the transaction Status to the client / integrator platform, regardless of the redirection experienced by the buyer / payer.
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:
- 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
- We convert the hash obtained into a lowercase Hexadecimal text string.
- We encode the result of the previous point in Base64 and obtain the calculated signature.
- 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 |