Open Banking in Spain

General information

Interaction diagram

Payment processing by using the Open Banking in Spain payment method requires merchant's web service, one of the interfaces and the payment platform of ecommpay, as well as one of the bank services which supports this payment method.

Operations support

* Amount limits and payment processing times depend on banks.

** The basic and threshold times are defined as follows:

• The basic time is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the initiator. The basic time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour (if any input from customer is required). Use the basic time to estimate when to react to the absence of payment result notifications or when to check payment status.
• The threshold time is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the initiator receives the callback with the payment result. A payment is automatically declined, if its waiting time exceeds the threshold time. For individual setting of the threshold time limit, contact ecommpay technical support.

Processing scenarios

In the Open Banking in Spain method, to perform a purchase operation, you need to redirect a customer to the provider service.

Supported banks

Payments through the Open Banking in Spain method are carried out through banks that support the work with this method. Banks have their own identifiers which are used to initiate purchases by using Gate and to display banks on Payment Page when choosing a payment method.

The table below provides information on these banks for informational purposes, it may change without additional notice; for the most recent list of supported banks, contact your ecommpay Key Account Manager or POST the /v2/info/banks/spain/sale/list request using Gate API. This request belongs to the following request group /v2/info/banks/{payment_method}/{operationType}/list.

The sections that follow provide detailed information about what you need to perform payments and how you can analyse the information on payments and operations.

Payment confirmation procedure

