Split Transfer Integration
Introduction
The Split Payments service is offered as an ideal model for the distribution of balances from a previous payment operation. This service is available in REST integration, therefore any call to the splitTransfer or splitTransferReversal service must originate with a previous executePurchase, dccPurchaseCreate or confirmPreauthorization 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 splitTransfer as desired may be sent to other destination accounts on PAYCOMET. This splitTransfer 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 splitTransfer to a destination account is the Split Id. parameter. This information may be taken from the PAYCOMET control panel on (Terminals -> Terminal name" -> Terminal details -> Integration credentials).
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 splitTransfer 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 splitTransfer 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.
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 product from PAYCOMET. These may be:
executePurchasedccPurchaseCreateconfirmPreauthorization
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 splitTransfer operation to make a deposit in a destination account or a splitTransferReversal if they wish to reverse a previously executed splitTransfer. 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:
splitTransfersplitTransferReversal
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 REST, 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 REST 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: splitTransfer
This method allows you to run a split transfer based on a previous authorization
The details on this functions are explained in REST full documentation, available in this link
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,5} | 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 |
Signature calculation: (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)
The description of the "Content" column refers to the regular expression that the information in the corresponding element must meet (except in the case of DS_ORIGINAL_IP, which refers to an IP Address of the type “192.168.1.254”). Therefore “[A-Z]” indicates any character from “A” to “Z” and the brackets indicate the number of characters. For example “1{2,4}” validates numbers “11”, “111” and “1111”.
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: splitTransferReversal
This method allows you to run a split transfer reversal based on a previous split transfer
The details on this functions are explained in REST full documentation, available in this link
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,5} | 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 |
Signature calculation: (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)
The description of the "Content" column refers to the regular expression that the information in the corresponding element must meet (except in the case of DS_ORIGINAL_IP, which refers to an IP Address of the type “192.168.1.254”). Therefore “[A-Z]” indicates any character from “A” to “Z” and the brackets indicate the number of characters. For example “1{2,4}” validates numbers “11”, “111” and “1111”.
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 details on this functions are explained in REST full documentation, available in this link
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,5} | 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 |
Signature calculation: (transfer)
SHA256(DS_MERCHANT_MERCHANTCODE + DS_MERCHANT_TERMINAL + DS_MERCHANT_ORDER + DS_SUBMERCHANT_TERMINAL_SPLITID + DS_SUBMERCHANT_AMOUNT + DS_SUBMERCHANT_CURRENCY + PASSWORD)
The description of the "Content" column refers to the regular expression that the information in the corresponding element must meet (except in the case of DS_ORIGINAL_IP, which refers to an IP Address of the type “192.168.1.254”). Therefore “[A-Z]” indicates any character from “A” to “Z” and the brackets indicate the number of characters. For example “1{2,4}” validates numbers “11”, “111” and “1111”.
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: transferReversal
This method allows you to run a transfer reversal based on a previous transfer
The details on this functions are explained in REST full documentation, available in this link
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,5} | 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 |
Signature calculation: (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)
The description of the "Content" column refers to the regular expression that the information in the corresponding element must meet (except in the case of DS_ORIGINAL_IP, which refers to an IP Address of the type “192.168.1.254”). Therefore “[A-Z]” indicates any character from “A” to “Z” and the brackets indicate the number of characters. For example “1{2,4}” validates numbers “11”, “111” and “1111”.
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. |