BankStore IFRAME

BankStore IFRAME/XML Integration

  1. Introduction
  2. IFRAME integration for data capture
    1. Operation of the Bankstore IFRAME (example)
    2. Methods of payment according to the integration
  3. BAKSTORE IFRAME Integration
    1. Execution of User Registration in the system (add_user)
      1. Signature Calculation
      2. Notification (Request to URL)
    2. Execution of charge (User implicit registration in the system) (execute_purchase)
      1. Signature Calculation
      2. Notification (Request to URL)
    3. Execution of subscription registration (User implicit registration in the system) (create_subscription)
      1. Signature Calculation
      2. Notification (Request to URL)
    4. Execution of Charges to an existing user (execute_purchase_token)
      1. Signature Calculation
      2. Notification (Request to URL)
    5. Execution of subscription registration to an existing user (create_subscription_token)
      1. Signature Calculation
      2. Notification (Request to URL)
    6. Execution of Preauthorization Registration (User implicit registration in the system) (create_preauthorization)
      1. Signature Calculation
      2. Notification (Request to URL)
    7. Execution of Preauthorization confirmation (preauthorization_confirm)
      1. Signature Calculation
      2. Notification (Request to URL)
    8. Execution of Preauthorization cancellation (preauthorization_cancel)
      1. Signature Calculation
      2. Notification (Request to URL)
    9. Preauthorization registration to an existing user (create_preauthorization_token)
      1. Signature Calculation
      2. Notification (Request to URL)
    10. Execution of Defered Preauthorization Registration (User implicit registration in the system) (deferred_preauthorization)
      1. Signature Calculation
      2. Notification (Request to URL)
    11. Execution of Defered Preauthorization confirmation (deferred_preauthorization_confirm)
      1. Signature Calculation
      2. Notification (Request to URL)
    12. Execution of Defered Preauthorization cancellation (deferred_preauthorization_cancel)
      1. Signature Calculation
      2. Notification (Request to URL)
    13. Execution of Charges to a user by Reference (execute_purchase_rtoken)
      1. Signature Calculation
      2. Notification (Request to URL)
  4. Overwriting parameters URLOK and URLKO
  5. Card Expiration Notification
    1. Notification (Request to URL)
  6. Appendix I – Operation types
  7. Appendix II - Advanced signature VHASH

Introduction

The purpose of using an IFRAME integration for capturing customer card data is to facilitate compliance with the PCI-DSS standard of the web application. So, the collection of banking data is done in the secure environment of Banco Sabadell and then treated in a Server2Server conversation without the risk of data theft.

IFRAME integration for data capture

This solution enables the generation of an IFRAME with the look&feel predefined in the product control panel. This solution must be activated by Banco Sabadell, so if it does not appear in the control panel, you must request it by opening an administrative ticket (Support → Notification of incidence → Administrative Department)

In this section you will be able to see a preview of the styles applied below. Styles allow reference to external sites but must respond with a digital certificate correctly signed by a trusted entity; otherwise the customer browser will display an error that will generate mistrust in your customer:

In the section on BankStore IFRAME product configuration, just below the preview, you will find the parameters that can be modified from the panel:

These are parameterizable using CSS properties to fit the design of your application.

If the available properties do not meet the needs of the application, you may request a development of specific "Template" by opening an administrative ticket (Support → Notification of incidence → Administrative department).

We will inform you of the steps to be followed and the rules of said development.

The functionalities available in Bankstore IFRAME are

  • Function: (add_user)
  • Function: (execute_purchase)
  • Function: (create_subscription)

Said functionalities are those that involve the collection of the bank details of the customer. Subsequently, once the IDUSER and TOKENUSER data have been collected, SOAP procedures may be used to execute purchases, modify subscriptions, information of user card data, cancel subscriptions, etc...

Operation of the Bankstore IFRAME (example)

The purpose of using an IFRAME integration to capture customer card data is to facilitate compliance with the PCI-DSS standard of the Web application. In this manner, the collection of bank data is carried out in the Banco Sabadell secure environment for processing them later in a Server2Server conversation without risk of the data being susceptible to theft.

In a fictional environment we would find the following scenario:

A business with high recurrence wants to store the bank details of the customer to facilitate future purchases. The techniques for collecting their bank details are two:

  • From their customer account. In their control panel they can modify their billing and shipping information and even their associated credit/debit card. Thus, at the end of the shopping cart, they will make the order payment with just one click.
  • In the first purchase. The customer enters all their bank details in the final process of the cart and these will be stored for future purchases. In this way, storage is done in a "transparent" way when completing the order.

In the first case, the customer is authenticated on the e-commerce platform because it is a previously registered user. They login to their Control Panel and chose to add a credit/debit card to their account to make the payments. The business shows in an integrated way in their control panel an IFRAME generated by Bankstore IFRAME and Banco Sabadell notifies the business of the result. The business stores the IDUSER and TOKENUSER data in the customer's account (they may have several, in order to have multiple cards), to subsequently make payments.

The customer enters the data into an IFRAME of Banco Sabadell (aesthetically integrated with the web of the business) and Banco Sabadell notifies the IDUSER and TOKENUSER data in the case of success, with a delay.

The business stores the data associated with the account of its customer to execute a payment through SOAP XML integration.

In the second case (storage on the first purchase), the customer places an order normally and when selecting the method of payment by credit/debit card, the bank details are requested to proceed to

The bank details are introduced in an IFRAME generated by Banco Sabadell returning both the storage data of the user (IDUSER and TOKENUSER) and the result of the transaction.

This will happen only if the business does not have the two IDUSER and TOKENUSER data. Otherwise the communication would not be done by IFRAME.

In the situation where the business has the IDUSER and TOKENUSER data, either by obtaining them through add_user, the customer has entered their data from their control panel of the business, or through execute_purchase, the customer has already made a purchase previously, the method for making a purchase is different. The method to be used shall be by a Server2Server XML SOAP connection where the business will use the execute_purchase service directly with Banco Sabadell.

It is recommended to use some kind of authentication (PIN or similar) to execute the execute_purchase service to prevent unsolicited purchases.

Said unsolicited purchases are usually subject of dispute of the operation and may incur additional charges from the bank and, if it is a repeated offense, the account could be canceled.

Methods of payment according to the integration

It is important to understand the two integrations in order to build the operation of the business.

3DSecure Payment Non-secure Payment Responsible for card capture
add_user (Bankstore IFRAME) YES YES Banco Sabadell
execute_purchase (Bankstore IFRAME) YES YES Banco Sabadell
create_subscription (Bankstore IFRAME) YES YES Banco Sabadell
add_user (Bankstore SOAP XML) NO YES Business
execute_purchase (Bankstore SOAP XML) NO YES Business
create_subscription (Bankstore SOAP XML) NO YES Business

BAKSTORE IFRAME Integration

Integration via IFRAME (an independent web page located within another web page, in this case that of the Banco Sabadell payment gateway and the store, respectively) is carried out via an IFRAME object with the URL address.

https://api.paycomet.com/gateway/ifr-bankstore

Below is an example of the HTML code (the request parameters have been simplified, which will be covered below):

<iframe title="titulo" src="https://api.paycomet.com/gateway/ifr-bankstore?MERCHANT_MERCHANTCODE=0gs265nc……" width="400" height="525" frameborder="0" marginheight="0" marginwidth="0" scrolling="no" style="border: 0px solid #000000; padding: 0px; margin: 0px"></iframe>