The workflow of processing purchases made with Open Banking in Spain implies participation of banks, and in certain cases, processing payments on the side of these banks and the Open Banking in Spain service may take up considerable time (in some cases up to seven or more days). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result (for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the ecommpay payment platform uses a payment confirmation procedure. When you integrate the Open Banking in Spain payment method, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the reversed or decline status (to make monitoring and analysing payments more convenient).

The payment confirmation procedure is performed as follows: after the customer completes all required steps, the payment is processed on the provider service side while the customer is redirected to the payment interface where they receive the information about payment processing. The payment confirmation operation is created on the payment platform side while the payment status is set to awaiting confirmation, the sale operation status is set to success until the information about payment confirmation is received from a service provider side and the corresponding payment status callback is sent to the web service.

The payment confirmation operation can have one of the following final statuses:

• success—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to success and the final callback containing the payment information is sent to the web service.
• decline—when the information regarding the funds not being credited to the recipient is received from a service provider. In this case depending on the project settings, that were configured during integration, the following scenarios are available:
  • The reversal operation is initiated automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the reversed payment status.
  • The payment status is set to decline and the final callback with information that purchase was declined is sent from the payment platform to the web service.

When using this procedure, you can also monitor payment statuses in the Dashboard interface.

General information

In the Open Banking in Spain method, to perform a purchase by using Payment Page, the merchant web service should send a request with all the required parameters and signature to the ecommpay URL and get the callback with the payment result from the payment platform. When opening Payment Page, you can either allow your customer to select the Open Banking in Spain method from the list of other payment methods on Payment Page or have Payment Page opened with the Open Banking in Spain method selected. For more information about preselecting payment methods, see in Preselecting payment methods.

When the Open Banking in Spain method is used, the merchant is required to obtain additional consent of the customer for payment processing and, in some cases, collect additional customer data. For this purpose, corresponding page is displayed on Payment Page.

The full sequence and special aspects of the purchase processing are provided below.

Figure: Purchase processing by using Payment Page

The sections that follow discuss in more details the request format and the Payment Page parameters to use in the Open Banking in Spain payment method and provide the information on the format of callbacks with payment results. For the general information on how to use the API, see Payment Page API Description.

Request format

There are several things you need to consider when using the Open Banking in Spain method:

1. You must provide values for the basic minimum of parameters. Listed below are the parameters that are mandatory for any payment method:
   • project_id—the project ID obtained from ecommpay
   • payment_id—payment ID unique within the project
   • payment_currency—payment currency in ISO-4217 alpha-3 format
   • payment_amount—purchase amount in minor currency units
   • customer_id—the unique ID of the customer within your project
2. It is recommended to specify the first and last names of the customer in the customer_first_name and customer_last_name additional parameters. If the request is missing the parameters, on Payment Page the additional fields are displayed to the customer to input missing data. For more details, see Submission of additional payment information.

   Additionally, when selecting certain banks the customer can be required to specify the International Bank Account Number (IBAN) on Payment Page, while selecting other banks the IBAN is specified on the provider side. Due to the specifics of the payment method this number can only be specified by the customer and can't be used in requests.

3. It is recommended to specify in the request the merchant_return_url parameter with the URL for redirecting the customer to the web service, so that the customer can return to the web service by clicking the corresponding button on the payment form in case the customer does not grant their consent for payment processing. The URL should lead to the checkout page to avoid repeated ordering on the side of the web service.
4. To preselect the Open Banking payment method group, specify the openbanking group code in the force_payment_group parameter.

5. You can customise the selecting payment method page on Payment Page.

   By default, the banks are grouped in one Spanish banks button on Payment Page, so the selection of a bank is carried out in two steps. First, the Open Banking in Spain method is chosen among others, and then the bank is selected on the next page with the list of the banks.

   There are several options for displaying the page with the selecting of payment method on Payment Page:

   • To display banks grouped in one Spanish banks button on Payment Page in the list of payment methods.
   • To display only one Spanish banks button without other payment methods. To preselect Open Banking in Spain as the payment method on Payment Page, pass the code online-spanish-banks in the force_payment_method parameter. The list of the banks from Open Banking in Spain group with separate buttons are displayed to a customer on Payment Page bypassing the page with the payment method selection.
   • To display the banks with separate buttons in the list of payment methods. You need to pass true in the split_banks parameter in the request for opening in the payment_methods_options string.

     "payment_methods_options": "{\"online_spanish_banks\": {\"split_banks\": true}}"
     

   • To display a button of a specific bank (one or several) from Open Banking in Spain group on Payment Page in the list of payment methods, pass the bank identifier in the banks_id parameter. If it is necessary to display several banks from a group, pass the identifiers of these banks separated by a comma with a space.

     "payment_methods_options": "{\"online_spanish_banks\": {\"split_banks\": true, \"banks_id\": [6651, 6641]}}"

     Here is the example of a request for opening Payment Page with preselected payment method and a bank.

     Figure: Example of the request with preselecting the payment method and a bank

         { 
           payment_id: '580', 
           payment_amount: 1000, 
           payment_currency: 'EUR', 
           project_id: 120,
           force_payment_method: 'online-spanish-banks',
           payment_methods_options: '{\"online_spanish_banks\": {\"banks_id\": [6651]}}',
           customer_id: 'customer1',
           customer_first_name: 'John',
           customer_last_name: 'Doe',
           signature: "XFyr/D1zXj84lUZVfpbWZol9JAZLnUZoPJKPXRbOqBUpxxa/hOKm2
                                 P8XOqydoyeIi7KdqrcxLFd3GxgPgUzIDg==
         }

6. If required, you can also add any other additional parameters Payment Page supports.
7. After you specify all the parameters you need, you must create the signature for the request. For instructions on how to sign a payment request, see Signature generation and verification.

Thus, a correct payment request in the Open Banking in Spain method must include project, customer, and payment IDs, the currency and the amount of a payment, first and last names of the customer, and URL for redirection, as shown in the following example:

    { 
      payment_id: 'X03936', 
      payment_amount: 1000, 
      payment_currency: 'EUR', 
      project_id: 123, 
      customer_id: 'customer1',
      customer_first_name: 'John',
      customer_last_name: 'Doe',
      merchant_return_url: 'http://example.com/return',
      signature: "kUi2x9dKHA...\/RLCvhtT4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg=="
    }

For information about all parameters available in the Open Banking in Spain method, see Parameters for opening payment form.

Callback format

The Open Banking in Spain method uses the standard format for callbacks to deliver purchase results. For more information, see Callbacks.

The following is the example of a callback with information about a 10.00 EUR purchase made in the 239 project.

 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Spanish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }

The following is the example of a callback with information about a declined purchase.

 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Spanish Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }

Useful links

The following articles can be useful when implementing purchases via Payment Page:

• Interaction concepts—about the interaction with the payment platform by using Payment Page.
• Signature generation and verification—about the procedure of generating and verifying signatures in requests and callbacks.
• Payment models and statuses—about the types, processing models, and possible statuses of supported payments and operations.
• One-time one-step purchase—about processing of one-time one-step purchases by using Payment Page.
• Information of operations performing—about error and response codes that are used in the payment platform to record information about performing of operations.

General information

In the Open Banking in Spain method, when processing a purchase by using Gate, the merchant web service is required to do the following:

1. Send a request with all the required parameters and signature to the ecommpay URL.
2. Redirect the customer to the website of the provider which supports payment processing by using the Open Banking in Spain method.
3. Get the callback with the payment result from the payment platform.

When the Open Banking in Spain method is used, the merchant is required to obtain additional consent of the customer for payment processing and, in some cases, collect additional customer data. The information about the required steps to perform on the side of the merchant web service is provided in the Formats of the data for obtaining customer's consent section, and the description below provides the detailed picture of the payment processing procedure.

The following diagram provides the detailed picture of the payment processing procedure.

The sections that follow discuss in more details the request format and the Gate parameters to use in the Open Banking in Spain payment method and provide the information on the format of callbacks with purchase results.

