Setup the merchant profile
Each merchant can configure his/her profile by accessing the Gestpay Back Office environment at:
- https://ecomm.sella.it/backoffice for production shops
- https://sandbox.gestpay.net/backoffice for test shops
Gestpay supports two ways to authenticate incoming calls: via IP and via ApiKey.
Authenticating via IP means that you register your server’s IP address on Gestpay, and Gestpay will reject any call that comes from an unknown IP address.
This approach might be good and can suffice most of the times, but with the rise of cloud hostings it might be difficult to have always the same public IP. Your server traffic might come from a wide range of IPs.
If this is your case, Gestpay has introduced the ApiKey authentication: just generate an ApiKey token via Gestpay Backoffice and use it for every call.
The first step is to choose what kind of autentication you need:
The two authentication systems can be used together, or indipendently, but at least one must be chosen. Let’s see them in detail.
Authenticating via IP
GestPay identifies the merchant requesting the encryption service by comparing the calling server IP address to the IP addresses configured in the profile associated with the Shop Login used for the call. If the calling server is not recognised, the transaction process ends and a specific error is returned.
In the Configuration -> Security -> IP Address section of the Back Office environment, the merchant can enter the IP addresses of its servers. There is no limit in the number of insertable IPs.
Authenticating via ApiKey
If you cannot use your server’s public IP, you can authenticate via a Gestpay-generated API Key. It is a unique random string that you must keep secret.
You understand that if the apiKey is stolen, anyone can pretend to be you at Gestpay’s eyes. Keep the apiKey safe and never share with anyone.
The token must be attached to every call to Gestpay. For example, in case of a
<Encrypt> <shopLogin>GESPAY12345</shopLogin> <!-- Use the apiKey as a field of your call --> <apikey>YZejApM8AfnBzmvmMsMIp0y1V91aakQY....</apikey> <!-- all other fields, as usual --> <uicCode>242</uicCode> <amount>1245.6</amount> <shopTransactionId>34az85ord19</shopTransactionId> ... </Encrypt>
For more information on how to generate and manage the
apikey, please refer to the online help available on each page.
Configuration of response URLs and e-mail
GestPay communicates the transaction result with a server-to-server call to a page specifically prepared by the merchant and by directing the buyer’s browser to the pages configured by the merchant (different pages for positive or negative results).
In Configuration > Responses section in the Back Office environment, it is possible to specify the URLs used by the system to communicate the transaction result.
In this section it is also possible to specify the addresses that will be used for e-mail notifications.
Let’s add some details on the URLs.
- URL for positive response: when the payment is completed, and the payment has succeded, Gestpay redirects the user at this URL with two parameters:
acontaining the shop login, and
bwith an encrypted string containing the payment data. The merchant should set up a page that will decrypt the encrypted string and show the payment result to the user.
- URL for negative response: this setting has the exact behavior of the preceeding point, but it is used when the payment fails.
- URL Server to Server: Gestpay will call this URL to notify the payment result. This is done asynchronously and independently from the two former settings.
The parameters will be, again,
acontaining the shop login and
bcontaining the encrypted string. The merchant’s server has to decrypt the string in order to retrieve useful information about the transaction. The decrypted data can be saved and used by the merchant. In this way the merchant has an indipendent way of updating the transaction statuses, even if the user redirect fails.
If URL Server to Server is not defined, GestPay will send its notifications to the URL specified for the buyer redirection (URL for positive response or URL for negative response) based on the transaction result.
Gestpay uses the server-to-server communication mainly to confirm the status of the transaction to the merchant server, even if the redirect of the user does not succed. Gestpay will try to contact the merchant’s server twice a day for up to 48 hours, until the merchant’s server answers with a 200 status code. After 48 hours an email will be sent, to notify the merchant of the failure.
The status of the transactions can be
XX means that the transaction status is pending, and a subsequent Server-to-Server call will return the final response,
M.O.T.O. : what happens after a transaction
M.O.T.O. stands for Mail Order - Telephone Order. Long before internet, the only way to pay without exhibiting the credit card was by telephone, or by mail.
In Gestpay, M.O.T.O. means that a transaction is carried out without physically handling the credit card.
M.O.T.O. is intended as the way the system should behave when receiving transactions. There are two options:
- Unify authorization and transaction. When a buyer completes a payment, the money is automatically transferred to the merchant account.
- Separation of the authorization and the transaction process. In this case, when the buyer completes a payment, Gestpay only asks his credit card company to authorize the payment (e.g. verify that the money is available, and block it); subsequently the merchant must carry out the transaction.
If the transaction is not carried out in 25 days (configurable), Gestpay will automatically cancel the transaction and the money will be returned to the buyer. 25 days is the maximum number of days that a transaction can be authorized before being cancelled.
M.O.T.O. settings are valid for all credit card transactions, including MasterPass, ApplePay, Hype, or token transactions.
M.O.T.O. settings are valid for every Gestpay plan. Your settings will be used to determine the transaction next state, weather you’re using Gestpay payment page, or the iFrame solution, or server-to-server calls.
Configuration of Fields & Parameters
Mechants may want to display or not some fields in the payment page, or in the email response, depending on their needs; think of the buyer’s email or the buyers name. In Configuration > Fields & Parameters you can decide which parameters to show, and when.
Sending Custom Parameters to Gestpay
Encrypt call you can also pass user-defined parameters. This is completely optional and can be useful for attaching some additional data (a
sessionId, a variable, etc.) that you want to receive back when the payment is completed (or failed).
From the page Payment Page -> Fields & Parametrs, create the custom parameter by clicking on Add parameter in the Merchant Back-Office:
Then fillout the box with your parameter’s name:
A description of the fields:
- Field Name: the name of the parameter that will show up in the Mechant Back-Office, under Payment Page -> Fields & Parametrs.
- Parameter: the parameter’s name that will be used via code in
WsCryptEncryptand all other relevant services.
- Response: the name the parameter should have in response.
- Visible: If the parameter should be shown to the buyer on the payment page, click this button. You can choose a name for the parameter in all Gestpay supported languages.
- Email Response: If the parameter should be sent to the buyer via mail, here you can specify the name of the parameter in all Gestpay supported languages.
Once you have set up a new parameter (in the examples the parameter is called
MYPARAM) you can send it via the webservice method
You can code your custom parameters inside the field
customInfo, paying attention to the syntax:
customInfocan contain at max 1000 characters
- each individual parameter can be max 300 characters
- you cannot use these special characters in your parameters:
& (space) § ( ) * < > , ; : *P1* / [ ] ? = -- /* % // ~
- The parameters must be encoded in this form:
<customInfo>datum1=value1*P1*datum2=value2*P1* ... *P1*datumN=valueN</customInfo>
Formally, it is a string containing couples of
key=value separated by the special string
Here is an example of
Encrypt request has been received, and the payment processed, the
Decrypt result will contain the same parameters back in another