The request parameters must be formatted in the following manner:

PARAM1=VALOR1&PARAM2=VALOR2&PARAM3=VALOR3

Operations allowed:

ID Operation
107 User registration in the system (add_user)
1 Payment (User implicit registration in the system) (execute_purchase)
9 Subscription registration (User implicit registration in the system) (create_subscription)
109 Charge to an existing user (execute_purchase_token)
110 Subscription registration to an existing user (create_subscription_token)
114 Subscription registration to an existing user (execute_purchase_rtoken)
3 Preauthorization Registration (User implicit registration in the system) (create_preauthorization)
6 Preauthorization Confirmation (preauthorization_confirm)
4 Preauthorization Cancelation (preauthorization_cancel)
111 Preauthorization registration to an existing user (create_preauthorization_token)
13 Defered Preauthorization Registration (User implicit registration in the system) (defered_create_preauthorization)
16 Defered Preauthorization Confirmation (defered_preauthorization_confirm)
14 Defered Preauthorization Cancelation (defered_preauthorization_cancel)

Parameters

Execution of User Registration in the system

Function: (add_user)

This operation will register a new user in the system and make the appropriate notification.

In order to execute a successful request, it will be necessary to submit the following information:

Element Content Description
MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
OPERATION [0-9]{1,3} Mandatory. Operation type. For registration of users in the system, the operation type will be 107
LANGUAGE [A-Za-z0-9]{2} Language of the payment environment ("ES","EN","FR","DE","IT")
MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Mandatory. See Signature Calculation.
MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Identifier of the operation.

Signature Calculation

The signature that the business will send to the gateway will be calculated in the following manner (in pseudocode):

SHA512( MERCHANT_MERCHANTCODE + MERCHANT_TERMINAL + OPERATION + MERCHANT_ORDER + md5(PASSWORD))

Notification (Request to URL)

The notification of the user registration in the system will only be sent by request to the URL configured in the control panel. No notification of user registration will be sent by email.

The notification parameters are passed to the target URL using the POST method according to the following table:

Element Content Description
TransactionType Numerical Operation type (107)
TransactionName Alphanumerical Description of the operation type
CardCountry Alphanumerical Card issuing country. May be left empty
DateTime Numerical Date of operation. Format yyyymmddhhmmss
Signature Alphanumerical Notification signature. See Signature Calculation.
Order Alphanumerical Reference provided by business
Response Alphanumerical Final status of operation. OK / KO
ErrorID Numerical Error code.
0 = No error
1 = The operation returned an error
Language Alphanumerical Language of the payment environment ("ES","EN","FR","DE","IT")
AccountCode Alphanumerical Customer code
TpvID Alphanumerical Terminal number
IdUser Numerical Id of the new user registered in the system. In case of error it will be returned empty.
TokenUser Alphanumerical Token of the new user registered in the system. In case of error it will be returned empty.
CardType Alphanumerical (Empty), CREDIT, DEBIT, CHARGE CARD

Signature Calculation

Notifications will include a signature for verification of the integrity of the data. The calculation of the same is made in the following manner (in pseudocode):

SHA512( MERCHANT_MERCHANTCODE + MERCHANT_TERMINAL + OPERATION + MERCHANT_ORDER + DateTime + md5(PASSWORD))
Different languages usage:

function AddUserUrl(
    $transreference,
    $lang = "ES",
    $urlOk = null,
    $urlKo = null,
    $secure3d = false)
{
$pretest = array();
$operation = new stdClass();
$operation->Type = 107;
$operation->Reference = $transreference;
$operation->Language = $lang;
if ($urlOk) {
    $operation->UrlOk = $urlOk;
}
if ($urlKo) {
    $operation->UrlKo = $urlKo;
}
if ($secure3d != false) {
    $operation->Secure3D = $secure3d;
}
$operation->Hash = $this->GenerateHash($operation,
        $operation->Type);
$lastrequest = $this->ComposeURLParams($operation,
        $operation->Type);
$pretest = $this->CheckUrlError($lastrequest);
$pretest["URL_REDIRECT"] = ($this->endpointurl.$lastrequest);
return $this->SendResponse($pretest);
}

Execution of charge (User implicit registration in the system)

Function: (execute_purchase)

This operation will register a new user in the system and will perform the payment operation on that user. The result of the user registration and the payment operation will be notified.

In order to execute a successful request, it will be necessary to submit the following information:

Element Content Description
MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
OPERATION [0-9]{1,3} Mandatory. Operation type in Execution of Charge is: 1
LANGUAGE [A-Za-z0-9]{2} Language of the payment environment ("ES","EN","FR","DE","IT")
MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Mandatory. Signature Calculation.
MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Reference of the operation.
MERCHANT_AMOUNT [0-9]{1,8} Mandatory. Amount of the operation in integer format. 1.00 EURO = 100, 4.50 EUROS = 450...
MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Mandatory. Currency of the transaction. See more information in CURRENCY
MERCHANT_PRODUCTDESCRIPTION [a-zA-Z0-9]{125} Optional. Description of the product
MERCHANT_DESCRIPTOR [A-Za-z0-9]{1,25} Optional. Allows the business to send a text up to 25 characters that will be printed on the customer invoice. Limited to simple characters, no accents or special characters.
3DSECURE [0-1]{1} Optional. Operation performed in secure (value 1) / non-secure (value 0). if not reported: non-secure.
MERCHANT_SCORING [0-100] Optional. Valor de scoring de riesgo de la transacción. Entre 0 y 100.
MERCHANT_DATA
JSON Optional. Client authentication information. The more information is provided in this field, the more likely the authorisation of the operation will be without requiring additional authentication. For this reason, it is recommended to send as much information as possible. See detail
MERCHANT_SCA_EXCEPTION
[LWV|TRA|MIT|COR] Optional TYPE OF EXCEPTION TO THE SECURE PAYMENT. If not specified, Banco Sabadell will try to assign it the most appropriate possible. See detail
MERCHANT_TRX_TYPE [I|R|H|E|D|M|N|C]  Conditional Obligatory only if an MIT exception has been selected in the MERCHANT_SCA_EXCEPTION field. See detail
ESCROW_TARGETS 
{
 "TARGETS": [
  {
    "ESCROW_TARGET_ID": "",
    "ESCROW_TARGET_AMOUNT": ""
  }
 ]
}
Optional Identification of the recipients of receipts in ESCROW operations. It must be a JSON object base64 encoded and urlencoded. Using pseudocode, it would be urlencode( base64_encode( JSON_Object ) )

Signature Calculation

The signature that the business will send to the gateway will be calculated in the following manner (in pseudocode):

SHA512( MERCHANT_MERCHANTCODE + MERCHANT_TERMINAL + OPERATION + MERCHANT_ORDER + MERCHANT_AMOUNT + MERCHANT_CURRENCY + md5(PASSWORD))

Notification (Request to URL)

The notification of the execution of a charge to a new user in the system shall be made as described Request to URL.

Different languages usage:

