Bankstore Operational Transfer Integration

  1. Introduction
  2. Split Payment Transfer Process
    1. Pay-In process (Pay-In)
    2. Split Transfer process
    3. Withdrawals(Pay-Out)
  3. API Programming
    1. Execution of purchase execute_purchase
    2. Execution of a Split Payment Transfer split_transfer
    3. Reversal of a Split Payment Transfer split_transfer_reversal
    4. Execution of a Transfer transfer
    5. Reversal of a Transfer transfer_reversal
  4. Signature calculation

Introduction

The Split Payments service is offered as an ideal model for the distribution of balances from a previous payment operation. This service uses BankStore as an integration model, therefore any call to the split_transfer or split_transfer_reversal service must originate with a previous execute_purchase, execute_purchase_dcc or preauthorization_confirm operation.

This will generate a balance on the product from which the transaction originates. This balance will be the transaction total, minus the financial commission of the purchase. Once the purchase operation is finalised, as many split_transfer as desired may be sent to other destination accounts on PAYCOMET. This split_transfer operation can be executed provided that there is a balance in the account of the product that generated the operation and that no more than 90 days have passed since the initial purchase.

The only information necessary to generate a split_transfer to a destination account is the DS_SUBMERCHANT_TERMINAL_SPLITID (called Split Id.). This information may be taken from the PAYCOMET control panel on “My products” -> “Configure product” -> Select the desination product -> “Generate Split Id”.

The Split Id. information must be sent securely to the transaction issuer so that they can deposit the proportional part of their services through the split_transfer after a purchase.

This service is widely used by Marketplaces to charge a single operation to the end client. In this way, the Marketplace receives the total amount of the operation and when the real supplier provides the service or merchandise, they are immediately paid a split_transfer of the total amount of the transaction, minus its commission. It is also very useful for charging commissions for advertising and services, etc., without the end client being affected by two charges. This service also allows the legal protection that European legislation requires with regard to receipt of the amounts by an authorised Payment Entity such as PAYCOMET by Banco de España.

We have attached a simple diagram of the operation of an example transaction:

PAYCOMET Split Transfer Integration

Split Payment Transfer Process

1. Pay-In process (Pay-In)

Charging of the operation may be carried out by any of the processes of the BankStore product from PAYCOMET. These may be:

  • execute_purchase here you can access the service: (by XML or by IFRAME/FULLSCREEN)
  • execute_purchase_dcc here you can access the service: (by XML)
  • preauthorization_confirm here you can access the service: (by XML o por IFRAME/FULLSCREEN)

2. Split Transfer process

The Split Transfer process may be automatic (the program defined by PAYCOMET and the client not changing anything in its integration) or on demand. In case of being on demand, the company must subsequently make a payment, a split_transfer operation to make a deposit in a destination account or a split_transfer_reversal if they wish to reverse a previously executed split_transfer. It is very important to know that these services may always be carried out provided that there is a sufficient balance to cover the amounts of the transfers.

The two services that can be called are:

  • split_transfer here you can access the service: (by XML)
  • split_transfer_reversal here you can access the service: (by XML)

3. Withdrawals(Pay-Out)

The business may withdraw funds from their financial account by the usual PAYCOMET process. This may be automatic or on demand from the PAYCOMET "Retirada de fondos" control panel.

API Programming

Since the entire payment process is performed in the background (server to server) the changes to be performed in the business are totally unrelated to the user experience.

The technology used for the operation with the PAYCOMET payment gateway is SOAP, based on HTTPS to prevent transportation problems through firewalls and other devices while ensuring the safety of operations. There is extensive support for carrying out SOAP requests for the major programming languages used in web environments.

The requests are made through the HTTPS transport protocol, so you must ensure that your system is capable of correctly performing requests and managing security certificates returned by the platform to ensure proper use.

There are several operations that can be launched from the same service. The available operations are described below.

Execution of split transfer

Function: split_transfer

This method allows you to run a split transfer based on a previous authorization

The variables required for making a split transfer request are (in this order):

Element Content Description
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
DS_MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
DS_MERCHANT_ORDER [A-Za-z0-9]{1,70} Mandatory. Reference of the original authorization.
DS_MERCHANT_AUTHCODE [a-zA-Z0-9]{1,40} Authorization bank code of the transaction (required to execute a return).
DS_SUBMERCHANT_TERMINAL_SPLITID [a-z0-9]{64} Identifier for you to receive split payments
DS_SUBMERCHANT_AMOUNT [0-9]{1,8} Amount of the operation in integer format. 1.00 EURO = 100, 4.50 EUROS = 450...
DS_SUBMERCHANT_CURRENCY [EUR][USD][GBP][JPY] Currency of the transaction. See more information in CURRENCY
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9]{64} Mandatory. See SIGNATURE CALCULATION