Request format

1. You perform purchase by sending the /v2/payment/banks/spain/sale request by using POST (HTTP) method. This is an online banking request group: /v2/payment/banks/{payment_method}/sale
2. The following objects and parameters must be specified in the request:
   • Object general—general request identification information:
     • project_id—the project ID obtained from ecommpay
     • payment_id—payment ID unique within the project
     • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
   • Object payment—purchase information:
     • amount—purchase amount in minor currency units
     • currency—purchase currency in ISO-4217 alpha-3 format
   • Object customer—customer information:
     • id—the unique ID of the customer within your project
     • ip_address—customer IP address
   • Object account—customer account information:
     • bank_id—bank identifier
   • Object return_url—URLs for redirecting a customer from the bank website:
     • return—URL for redirecting a customer during any step of the purchase
3. It is recommended to specify the additional parameters. If the request is missing the parameters, the list of parameters is sent in the clarification callback. For more details, see Submission of additional payment information.

   There is the list of recommended objects and parameters:

   • Object customer—customer information:
     • first_name—first name
     • last_name—last name

   Additionally, when selecting certain banks it may be required to specify the International Bank Account Number (IBAN), while selecting other banks the IBAN is specified on the provider side. In cases when the account number needs to be specified before the customer is redirected to the provider side, the clarification callback contains the number parameter of the number object; and if the initial request did not contain the first_name and last_name parameters of the customer object, all three of these parameters are sent in the clarification callback. Due to the specifics of the payment method, if this number is sent in the initial request, it is not taken into account during the initial payment processing, and can either be specified on the web service side after receiving the clarification callback or on the provider side after customer redirection.

4. If required, you can also add any other additional parameters Gate supports.

Thus, a correct payment request through the Open Banking in Spain method must include project, payment, customer, and bank IDs, customer IP-address, signature, currency and amount of the purchase, first and last names of the customer, and URL for redirection, as shown in the following example:

{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 1000,
      "currency": "EUR"
      },
    "customer": {
      "id": "customer1",
      "ip_address": "66.249.64.45",
      "first_name": "John",
      "last_name": "Doe"
    },
    "account":{
      "bank_id": 6651
    },
    "return_url":{
      "return": "http://example.com/return"
 }
}

Formats of the data for obtaining customer's consent

When the Open Banking in Spain method is used, the merchant is required to obtain customer's consent for processing the purchase. To do so, the merchant web service is required to do the following:

1. Receive callback informing about the necessity of obtaining customer's consent (and collecting additional data for payment processing, if needed).
2. Obtain customer's consent (and collect additional data, if needed).
3. Send request with information about customer's consent (and additional data, if needed) to the payment platform.

The callback contains the clarification_fields object with information regarding the parameters and objects required for payment processing. The structure of each object in the clarification_fields object consists of the following:

• type and description parameters—information about the object type and its description
• properties parameter—information about the parameters included in the object
• required array—list of the required parameters
• errors array—information on the reasons for requesting the listed parameters

The properties object and the required array are specified according to the JSON Schema specification, while the errors array contains the property, message and constraint parameters which specify the names, relevant messages and reasons.

The text which is required to be displayed to the customer is specified in the clarification_fields.customer.properties.psu_consent_text.default parameter.

The following is a fragment of a callback informing about the necessity of obtaining customer's consent.

{
"clarification_fields": {
        "customer": {
            "type": "object",
            "description": "Object that contains customer details",
            "properties": {
                "psu_consent": {
                    "type": "string",
                    "description": "Need to request the users consent to make a payment"
                },
                "psu_consent_text": {
                    "type": "string",
                    "description": "The PSU consent text to be displayed on Payment Page",
                    "default": "This consent text with possibly links to some resources here."
                },
                "first_name": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "Customer first name"
                },
                "last_name": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "Customer last name"
                }
            },
            "required": [
                "psu_consent",
                "psu_consent_text",
                "first_name",
                "last_name"
            ],
            "errors": [
                {
                    "property": "customer.psu_consent",
                    "message": "The property psu_consent is required for the clarification request",
                    "constraint": "required"
                },
                {
                    "property": "customer.psu_consent_text",
                    "message": "The property psu_consent_text is required for the clarification request",
                    "constraint": "required"
                },
                {
                    "property": "customer.first_name",
                    "message": "The property first_name is required",
                    "constraint": "required"
                },
                {
                    "property": "customer.last_name",
                    "message": "The property last_name is required",
                    "constraint": "required"
                }
            ]
        },
        "account": {
            "type": "object",
            "description": "Object that contains the details of the customer's bank account for payment performing",
            "properties": {
                "number": {
                    "type": "string",
                    "maxLength": 100,
                    "minLength": 1,
                    "description": "Customer's account number"
                },
                "bank_code": {
                    "type": "string",
                    "maxLength": 100,
                    "minLength": 1,
                    "description": "Customer's bank code"
                }
            },
            "required": [
                "number",
                "bank_code"
            ],
            "errors": [
                {
                    "property": "account.number",
                    "message": "The property number is required",
                    "constraint": "required"
                },
                {
                    "property": "account.bank_code",
                    "message": "The property bank_code is required",
                    "constraint": "required"
                }
            ]
        }
    }
}