function ExecutePurchaseUrl(
    $transreference,
    $amount,
    $currency,
    $lang = "ES",
    $description = false,
    $secure3d = false,
    $scoring = null,
    $urlOk = null,
    $urlKo = null,
    $merchant_data = null,
    $merchant_description = null)
{
$pretest = array();
$operation = new stdClass();
$operation->Type = 1;
$operation->Reference = $transreference;
$operation->Amount = $amount;
$operation->Currency = $currency;
$operation->Language = $lang;
$operation->Concept = $description;
if ($secure3d != false) {
    $operation->Secure3D = $secure3d;
}
if ($scoring) {
    $operation->Scoring = (int)$scoring;
}
if ($urlOk) {
    $operation->UrlOk = $urlOk;
}
if ($urlKo) {
    $operation->UrlKo = $urlKo;
}
if ($merchant_data) {
    $operation->Merchant_data = $merchant_data;
}
if ($merchant_description) {
    $operation->Merchant_description = $merchant_description;
}
$operation->Hash = $this->GenerateHash($operation,
        $operation->Type);
$lastrequest = $this->ComposeURLParams($operation,
        $operation->Type);
$pretest = $this->CheckUrlError($lastrequest);
$pretest["URL_REDIRECT"] = ($this->endpointurl.$lastrequest);
return $this->SendResponse($pretest);
}

Execution of subscription registration (User implicit registration in the system)

Function: (create_subscription)

The registration of a subscription implies the registration of a user in the BankStore system of Banco Sabadell. This operation will register a new user in the system and will perform the operation of the first payment of the subscription. The result of the subscription shall be notified.

In order to execute a successful request, it will be necessary to submit the following information:

Element Content Description
MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
OPERATION [0-9]{1,3} Mandatory. Operation type in Subscription registration is: 9
LANGUAGE [A-Za-z0-9]{2} Language of the payment environment ("ES","EN","FR","DE","IT")
MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Mandatory. See Signature Calculation.
MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Reference of the operation.
MERCHANT_AMOUNT [0-9]{1,8} Mandatory. Amount of the operation in integer format. 1.00 EURO = 100, 4.50 EUROS = 450
MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Mandatory. Currency of the transaction. See more information in CURRENCY
SUBSCRIPTION_STARTDATE [0-9]{8} Mandatory. Subscription start date yyyymmdd. IMPORTANT: Subscriptions are charged on the first run if this field has value it will be taken into account for future charges.
SUBSCRIPTION_ENDDATE [0-9]{8} Mandatory. Subscription end date yyyymmdd
SUBSCRIPTION_PERIODICITY [0-9]{1-365} Mandatory. Frequency of the subscription. Expressed in days.
3DSECURE [0-1]{1} Optional. Operation performed in secure (value 1) / non-secure (value 0). If not reported: non-secure.
MERCHANT_SCORING [0-100] Optional. Valor de scoring de riesgo de la transacción. Entre 0 y 100.
MERCHANT_DATA
JSON Optional. Client authentication information. The more information is provided in this field, the more likely the authorisation of the operation will be without requiring additional authentication. For this reason, it is recommended to send as much information as possible. See detail

Signature Calculation

The signature that the business will send to the gateway will be calculated in the following manner (in pseudocode):

SHA512( MERCHANT_MERCHANTCODE + MERCHANT_TERMINAL + OPERATION + MERCHANT_ORDER + MERCHANT_AMOUNT + MERCHANT_CURRENCY + md5(PASSWORD))

Notification (Request to URL)

The notification of the creation of a subscription (which implies the execution of the first payment) to a new user in the system shall be made as described for notifications in Request to URL.

Different languages usage:

function CreateSubscriptionUrl(
    $transreference,
    $amount,
    $currency,
    $startdate,
    $enddate,
    $periodicity,
    $lang = "ES",
    $secure3d = false,
    $scoring = null,
    $urlOk = null,
    $urlKo = null,
    $merchant_data = null)
{
$pretest = array();
$operation = new stdClass();
$operation->Type = 9;
$operation->Reference = $transreference;
$operation->Amount = $amount;
$operation->Currency = $currency;
$operation->Language = $lang;
$operation->StartDate = $startdate;
$operation->EndDate = $enddate;
$operation->Periodicity = $periodicity;
if ($secure3d != false) {
    $operation->Secure3D = $secure3d;
}
if ($scoring) {
    $operation->Scoring = (int)$scoring;
}
if ($urlOk) {
    $operation->UrlOk = $urlOk;
}
if ($urlKo) {
    $operation->UrlKo = $urlKo;
}
if ($merchant_data) {
    $operation->Merchant_data = $merchant_data;
}
$operation->Hash = $this->GenerateHash($operation,
        $operation->Type);
$lastrequest = $this->ComposeURLParams($operation,
        $operation->Type);
$pretest = $this->CheckUrlError($lastrequest);
$pretest["URL_REDIRECT"] = ($this->endpointurl.$lastrequest);
return $this->SendResponse($pretest);
}

Execution of Charges to an existing user

Function: (execute_purchase_token)

This operation makes a charge to a user previously registered in the system. The result of the operation will be notified (as Type 1, Authorization).

In order to execute a successful request, it will be necessary to submit the following information:

Element Content Description
MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
OPERATION [0-9]{1,3} Mandatory. Operation type in Execution of Charge to an existing user is: 109
LANGUAGE [A-Za-z0-9]{2} Language of the payment environment ("ES","EN","FR","DE","IT")
MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Mandatory. See Signature Calculation
MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Reference of the operation.
MERCHANT_PRODUCTDESCRIPTION [a-zA-Z0-9]{125} Optional. Description of the product
MERCHANT_DESCRIPTOR [A-Za-z0-9]{1,25} Optional. Allows the business to send a text up to 25 characters that will be printed on the customer invoice. Limited to simple characters, no accents or special characters.
MERCHANT_AMOUNT [0-9]{1,8} Mandatory. Amount of the operation in integer format. 1.00 EURO = 100, 4.50 EUROS = 450
MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Mandatory. Currency of the transaction. See more information in CURRENCY
IDUSER [0-9]{1,13} Mandatory. Unique identifier of the user registered in the system.
TOKEN_USER [A-Za-z0-9]{1,20} Mandatory. Token code associated with the IDUSER.
3DSECURE [0-1]{1} Optional. Operation performed in secure (value 1) / non-secure (value 0). If not reported: non-secure.
MERCHANT_SCORING [0-100] Optional. Valor de scoring de riesgo de la transacción. Entre 0 y 100.
MERCHANT_DATA
JSON Optional. Client authentication information. The more information is provided in this field, the more likely the authorisation of the operation will be without requiring additional authentication. For this reason, it is recommended to send as much information as possible. See detail
MERCHANT_SCA_EXCEPTION
[LWV|TRA|MIT|COR] Optional TYPE OF EXCEPTION TO THE SECURE PAYMENT. If not specified, Banco Sabadell will try to assign it the most appropriate possible. See detail
MERCHANT_TRX_TYPE [I|R|H|E|D|M|N|C]  Conditional Obligatory only if an MIT exception has been selected in the MERCHANT_SCA_EXCEPTION field. See detail
ESCROW_TARGETS 
{
 "TARGETS": [
  {
    "ESCROW_TARGET_ID": "",
    "ESCROW_TARGET_AMOUNT": ""
  }
 ]
}
Optional Identification of the recipients of receipts in ESCROW operations. It must be a JSON object base64 encoded and urlencoded. Using pseudocode, it would be urlencode( base64_encode( JSON_Object ) )

Signature Calculation

The signature that the business will send to the gateway will be calculated in the following manner (in pseudocode):