The response of the service to the request is performed by the return of an array formatted in XML with the various elements described in the following table:

Element Content Description
DS_SUBMERCHANT_AMOUNT [0-9]{1,8} Amount of the operation in integer format. 1.00 EURO = 100, 4.50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Reference of the operation.
DS_SUBMERCHANT_CURRENCY [EUR][USD][GBP][JPY] Currency of the transaction. See more information in MONEDAS
DS_MERCHANT_TRANSFER_AUTHCODE [a-zA-Z0-9]{1,40} Authorization code of the split transfer (required to execute a split transfer reversal)
DS_RESPONSE [0-1]{1} Result of operation. 0 or empty will be erroneous operation and 1 operation completed.
DS_ERROR_ID [0-9]{1,5} In the case of error, the error code generated will be here. If there is no error it will be 0 or empty. The error codes are specified in the document ERROR CODES.

If the request generates an error of some kind (incorrect signature, user not found, etc) all fields will be delivered empty, except “DS_ERROR_ID” which will contain the error code.

If the transaction is correct, the service will return the field DS_RESPONSE the value of which will be 0 or empty in case of error and 1 in case of success.

Execution of split transfer reversal

Function: split_transfer_reversal

This method allows you to run a split transfer reversal based on a previous split transfer

The variables required for making a split transfer reversal request are (in this order):

Element Content Description
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
DS_MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
DS_MERCHANT_ORDER [A-Za-z0-9]{1,70} Mandatory. Reference of the original authorization.
DS_MERCHANT_AUTHCODE [a-zA-Z0-9]{1,40} Authorization bank code of the transaction (required to execute a return).
DS_SUBMERCHANT_TERMINAL_SPLITID [a-z0-9]{64} Identifier for you to receive split payments
DS_SUBMERCHANT_SPLIT_AUTHCODE [a-zA-Z0-9]{1,40} Authorization code of the original split transfer
DS_SUBMERCHANT_AMOUNT [0-9]{1,8} Amount of the operation in integer format. 1.00 EURO = 100, 4.50 EUROS = 450...
DS_SUBMERCHANT_CURRENCY [EUR][USD][GBP][JPY] Currency of the transaction. See more information in CURRENCY
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9]{64} Mandatory. See SIGNATURE CALCULATION

The response of the service to the request is performed by the return of an array formatted in XML with the various elements described in the following table:

Element Content Description
DS_SUBMERCHANT_AMOUNT [0-9]{1,8} Amount of the operation in integer format. 1.00 EURO = 100, 4.50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Reference of the operation.
DS_SUBMERCHANT_CURRENCY [EUR][USD][GBP][JPY] Currency of the transaction. See more information in MONEDAS
DS_MERCHANT_TRANSFER_AUTHCODE [a-zA-Z0-9]{1,40} Authorization code of the split transfer (required to execute a split transfer reversal)
DS_RESPONSE [0-1]{1} Result of operation. 0 or empty will be erroneous operation and 1 operation completed.
DS_ERROR_ID [0-9]{1,5} In the case of error, the error code generated will be here. If there is no error it will be 0 or empty. The error codes are specified in the document ERROR CODES.

If the request generates an error of some kind (incorrect signature, user not found, etc) all fields will be delivered empty, except “DS_ERROR_ID” which will contain the error code.

If the transaction is correct, the service will return the field DS_RESPONSE the value of which will be 0 or empty in case of error and 1 in case of success.

Execution of transfer

Function: transfer

This method allows you to run a transfer

The variables required for making a split transfer are (in this order):

Element Content Description
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
DS_MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
DS_MERCHANT_ORDER [A-Za-z0-9]{1,70} Mandatory. Reference of the original authorization.
DS_SUBMERCHANT_TERMINAL_SPLITID [a-z0-9]{64} Identifier for you to receive split payments
DS_SUBMERCHANT_AMOUNT [0-9]{1,8} Amount of the operation in integer format. 1.00 EURO = 100, 4.50 EUROS = 450...
DS_SUBMERCHANT_CURRENCY [EUR][USD][GBP][JPY] Currency of the transaction. See more information in CURRENCY
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9]{64} Mandatory. See SIGNATURE CALCULATION

The response of the service to the request is performed by the return of an array formatted in XML with the various elements described in the following table:

Element Content Description
DS_SUBMERCHANT_AMOUNT [0-9]{1,8} Amount of the operation in integer format. 1.00 EURO = 100, 4.50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Reference of the operation.
DS_SUBMERCHANT_CURRENCY [EUR][USD][GBP][JPY] Currency of the transaction. See more information in MONEDAS
DS_MERCHANT_TRANSFER_AUTHCODE [a-zA-Z0-9]{1,40} Authorization code of the split transfer (required to execute a split transfer reversal)
DS_RESPONSE [0-1]{1} Result of operation. 0 or empty will be erroneous operation and 1 operation completed.
DS_ERROR_ID [0-9]{1,5} In the case of error, the error code generated will be here. If there is no error it will be 0 or empty. The error codes are specified in the document ERROR CODES.

If the request generates an error of some kind (incorrect signature, user not found, etc) all fields will be delivered empty, except “DS_ERROR_ID” which will contain the error code.

If the transaction is correct, the service will return the field DS_RESPONSE the value of which will be 0 or empty in case of error and 1 in case of success.

Execution of transfer reversal

Function: transfer_reversal

This method allows you to run a transfer reversal based on a previous transfer

The variables required for making a split transfer reversal request are (in this order):

Element Content Description
DS_MERCHANT_MERCHANTCODE [A-Za-z0-9]{1,8} Mandatory. Customer code
DS_MERCHANT_TERMINAL [0-9]{1,4} Mandatory. Terminal number
DS_MERCHANT_ORDER [A-Za-z0-9]{1,70} Mandatory. Reference of the original authorization.
DS_SUBMERCHANT_TERMINAL_SPLITID [a-z0-9]{64} Identifier for you to receive split payments
DS_SUBMERCHANT_SPLIT_AUTHCODE [a-zA-Z0-9]{1,40} Authorization code of the original split transfer
DS_SUBMERCHANT_AMOUNT [0-9]{1,8} Amount of the operation in integer format. 1.00 EURO = 100, 4.50 EUROS = 450...
DS_SUBMERCHANT_CURRENCY [EUR][USD][GBP][JPY] Currency of the transaction. See more information in CURRENCY
DS_MERCHANT_MERCHANTSIGNATURE [a-zA-Z0-9]{64} Mandatory. See SIGNATURE CALCULATION

The response of the service to the request is performed by the return of an array formatted in XML with the various elements described in the following table:

Element Content Description
DS_SUBMERCHANT_AMOUNT [0-9]{1,8} Amount of the operation in integer format. 1.00 EURO = 100, 4.50 EUROS = 450...
DS_MERCHANT_ORDER [A-Za-z0-9]{1,20} Reference of the operation.
DS_SUBMERCHANT_CURRENCY [EUR][USD][GBP][JPY] Currency of the transaction. See more information in MONEDAS
DS_MERCHANT_TRANSFER_AUTHCODE [a-zA-Z0-9]{1,40} Authorization code of the split transfer (required to execute a split transfer reversal)
DS_RESPONSE [0-1]{1} Result of operation. 0 or empty will be erroneous operation and 1 operation completed.
DS_ERROR_ID [0-9]{1,5} In the case of error, the error code generated will be here. If there is no error it will be 0 or empty. The error codes are specified in the document ERROR CODES.

SIGNATURE CALCULATION

The signature that the business will send to the gateway will be calculated in the following way (in pseudo code):

Function: (split_transfer)

SHA256(DS_MERCHANT_MERCHANTCODE + DS_MERCHANT_TERMINAL + DS_MERCHANT_ORDER + DS_MERCHANT_AUTHCODE + DS_SUBMERCHANT_TERMINAL_SPLITID + DS_SUBMERCHANT_AMOUNT + DS_SUBMERCHANT_CURRENCY + PASSWORD)

 

Function: (split_transfer_reversal)

SHA256(DS_MERCHANT_MERCHANTCODE + DS_MERCHANT_TERMINAL + DS_MERCHANT_ORDER + DS_MERCHANT_AUTHCODE + DS_SUBMERCHANT_TERMINAL_SPLITID + DS_SUBMERCHANT_SPLIT_AUTHCODE + DS_SUBMERCHANT_AMOUNT + DS_SUBMERCHANT_CURRENCY + PASSWORD)

 

Function: (transfer)

SHA256(DS_MERCHANT_MERCHANTCODE + DS_MERCHANT_TERMINAL + DS_MERCHANT_ORDER + DS_SUBMERCHANT_TERMINAL_SPLITID + DS_SUBMERCHANT_AMOUNT + DS_SUBMERCHANT_CURRENCY + PASSWORD)

 

Function: (transfer_reversal)

SHA256(DS_MERCHANT_MERCHANTCODE + DS_MERCHANT_TERMINAL + DS_MERCHANT_ORDER + DS_SUBMERCHANT_TERMINAL_SPLITID + DS_SUBMERCHANT_SPLIT_AUTHCODE + DS_SUBMERCHANT_AMOUNT + DS_SUBMERCHANT_CURRENCY + PASSWORD)