Along with the information about customer's consent, it may be required to specify in the request additional customer data described in the Purchase by using Gate section.

Thus, a correct request must include project and payment IDs, information about customer's consent and text displayed to the customer, additional customer data (if needed), and signature, as shown in the following example:

{
    "general": {
        "project_id": 10571,
        "payment_id": "1234567890",
        "signature": "=== signature ==="
    },
    "additional_data": {
        "customer": {
            "psu_consent": "1",
            "psu_consent_text": "=== The PSU consent text to be displayed on payment page ===",
            "first_name": "Firstname",
            "last_name": "Lastname"
        "account": {
            "number": "AB123456789"
        }
    }
}

Formats of the customer redirection data

To redirect a customer from the web service to the Open Banking in Spain site, you must receive a callback from the payment platform containing the URL for redirection in the redirect_data.url parameter and data to be sent in the request body in the redirect_data.body parameter, and use these parameters when opening the HTML page using the method specified in the redirect_data.method parameter.

The following is the callback fragment containing the redirection data.

"redirect": {
        "method": "POST",
        "body": [],
        "encrypted": [],
        "url": "https://web-app.example.com/app/request-token/rq:3R123"
    }

Final callback format

The Open Banking in Spain method uses the standard format for callbacks to deliver purchase results. For more information, see Callbacks.

The following is the example of a callback with information about a 10.00 EUR purchase made in the 239 project.

 {
        "project_id": 239,
        "payment": {
            "id": "TEST_PAYMENT_671446",
            "type": "purchase",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "method": "Spanish Banks",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_671446"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 77796010023511,
            "type": "sale",
            "status": "success",
            "date": "2020-11-03T14:41:38+0000",
            "created_date": "2020-11-03T14:39:34+0000",
            "request_id": "4727897a23d96203f784...d22c87a7f4f473d93-00077797",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 3901,
                "payment_id": "t:5nFu358iuKC3vz8g...zQLtgSSoyAQubVf",
                "auth_code": ""
            }
        },
        "signature": "8UuSBBDvR9RlVXJR+3A3JeYOOPhf...1VlLygAOq+NPNKLu37IZ0kw=="
    }

The following is the example of a callback with information about a declined purchase.

 {
        "customer": {
            "id": "1"
        },
        "project_id": 10801,
        "payment": {
            "id": "TEST_PAYMENT_624318",
            "type": "purchase",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "method": "Spanish Banks",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_624318"
        },
        "operation": {
            "id": 92939010024021,
            "type": "sale",
            "status": "decline",
            "date": "2020-11-03T15:47:39+0000",
            "created_date": "2020-11-03T15:47:02+0000",
            "request_id": "2973231f346e408fcf62f1e3388a...3971c8ccb13-00092940",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 3901,
                "payment_id": ""
            }
        },
        "signature": "GK7q/MHaYQuUqSQiCzWFi.../6UzJhblNPSr7tj1/PWfWgCJLbnaeg=="
    }

Useful links

The following articles can be useful when implementing purchases via Gate:

• Interaction concepts—about the interaction with the payment platform by using Gate.
• Signature generation and verification—about the procedure of generating and verifying signatures in requests and callbacks.
• Payment models and statuses—about the types, processing models, and possible statuses of supported payments and operations.
• One-time one-step purchase—about processing of one-time one-step purchases by using Payment Page.
• Information of operations performing—about error and response codes that are used in the payment platform to record information about performing of operations.

As with other payment methods ecommpay offers, when using the Open Banking in Spain method, you have several options to analyse the information about payments and operations performed by using the method—alone or in conjunction with other methods.

You can load and analyse all the necessary information in Dashboard, for instance you can use the analytic panels on the Analytics tab to this end.

Also, you can export the information for further analysis by using third party analytical tools. The following options are available:

• Dashboard allows you to download reports in CSV and XLS formats—by using the tools on the Payments tab. You can perform export as a one-time download to your local computer or have payment data regularly exported and delivered to email addresses you specify.
• Data API allows you to have payment information exported in JSON format and delivered to a URL you specify. The payment information is exported by using the /operations/get queries.

If you have any further questions regarding payment data analysis, contact ecommpay technical support.