SHA512( MERCHANT_MERCHANTCODE + IDUSER + TOKEN_USER + MERCHANT_TERMINAL + OPERATION + MERCHANT_ORDER + MERCHANT_AMOUNT + MERCHANT_CURRENCY + md5(PASSWORD))

Notification (Request to URL)

The notification of the execution of charge to an existing user in the system shall be made as described in Request to URL.

Different languages usage:

function ExecutePurchaseTokenUrl(
    $transreference,
    $amount,
    $currency,
    $iduser,
    $tokenuser,
    $lang = "ES",
    $description = false,
    $secure3d = false,
    $scoring = null,
    $urlOk = null,
    $urlKo = null,
    $merchant_data = null,
    iframe$merchant_description = null)
{
$pretest = array();
$operation = new stdClass();
$operation->Type = 109;
$operation->Reference = $transreference;
$operation->Amount = $amount;
$operation->Currency = $currency;
$operation->IdUser = $iduser;
$operation->TokenUser = $tokenuser;
$operation->Language = $lang;
$operation->Concept = $description;
if ($secure3d != false) {
    $operation->Secure3D = $secure3d;
}
if ($scoring) {
    $operation->Scoring = (int)$scoring;
}
if ($urlOk) {
    $operation->UrlOk = $urlOk;
}
if ($urlKo) {
    $operation->UrlKo = $urlKo;
}
if ($merchant_data) {
    $operation->Merchant_data = $merchant_data;
}
if ($merchant_description) {
    $operation->Merchant_description = $merchant_description;
}
$operation->Hash = $this->GenerateHash($operation,
        $operation->Type);
$lastrequest = $this->ComposeURLParams($operation,
        $operation->Type);
$pretest = $this->CheckUrlError($lastrequest);
$pretest["URL_REDIRECT"] = ($this->endpointurl.$lastrequest);
return $this->SendResponse($pretest);
}

Execution of subscription registration to an existing user

Function: (create_subscription_token)

This operation creates a subscription for a user already in the system and executes the operation of the first payment of the same. The result of the operation will be notified (as Type 9, Subscription).

In order to execute a successful request, it will be necessary to submit the following information:

Element Content Description
MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
OPERATION [0-9]{1,3} Mandatory. Operation type in Subscription registration to an existing user is: 110
LANGUAGE [A-Za-z0-9]{2} Language of the payment environment ("ES","EN","FR","DE","IT")
MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Mandatory. See Signature Calculation.
MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Reference of the operation.
MERCHANT_AMOUNT [0-9]{1,8} Mandatory. Amount of the operation in integer format. 1.00 EURO = 100, 4.50 EUROS = 450
MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Mandatory. Currency of the transaction. See more information in CURRENCY
SUBSCRIPTION_STARTDATE [0-9]{8} Mandatory. Subscription start date yyyymmdd. IMPORTANT: Subscriptions are charged on the first run if this field has value it will be taken into account for future charges.
SUBSCRIPTION_ENDDATE [0-9]{8} Mandatory. Subscription end date yyyymmdd
SUBSCRIPTION_PERIODICITY [0-9]{1-365} Mandatory. Frequency of the subscription. Expressed in days.
IDUSER [0-9]{1,13} Mandatory. Unique identifier of the user registered in the system.
TOKEN_USER [A-Za-z0-9]{1,20} Mandatory. Token code associated with the IDUSER.
3DSECURE [0-1]{1} Optional. Operation performed in secure (value 1) / non-secure (value 0). If not reported: non-secure.
MERCHANT_SCORING [0-100] Optional. Valor de scoring de riesgo de la transacción. Entre 0 y 100.
MERCHANT_DATA
JSON Optional. Client authentication information. The more information is provided in this field, the more likely the authorisation of the operation will be without requiring additional authentication. For this reason, it is recommended to send as much information as possible. See detail

Signature Calculation

The signature that the business will send to the gateway will be calculated in the following manner (in pseudocode):

SHA512( MERCHANT_MERCHANTCODE + IDUSER + TOKEN_USER + MERCHANT_TERMINAL + OPERATION + MERCHANT_ORDER + MERCHANT_AMOUNT + MERCHANT_CURRENCY + md5(PASSWORD))

Notification (Request to URL)

The notification of the execution of charge to an existing user in the system shall be made as described in Request to URL.

Different languages usage:

function CreateSubscriptionTokenUrl(
    $transreference,
    $amount,
    $currency,
    $startdate,
    $enddate,
    $periodicity,
    $iduser,
    $tokenuser,
    $lang = "ES",
    $secure3d = false,
    $scoring = null,
    $urlOk = null,
    $urlKo = null,
    $merchant_data = null)
{
$pretest = array();
$operation = new stdClass();
$operation->Type = 110;
$operation->Reference = $transreference;
$operation->Amount = $amount;
$operation->Currency = $currency;
$operation->Language = $lang;
$operation->StartDate = $startdate;
$operation->EndDate = $enddate;
$operation->Periodicity = $periodicity;
$operation->IdUser = $iduser;
$operation->TokenUser = $tokenuser;
if ($secure3d != false) {
    $operation->Secure3D = $secure3d;
}
if ($scoring) {
    $operation->Scoring = (int)$scoring;
}
if ($urlOk) {
    $operation->UrlOk = $urlOk;
}
if ($urlKo) {
    $operation->UrlKo = $urlKo;
}
if ($merchant_data) {
    $operation->Merchant_data = $merchant_data;
}
$operation->Hash = $this->GenerateHash($operation,
        $operation->Type);
$lastrequest = $this->ComposeURLParams($operation,
        $operation->Type);
$pretest = $this->CheckUrlError($lastrequest);
$pretest["URL_REDIRECT"] = ($this->endpointurl.$lastrequest);
return $this->SendResponse($pretest);
}

Execution of Preauthorization Registration (User implicit registration in the system)

Function: (create_preauthorization)

This operation will register a new user in the system and perform the operation of preauthorization registration. The result of the user registration and the preauthorization operation shall be notified.

In order to execute a successful request, it will be necessary to submit the following information:

Element Content Description
MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
OPERATION [0-9]{1,3} Mandatory. Operation type in Preauthorization registration is: 3
LANGUAGE [A-Za-z0-9]{2} Language of the payment environment ("ES","EN","FR","DE","IT")
MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Mandatory. See Signature Calculation.
MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Reference of the operation.
MERCHANT_AMOUNT [0-9]{1,8} Mandatory. Amount of the operation in integer format. 1.00 EURO = 100, 4.50 EUROS = 450
MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Mandatory. Currency of the transaction. See more information in CURRENCY
3DSECURE [0-1]{1} Optional. Operation performed in secure (value 1) / non-secure (value 0). If not reported: non-secure.
MERCHANT_PRODUCTDESCRIPTION [a-zA-Z0-9]{125} Optional. Description of the product
MERCHANT_SCORING [0-100] Optional. Valor de scoring de riesgo de la transacción. Entre 0 y 100.
MERCHANT_DATA
JSON Optional. Client authentication information. The more information is provided in this field, the more likely the authorisation of the operation will be without requiring additional authentication. For this reason, it is recommended to send as much information as possible. See detail
MERCHANT_SCA_EXCEPTION
[LWV|TRA|MIT|COR] Optional TYPE OF EXCEPTION TO THE SECURE PAYMENT. If not specified, Banco Sabadell will try to assign it the most appropriate possible. See detail
MERCHANT_TRX_TYPE [I|R|H|E|D|M|N|C]  Conditional Obligatory only if an MIT exception has been selected in the MERCHANT_SCA_EXCEPTION field. See detail
ESCROW_TARGETS 
{
 "TARGETS": [
  {
    "ESCROW_TARGET_ID": "",
    "ESCROW_TARGET_AMOUNT": ""
  }
 ]
}
Optional Identification of the recipients of receipts in ESCROW operations. It must be a JSON object base64 encoded and urlencoded. Using pseudocode, it would be urlencode( base64_encode( JSON_Object ) )

Signature Calculation

The signature that the business will send to the gateway will be calculated in the following manner (in pseudocode):

SHA512( MERCHANT_MERCHANTCODE + MERCHANT_TERMINAL + OPERATION + MERCHANT_ORDER + MERCHANT_AMOUNT + MERCHANT_CURRENCY + md5(PASSWORD))

Notification (Request to URL)

The notification of the execution of charge to an existing user in the system shall be made as described in Request to URL.

Different languages usage:

function CreatePreauthorizationUrl(
    $transreference,
    $amount,
    $currency,
    $lang = "ES",
    $description = false,
    $secure3d = false,
    $scoring = null,
    $urlOk = null,
    $urlKo = null,
    $merchant_data = null,
    $merchant_description = null)
{
$pretest = array();
$operation = new stdClass();
$operation->Type = 3;
$operation->Reference = $transreference;
$operation->Amount = $amount;
$operation->Currency = $currency;
$operation->Language = $lang;
$operation->Concept = $description;
if ($secure3d != false) {
    $operation->Secure3D = $secure3d;
}
if ($scoring) {
    $operation->Scoring = (int)$scoring;
}
if ($urlOk) {
    $operation->UrlOk = $urlOk;
}
if ($urlKo) {
    $operation->UrlKo = $urlKo;
}
if ($merchant_data) {
    $operation->Merchant_data = $merchant_data;
}
if ($merchant_description) {
    $operation->Merchant_description = $merchant_description;
}
$operation->Hash = $this->GenerateHash($operation,
        $operation->Type);
$lastrequest = $this->ComposeURLParams($operation,
        $operation->Type);
$pretest = $this->CheckUrlError($lastrequest);
$pretest["URL_REDIRECT"] = ($this->endpointurl.$lastrequest);
return $this->SendResponse($pretest);
}

Execution of Preauthorization confirmation

Function: (preauthorization_confirm)

This operation will perform the operation of preauthorization confirmation. The result of the preauthorization confirmation operation shall be notified.

In order to execute a successful request, it will be necessary to submit the following information:

Element Content Description
MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
OPERATION [0-9]{1,3} Mandatory. Operation type in Preauthorization confirmation is: 6
LANGUAGE [A-Za-z0-9]{2} Language of the payment environment ("ES","EN","FR","DE","IT")
MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Mandatory. See Signature Calculation.
MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Reference of the operation.
MERCHANT_AMOUNT [0-9]{1,8} Mandatory. Amount of the operation in integer format. 1.00 EURO = 100
4.50 EUROS = 450
MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Mandatory. Currency of the transaction. See more information in CURRENCY
3DSECURE [0-1]{1} Optional. Operation performed in secure (value 1) / non-secure (value 0). If not reported: non-secure.
MERCHANT_PRODUCTDESCRIPTION [a-zA-Z0-9]{125} Optional. Description of the product
MERCHANT_DESCRIPTOR [A-Za-z0-9]{1,25} Optional. Allows the business to send a text up to 25 characters that will be printed on the customer invoice. Limited to simple characters, no accents or special characters.
IDUSER [0-9]{1,13} Mandatory. Unique identifier of the user registered in the system.
TOKEN_USER [A-Za-z0-9]{1,20} Mandatory. Token code associated with the IDUSER.

Signature Calculation

The signature that the business will send to the gateway will be calculated in the following manner (in pseudocode):

SHA512( MERCHANT_MERCHANTCODE + IDUSER + TOKEN_USER + MERCHANT_TERMINAL + OPERATION + MERCHANT_ORDER + MERCHANT_AMOUNT + md5(PASSWORD))

Notification (Request to URL)

The notification of the execution of charge to an existing user in the system shall be made as described in Request to URL.

Different languages usage:

function PreauthorizationConfirmUrl(
    $transreference,
    $amount,
    $currency,
    $iduser,
    $tokenuser,
    $lang = "ES",
    $description = false,
    $secure3d = false,
    $urlOk = null,
    $urlKo = null)
{
$pretest = array();
$operation = new stdClass();
$operation->Type = 6;
$operation->Reference = $transreference;
$operation->Amount = $amount;
$operation->Currency = $currency;
$operation->Language = $lang;
$operation->Concept = $description;
$operation->IdUser = $iduser;
$operation->TokenUser = $tokenuser;
if ($secure3d != false) {
    $operation->Secure3D = $secure3d;
}
if ($urlOk) {
    $operation->UrlOk = $urlOk;
}
if ($urlKo) {
    $operation->UrlKo = $urlKo;
}
$check_user_exist = $this->InfoUser($operation->IdUser,
        $operation->TokenUser);
if ($check_user_exist->DS_ERROR_ID != 0) {
    return $this->SendResponse(array("DS_ERROR_ID" => $check_user_exist->DS_ERROR_ID));
}
$operation->Hash = $this->GenerateHash($operation,
        $operation->Type);
$lastrequest = $this->ComposeURLParams($operation,
        $operation->Type);
$pretest = $this->CheckUrlError($lastrequest);
$pretest["URL_REDIRECT"] = ($this->endpointurl.$lastrequest);
return $this->SendResponse($pretest);
}

Execution of Preauthorization cancellation

Function: (preauthorization_cancel)

This operation will perform the operation of preauthorization cancellation. The result of the preauthorization cancellation operation shall be notified.

In order to execute a successful request, it will be necessary to submit the following information:

Element Content Description
MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
OPERATION [0-9]{1,3} Mandatory. Operation type in Preauthorization confirmation is: 4
LANGUAGE [A-Za-z0-9]{2} Language of the payment environment ("ES","EN","FR","DE","IT")
MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Mandatory. See Signature Calculation.
MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Reference of the operation.
MERCHANT_AMOUNT [0-9]{1,8} Mandatory. Amount of the operation in integer format. 1.00 EURO = 100
4.50 EUROS = 450
MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Mandatory. Currency of the transaction. See more information in CURRENCY
3DSECURE [0-1]{1} Optional. Operation performed in secure (value 1) / non-secure (value 0). If not reported: non-secure.
MERCHANT_PRODUCTDESCRIPTION [a-zA-Z0-9]{125} Optional. Description of the product
IDUSER [0-9]{1,13} Mandatory. Unique identifier of the user registered in the system.
TOKEN_USER [A-Za-z0-9]{1,20} Mandatory. Token code associated with the IDUSER.

Signature Calculation

The signature that the business will send to the gateway will be calculated in the following manner (in pseudocode):

SHA512( MERCHANT_MERCHANTCODE + IDUSER + TOKEN_USER + MERCHANT_TERMINAL + OPERATION + MERCHANT_ORDER + MERCHANT_AMOUNT + md5(PASSWORD))

Notification (Request to URL)

The notification of the execution of charge to an existing user in the system shall be made as described in Request to URL.

Different languages usage:

function PreauthorizationCancelUrl(
    $transreference,
    $amount,
    $currency,
    $iduser,
    $tokenuser,
    $lang = "ES",
    $description = false,
    $secure3d = false,
    $urlOk = null,
    $urlKo = null)
{
$pretest = array();
$operation = new stdClass();
$operation->Type = 4;
$operation->Reference = $transreference;
$operation->Amount = $amount;
$operation->Currency = $currency;
$operation->Language = $lang;
$operation->Concept = $description;
$operation->IdUser = $iduser;
$operation->TokenUser = $tokenuser;
if ($secure3d != false) {
    $operation->Secure3D = $secure3d;
}
if ($urlOk) {
    $operation->UrlOk = $urlOk;
}
if ($urlKo) {
    $operation->UrlKo = $urlKo;
}
$check_user_exist = $this->InfoUser($operation->IdUser,
        $operation->TokenUser);
if ($check_user_exist->DS_ERROR_ID != 0) {
    return $this->SendResponse(array("DS_ERROR_ID" => $check_user_exist->DS_ERROR_ID));
}
$operation->Hash = $this->GenerateHash($operation,
        $operation->Type);
$lastrequest = $this->ComposeURLParams($operation,
        $operation->Type);
$pretest = $this->CheckUrlError($lastrequest);
$pretest["URL_REDIRECT"] = ($this->endpointurl.$lastrequest);
return $this->SendResponse($pretest);
}

Preauthorization registration to an existing user

Function: (create_preauthorization_token)

This operation performs the operation of preauthorization for a user previously registered in the system. The result of the operation will be notified (as Type 3, Preauthorization).

In order to execute a successful request, it will be necessary to submit the following information:

Element Content Description
MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
OPERATION [0-9]{1,3} Mandatory. Operation type in Execution of Preauthorization for an existing user is: 111
LANGUAGE [A-Za-z0-9]{2} Language of the payment environment ("ES","EN","FR","DE","IT")
MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Mandatory. See Signature Calculation
MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Reference of the operation.
MERCHANT_AMOUNT [0-9]{1,8} Mandatory. Amount of the operation in integer format. 1.00 EURO = 100
4.50 EUROS = 450
MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Mandatory. Currency of the transaction. See more information in CURRENCY
IDUSER [0-9]{1,13} Mandatory. Unique identifier of the user registered in the system.
TOKEN_USER [A-Za-z0-9]{1,20} Mandatory. Token code associated with the IDUSER.
3DSECURE [0-1]{1} Optional. Operation performed in secure (value 1) / non-secure (value 0). If not reported: non-secure.
MERCHANT_SCORING [0-100] Optional. Valor de scoring de riesgo de la transacción. Entre 0 y 100.
MERCHANT_DATA
JSON Optional. Client authentication information. The more information is provided in this field, the more likely the authorisation of the operation will be without requiring additional authentication. For this reason, it is recommended to send as much information as possible. See detail
MERCHANT_SCA_EXCEPTION
[LWV|TRA|MIT|COR] Optional TYPE OF EXCEPTION TO THE SECURE PAYMENT. If not specified, Banco Sabadell will try to assign it the most appropriate possible. See detail
MERCHANT_TRX_TYPE [I|R|H|E|D|M|N|C]  Conditional Obligatory only if an MIT exception has been selected in the MERCHANT_SCA_EXCEPTION field. See detail
ESCROW_TARGETS 
{
 "TARGETS": [
  {
    "ESCROW_TARGET_ID": "",
    "ESCROW_TARGET_AMOUNT": ""
  }
 ]
}
Optional Identification of the recipients of receipts in ESCROW operations. It must be a JSON object base64 encoded and urlencoded. Using pseudocode, it would be urlencode( base64_encode( JSON_Object ) )

Signature Calculation

The signature that the business will send to the gateway will be calculated in the following manner (in pseudocode):

SHA512( MERCHANT_MERCHANTCODE + IDUSER + TOKEN_USER + MERCHANT_TERMINAL + OPERATION + MERCHANT_ORDER + MERCHANT_AMOUNT + MERCHANT_CURRENCY + md5(PASSWORD))

Notification (Request to URL)

The notification of the execution of charge to an existing user in the system shall be made as described in Request to URL.

Different languages usage:

function CreatePreauthorizationTokenUrl(
    $transreference,
    $amount,
    $currency,
    $iduser,
    $tokenuser,
    $lang = "ES",
    $description = false,
    $secure3d = false,
    $scoring = null,
    $urlOk = null,
    $urlKo = null,
    $merchant_data = null,
    $merchant_description = null)
{
$pretest = array();
$operation = new stdClass();
$operation->Type = 111;
$operation->Reference = $transreference;
$operation->Amount = $amount;
$operation->Currency = $currency;
$operation->Language = $lang;
$operation->Concept = $description;
$operation->IdUser = $iduser;
$operation->TokenUser = $tokenuser;
if ($secure3d != false) {
    $operation->Secure3D = $secure3d;
}
if ($scoring) {
    $operation->Scoring = (int)$scoring;
}
if ($urlOk) {
    $operation->UrlOk = $urlOk;
}
if ($urlKo) {
    $operation->UrlKo = $urlKo;
}
if ($merchant_data) {
    $operation->Merchant_data = $merchant_data;
}
if ($merchant_description) {
    $operation->Merchant_description = $merchant_description;
}
$check_user_exist = $this->InfoUser($operation->IdUser,
        $operation->TokenUser);
if ($check_user_exist->DS_ERROR_ID != 0) {
    return $this->SendResponse(array("DS_ERROR_ID" => $check_user_exist->DS_ERROR_ID));
}
$operation->Hash = $this->GenerateHash($operation,
        $operation->Type);
$lastrequest = $this->ComposeURLParams($operation,
        $operation->Type);
$pretest = $this->CheckUrlError($lastrequest);
$pretest["URL_REDIRECT"] = ($this->endpointurl.$lastrequest);
return $this->SendResponse($pretest);
}

Execution of Defered Preauthorization Registration (User implicit registration in the system)

Function: (deferred_preauthorization)

This operation will register a new user on the system and will carry out the deferred pre-authorisation registration operation. The result of the user registration and the deferred pre-authorisation operation will be reported (Type 13).

In order to execute a successful request, it will be necessary to submit the following information:

Element Content Description
MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
OPERATION [0-9]{1,3} Mandatory. Operation type in Defered Preauthorization registration is: 13
LANGUAGE [A-Za-z0-9]{2} Language of the payment environment ("ES","EN","FR","DE","IT")
MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Mandatory. See Signature Calculation.
MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Reference of the operation.
MERCHANT_AMOUNT [0-9]{1,8} Mandatory. Amount of the operation in integer format. 1.00 EURO = 100
4.50 EUROS = 450
MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Mandatory. Currency of the transaction. See more information in CURRENCY
3DSECURE [0-1]{1} Optional. Operation performed in secure (value 1) / non-secure (value 0). If not reported: non-secure.
MERCHANT_PRODUCTDESCRIPTION [a-zA-Z0-9]{125} Optional. Description of the product
MERCHANT_SCORING [0-100] Optional. Valor de scoring de riesgo de la transacción. Entre 0 y 100.
MERCHANT_DATA
JSON Optional. Client authentication information. The more information is provided in this field, the more likely the authorisation of the operation will be without requiring additional authentication. For this reason, it is recommended to send as much information as possible. See detail
MERCHANT_SCA_EXCEPTION
[LWV|TRA|MIT|COR] Optional TYPE OF EXCEPTION TO THE SECURE PAYMENT. If not specified, Banco Sabadell will try to assign it the most appropriate possible. See detail
MERCHANT_TRX_TYPE [I|R|H|E|D|M|N|C]  Conditional Obligatory only if an MIT exception has been selected in the MERCHANT_SCA_EXCEPTION field. See detail
ESCROW_TARGETS 
{
 "TARGETS": [
  {
    "ESCROW_TARGET_ID": "",
    "ESCROW_TARGET_AMOUNT": ""
  }
 ]
}
Optional Identification of the recipients of receipts in ESCROW operations. It must be a JSON object base64 encoded and urlencoded. Using pseudocode, it would be urlencode( base64_encode( JSON_Object ) )

Signature Calculation

The signature that the business will send to the gateway will be calculated in the following manner (in pseudocode):

SHA512( MERCHANT_MERCHANTCODE + MERCHANT_TERMINAL + OPERATION + MERCHANT_ORDER + MERCHANT_AMOUNT + MERCHANT_CURRENCY + md5(PASSWORD))

Notification (Request to URL)

The deferred pre-authorisation notification on the system will be carried out in accordance with section URL call notification.

Different languages usage:

function DeferredPreauthorizationUrl(
    $transreference,
    $amount,
    $currency,
    $lang = "ES",
    $description = false,
    $secure3d = false,
    $scoring = null,
    $urlOk = null,
    $urlKo = null,
    $merchant_data = null,
    $merchant_description = null)
{
$pretest = array();
$operation = new stdClass();
$operation->Type = 13;
$operation->Reference = $transreference;
$operation->Amount = $amount;
$operation->Currency = $currency;
$operation->Language = $lang;
$operation->Concept = $description;
if ($secure3d != false) {
    $operation->Secure3D = $secure3d;
}
if ($scoring) {
    $operation->Scoring = (int)$scoring;
}
if ($urlOk) {
    $operation->UrlOk = $urlOk;
}
if ($urlKo) {
    $operation->UrlKo = $urlKo;
}
if ($merchant_data) {
    $operation->Merchant_data = $merchant_data;
}
if ($merchant_description) {
    $operation->Merchant_description = $merchant_description;
}
$operation->Hash = $this->GenerateHash($operation,
        $operation->Type);
$lastrequest = $this->ComposeURLParams($operation,
        $operation->Type);
$pretest = $this->CheckUrlError($lastrequest);
$pretest["URL_REDIRECT"] = ($this->endpointurl.$lastrequest);
return $this->SendResponse($pretest);
}

Execution of Defered Preauthorization confirmation

Function: (deferred_preauthorization_confirm)

This operation will carry out the deferred pre-authorisation confirmation operation. The result of the deferred pre-authorisation confirmation operation will be reported (Type 16).

In order to execute a successful request, it will be necessary to submit the following information:

Element Content Description
MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
OPERATION [0-9]{1,3} Mandatory. Operation type in Defered Preauthorization confirmation is: 16
LANGUAGE [A-Za-z0-9]{2} Language of the payment environment ("ES","EN","FR","DE","IT")
MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Mandatory. See Signature Calculation.
MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Reference of the operation.
MERCHANT_AMOUNT [0-9]{1,8} Mandatory. Amount of the operation in integer format. 1.00 EURO = 100
4.50 EUROS = 450
MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Mandatory. Currency of the transaction. See more information in CURRENCY
3DSECURE [0-1]{1} Optional. Operation performed in secure (value 1) / non-secure (value 0). If not reported: non-secure.
MERCHANT_PRODUCTDESCRIPTION [a-zA-Z0-9]{125} Optional. Description of the product
IDUSER [0-9]{1,13} Mandatory. Unique identifier of the user registered in the system.
TOKEN_USER [A-Za-z0-9]{1,20} Mandatory. Token code associated with the IDUSER.

Signature Calculation

The signature that the business will send to the gateway will be calculated in the following manner (in pseudocode):

SHA512( MERCHANT_MERCHANTCODE + IDUSER + TOKEN_USER + MERCHANT_TERMINAL + OPERATION + MERCHANT_ORDER + MERCHANT_AMOUNT + md5(PASSWORD))

Notification (Request to URL)

The notification of execution of a deferred pre-authorisation will be carried out in accordance with section URL call notification.

Different languages usage:

function DeferredPreauthorizationConfirmUrl(
    $transreference,
    $amount,
    $currency,
    $iduser,
    $tokenuser,
    $lang = "ES",
    $description = false,
    $secure3d = false,
    $urlOk = null,
    $urlKo = null)
{
$pretest = array();
$operation = new stdClass();
$operation->Type = 16;
$operation->Reference = $transreference;
$operation->Amount = $amount;
$operation->Currency = $currency;
$operation->Language = $lang;
$operation->Concept = $description;
$operation->IdUser = $iduser;
$operation->TokenUser = $tokenuser;
if ($secure3d != false) {
    $operation->Secure3D = $secure3d;
}
if ($urlOk) {
    $operation->UrlOk = $urlOk;
}
if ($urlKo) {
    $operation->UrlKo = $urlKo;
}
$check_user_exist = $this->InfoUser($operation->IdUser,
        $operation->TokenUser);
if ($check_user_exist->DS_ERROR_ID != 0) {
    return $this->SendResponse(array("DS_ERROR_ID" => $check_user_exist->DS_ERROR_ID));
}
$operation->Hash = $this->GenerateHash($operation,
        $operation->Type);
$lastrequest = $this->ComposeURLParams($operation,
        $operation->Type);
$pretest = $this->CheckUrlError($lastrequest);
$pretest["URL_REDIRECT"] = ($this->endpointurl.$lastrequest);
return $this->SendResponse($pretest);
}

Execution of Defered Preauthorization cancellation

Function: (deferred_preauthorization_cancel)

This operation will carry out the deferred pre-authorisation cancellation operation. The result of the deferred pre-authorisation cancellation operation will be reported (Type 14).

In order to execute a successful request, it will be necessary to submit the following information:

Element Content Description
MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
OPERATION [0-9]{1,3} Mandatory. Operation type in Defered Preauthorization cancel is: 14
LANGUAGE [A-Za-z0-9]{2} Language of the payment environment ("ES","EN","FR","DE","IT")
MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Mandatory. See Signature Calculation.
MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Reference of the operation.
MERCHANT_AMOUNT [0-9]{1,8} Mandatory. Amount of the operation in integer format. 1.00 EURO = 100
4.50 EUROS = 450
MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Mandatory. Currency of the transaction. See more information in CURRENCY
3DSECURE [0-1]{1} Optional. Operation performed in secure (value 1) / non-secure (value 0). If not reported: non-secure.
MERCHANT_PRODUCTDESCRIPTION [a-zA-Z0-9]{125} Optional. Description of the product
IDUSER [0-9]{1,13} Mandatory. Unique identifier of the user registered in the system.
TOKEN_USER [A-Za-z0-9]{1,20} Mandatory. Token code associated with the IDUSER.

Signature Calculation

The signature that the business will send to the gateway will be calculated in the following manner (in pseudocode):

SHA512( MERCHANT_MERCHANTCODE + IDUSER + TOKEN_USER + MERCHANT_TERMINAL + OPERATION + MERCHANT_ORDER + MERCHANT_AMOUNT + md5(PASSWORD))

Notification (Request to URL)

The notification of execution of charges to a user by reference will be carried out in accordance with section URL call notification.

Different languages usage:

function DeferredPreauthorizationCancelUrl(
    $transreference,
    $amount,
    $currency,
    $iduser,
    $tokenuser,
    $lang = "ES",
    $description = false,
    $secure3d = false,
    $urlOk = null,
    $urlKo = null)
{
    $pretest = array();
    $operation = new stdClass();
    $operation->Type = 14;
    $operation->Reference = $transreference;
    $operation->Amount = $amount;
    $operation->Currency = $currency;
    $operation->Language = $lang;
    $operation->Concept = $description;
    $operation->IdUser = $iduser;
    $operation->TokenUser = $tokenuser;
    if ($secure3d != false) {
        $operation->Secure3D = $secure3d;
    }
    if ($urlOk) {
        $operation->UrlOk = $urlOk;
    }
    if ($urlKo) {
        $operation->UrlKo = $urlKo;
    }
    $check_user_exist = $this->InfoUser($operation->IdUser,
            $operation->TokenUser);
    if ($check_user_exist->DS_ERROR_ID != 0) {
        return $this->SendResponse(array("DS_ERROR_ID" => $check_user_exist->DS_ERROR_ID));
    }
		$data["MERCHANT_MERCHANTCODE"] = $this->merchantCode;
		$data["MERCHANT_TERMINAL"] = $this->terminal;
		$data["OPERATION"] = $operationtype;
		$data["LANGUAGE"] = $operationdata->Language;
		$data["MERCHANT_MERCHANTSIGNATURE"] = $operationdata->Hash;
        $data["URLOK"] = $operationdata->UrlOk;
        $data["URLKO"] = $operationdata->UrlKo;

    $operation->Hash = $this->GenerateHash($operation,
            $operation->Type);
    $lastrequest = $this->ComposeURLParams($operation,
            $operation->Type);
    $pretest = $this->CheckUrlError($lastrequest);
    $pretest["URL_REDIRECT"] = ($this->endpointurl.$lastrequest);
    return $this->SendResponse($pretest);
}

Execution of Charges to a user by Reference

Function: (execute_purchase_rtoken)

This method allows you to run a charge based on a token previously obtained by Payment by Reference

In order to execute a successful request, it will be necessary to submit the following information:

Element Content Description
MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
OPERATION [0-9]{1,3} Mandatory. Operation type in Execution of Charges to a user by Reference is: 114
LANGUAGE [A-Za-z0-9]{2} Language of the payment environment ("ES","EN","FR","DE","IT")
MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9] Mandatory. See Signature Calculation
MERCHANT_ORDER [A-Za-z0-9]{1,20} Mandatory. Reference of the operation.
MERCHANT_AMOUNT [0-9]{1,8} Mandatory. Amount of the operation in integer format. 1.00 EURO = 100, 4.50 EUROS = 450
MERCHANT_CURRENCY [EUR][USD][GBP][JPY] Mandatory. Currency of the transaction. See more information in CURRENCY
MERCHANT_IDENTIFIER [0-9]{8} Mandatory. Identifier obtained by previous Payment by Reference
MERCHANT_GROUP [0-9]{9} Optional. Code group identificator asociated to the hash unique credit card id
MERCHANT_PRODUCTDESCRIPTION [a-zA-Z0-9]{125} Optional. Description of the product
MERCHANT_DESCRIPTOR [A-Za-z0-9]{1,25} Optional. Allows the business to send a text up to 25 characters that will be printed on the customer invoice. Limited to simple characters, no accents or special characters.
3DSECURE [0-1]{1} Mandatory. Perform operation in secure (value 1) / non-secure (value 0). In Execution of Charges to a user by Reference is: 1
MERCHANT_SCORING [0-100] Optional. Valor de scoring de riesgo de la transacción. Entre 0 y 100.
MERCHANT_DATA
JSON Optional. Client authentication information. The more information is provided in this field, the more likely the authorisation of the operation will be without requiring additional authentication. For this reason, it is recommended to send as much information as possible. See detail
MERCHANT_SCA_EXCEPTION
[LWV|TRA|MIT|COR] Optional TYPE OF EXCEPTION TO THE SECURE PAYMENT. If not specified, Banco Sabadell will try to assign it the most appropriate possible. See detail
MERCHANT_TRX_TYPE [I|R|H|E|D|M|N|C]  Conditional Obligatory only if an MIT exception has been selected in the MERCHANT_SCA_EXCEPTION field. See detail
ESCROW_TARGETS 
{
 "TARGETS": [
  {
    "ESCROW_TARGET_ID": "",
    "ESCROW_TARGET_AMOUNT": ""
  }
 ]
}
Optional Identification of the recipients of receipts in ESCROW operations. It must be a JSON object base64 encoded and urlencoded. Using pseudocode, it would be urlencode( base64_encode( JSON_Object ) )

Signature Calculation

The signature that the business will send to the gateway will be calculated in the following manner (in pseudocode):

SHA512( MERCHANT_MERCHANTCODE + MERCHANT_TERMINAL + OPERATION + MERCHANT_ORDER + MERCHANT_AMOUNT + MERCHANT_CURRENCY + md5(PASSWORD))

Notification (Request to URL)

The notification of execution of charges to a user by reference will be carried out in accordance with section URL call notification.

Overwriting parameters URLOK and URLKO

In addition to the parameters mentioned above for each operation type, and in a generic and transverse manner to all the operations, it is possible to overwrite the URLOK and URLKO parameters. Said parameters tell the system which URLs to redirect the result of the operation to, in terms of their success or denial.

This is available in almost all banks. If you need to use it please check this matter with Banco Sabadell.

Card Expiration Notification

For users registered in the Bankstore system, there is the possibility of receiving an informative notification to alert them of the upcoming expiration of the card for this user/token.

Notification (Request to URL)

The notification parameters are passed to the target URL using the POST method according to the following table:

TransactionType Numerical Operation type (108) See OPERATION TYPES.
TransactionName Alphanumerical Description of operation.
IdUser Numerical Id of the user registered in the system.
Terminal Numerical Terminal Identifier.
Name Alphanumerical Name of the product.
Domain Alphanumerical Domain of the product.
MonthsToExpire Numerical Months to expiration.

In order to receive such notifications it must be specifically enabled by Banco Sabadell. You can contact us through of the customer portal on the menu “Support Notification of incidence”.

Appendix I – Operation types

The operation types that will be notified are detailed in the following table:

ID Operation
1 Authorization
2 Refund
3 Preauthorization
4 Preauthorization cancellation
6 Preauthorization confirmation
9 Subscription
13 Defered Preauthorization Registration
14 Defered Preauthorization Confirmation
16 Defered Preauthorization Cancellation
106 Chargeback
107 Bankstore user registration
108 Card Expiration

Appendix II - Advanced signature VHASH

The advanced signature VHASH aims to secure and keep the integrity of personal data information that may contain the variables sent in the IFRAME generation. This feature must be activated by Banco Sabadell.

The signature that the business will send to the gateway is calculated in the following manner (in pseudocode):

SHA512( MD5( QUERY_STRING + MD5( PASSWORD ) ) )

The calculated signature must be included in the parameters of the call.

Element Content Description
VHASH [A-Za-z0-9]{128} Optional. Advanced signature.

Do you have any unresolved questions?

Enter your account control panel and open a new ticket.

Enter your panel