NAV Navbar
Gestpay diventa Axerve Ecommerce Solutions
Axerve api logo

Introduction

Axerve Ecommerce Solutions API documentation aims to be a comprehensive and living catalog of Axerve services.

Our API is SOAP-based, so you must encode your requests in XML to communicate with Axerve Ecommerce Solutions.

For every service, we will present both the test and the production endpoints.

Our services are:

WSCryptDecrypt used to start (and end) the payment process.
js_GestPay.js Mainly used to build a customized payment page.
WSs2s Allows to control via a programmable interface many aspects of your transactions.

Authorizing calls against Axerve Ecommerce Solutions

<Encrypt>
  <shopLogin>GESPAY12345</shopLogin>

   <!-- Use the apikey as a field of your call -->
   <apikey>YZejApM8AfnBzmvmMsMIp0y1V91aakQY....</apikey>

   ...
</Encrypt>

Axerve Ecommerce Solutions supports two ways of authenticating your calls; via IP Address or via ApiKey. You can use at least one, or both.

If you use the IP Address authentication mechanism, you only have to specify this setting in the Merchant Back Office.

If you use the ApiKey, you must add for every call the field apiKey. You can see an example on the side. Keep the ApiKey secret.

For more information, checkout the docs for Authentication.

How read documentation

The notation {...} means that are required the value of certain type. For example, for every REST call you must provide a header with your merchant apikey, so this notation

Header Value
Authorization apikey {merchant Api Key}

means the header should look like

Authorization: apikey d3h8273gd87g8h34d78438dv4783d3874f

SOAP APIs

WSCryptDecrypt API

Axerve Ecommerce Solutions WsCryptDecrypt web service is exposed at following URLs:

environment URL
test https://sandbox.gestpay.net/gestpay/GestPayWS/WsCryptDecrypt.asmx?wsdl
production https://ecommS2S.sella.it/gestpay/GestPayWS/WsCryptDecrypt.asmx?wsdl

WSCryptDecrypt web service is available on production and test servers and does not require any installation on the merchant’s server.

The merchant must implement – in the page(s) of the virtual store configured to handle payments – a call to the webservice which handles requests to use the Axerve Ecommerce Solutions encryption service.

To request the encryption service you can call the Encrypt method.

If the encryption operation is concluded correctly (TransactionResult tag value with OK), the encrypted data string returned by Axerve Ecommerce Solutions will be available by reading the value of the CryptDecryptString tag.

If not, the values of the ErrorCode and ErrorDescription tag will make it possible to identify the reasons that prevented the encryption operation. To request the decryption service it is necessary to call the Decrypt method, passing the shopLogin and CryptedString tags with the values communicated by Axerve Ecommerce Solutions.

The information containing the transaction result will be available by reading the information in the XML response file corresponding to the result of the transaction.

Encrypt

A valid Encrypt can be called with just these fields - very easy:

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>985.21</amount>
  <shopTransactionId>34az85ord19</shopTransactionId>
</Encrypt>

Characters and strings that must not be used within the parameters encoded by Axerve Ecommerce Solutions and in customised information are:

&  (space)  §     (     )     * 
<     >     ,     ;     :    *P1* 
/     [     ]     ?     =     -- 
/*    %     //    ~     ° 

Encrypt is the main entrypoint for Axerve Ecommerce Solutions. You must call Encrypt either if you want to use the standard payment page, or the custom iframe solution.

These are the mandatory fields.

Name max length description
shopLogin 30 shopLogin (Mandatory)
uicCode 3 Code identifying currency in which transaction amount is denominated - see Currency Codes table - (Mandatory)
amount 9 Transaction amount. Do not insert thousands separator. Decimals, max. 2 numbers, are optional and separator is the point (Mandatory)
shopTransactionId 50 Identifier attributed to merchant’s transaction (Mandatory)

Here is an example where we use customInfo and other non-mandatory fields.

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <apikey>YZejApM8AfnBzmvmMsMIp0y1V91aakQY....</apikey>
  <uicCode>242</uicCode>
  <amount>1245.6</amount>
  <shopTransactionId>34az85ord19</shopTransactionId>
  <buyerName>Mario Bianchi</buyerName>
  <buyerEmail>mario.bianchi@isp.it</buyerEmail>
  <customInfo>BV_CODCLIENTE=12*P1*BV_SESSIONID=398</customInfo>
  <OrderDetails>
    ...
  </OrderDetails>
  <transDetails>
    ...
  </transDetails>
</Encrypt>

These are non-mandatory fields, but are direct children of the Encrypt root.

Name max length description
apikey If you have selected the apiKey authentication method, add the apikey field to the call. More details about the apiKey here.
buyerName 50 Buyer’s name and surname. Mandatory for Banca Sella customers (see Risk Based Authentication (RBA))
buyerEmail 50 Buyer’s e-mail address. Mandatory for Banca Sella customers (see Risk Based Authentication (RBA))
languageId 2 Code identifying language used in communication with buyer
customInfo1 1000 String containing specific information as configured in the merchant’s profile. See the next section for further explanations.
OrderDetails
a container ojbect of other data. It is used by Axerve Guaranteed Payment and by alternative payments.
transDetails object Contians informations for 3DS 2.0 authentication

1. Each field can be up to a maximum of 300 characters in length. See next section for further explanations.

Name Description Format/length
type Transaction type. Possible values:
  • 01F: Recurring first
  • 03F: Unscheduled MIT first
  • EC: Ecommerce
  • NPA: only authentication - not payment
If not evaluated, the Axerve Ecommerce Solutions rule is applied.
3
authenticationAmount 3DS authentication amount. If not filled, the authentication amount used will be the amount of the transaction (amount field previously described). The authenticationAmount should be equal or higher than amount, otherwise it will be ignored and the authentication will be made using the amount value. If the authenticationAmount field is used and it is higher than the transaction amount, it is recommended to notify the buyer that the authentication amount will differ from the authorization amount. max 9 (see the amount field)
threeDsContainer Container of additional data defined in 3DS2 protocol, that better define the transaction. The data here included will be used for assessing the risk level of the transaction with the purpose of ensuring security without affecting the buyer’s experience object
recurringTransaction Contains informations necessary in case of recurring payment object
expiry
Required for Recurring Payments. Date after which no further transaction shall be performed.
Format: YYYYMMDD
8
frequency
Required for Recurring Payments. It indicates the minimum number of days between two transactions of the same plan 4
previousTransDetails Contains the details of a previous authenticated transaction for the same cardholder on the same merchant. If present, it can help to increase the chances of a frictionless authentication object
authData
Prior Transaction Authentication Data string
authMethod
Prior Transaction Authentication Method. Possible values:
  • 01: Frictionless authentication occurred by ACS
  • 02: Cardholder challenge occurred by ACS
  • 03: AVS verified
  • 04: Other issuer methods
2
authTimestamp
Prior Transaction Authentication Timestamp.
Format: YYYYMMDDHHMM
12
acsID
Prior Transaction Authentication Reference (ACS Transaction ID) 36
bankTransactionID
Prior Transaction Bank ID (if it was managed by Axerve Ecommerce Solutions) 18
XID
Prior Transaction unique ID assigned by Directory Server 36

Sending custom data to Axerve Ecommerce Solutions: <customInfo>

The information included in customInfo will follow 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 *P1*.

<customInfo> is a special Axerve Ecommerce Solutions field; it is used to send custom merchant-defined parameters that Axerve Ecommerce Solutions will not touch. You can store everything, as long as the data respects the syntax described on the right.

The maximum length of the field is 1000 characters, and each individual parameter can be max 300 characters.

To start sending custom parameters, you must configure Axerve Ecommerce Solutions to receive them. This can be done in the backoffice, in Payment Page -> Fields & Parameters -> Add Parameter. Here you can configure some aspects of this parameter, for example if has to be returned by the Decrypt webservice. Don’t forget to populate the languages section.

With this customization, you can send all the parameters you want, as long they fit the 1000 characters length. To read more about custom parameters, refer to the documentation.

Card On File

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>985</amount>
  <shopTransactionId>34az85ord19</shopTransactionId> 
  <paymentTypes>
    <paymentType>CREDITCARD</paymentType> 
  </paymentTypes>
  <cof>Y</cof>
<Encrypt>

By filling this field with value “Y” you are stating that the card number used in this transaction has been saved on your system following the full PCI compliance. Saving card data may be useful for recurring payments or one-click payments since your customer is not required to enter card data.
If you are not PCI compliant, you can rely on the Axerve tokenization system. If you already use the Axerve tokenization system (see the RequestToken paragraph below) you should not fill this field out.

Name max length description
cof 1 Card On File flag, Y for “Card On File” transaction, null or other values for no “Card On File” transaction.

RequestToken

RequestToken example we are requesting a token to store the payment data.

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>985</amount>
  <shopTransactionId>34az85ord19</shopTransactionId>
  <requestToken>MASKEDPAN</requestToken>
</Encrypt>

You can request a token that will represent the credit card for your website. You can use it later to handle recurring payments, or to avoid your customer to insert again his credit card data. This behaviour is compliant with PCI. Read more here.

Name max length description
requestToken 2 25 MASKEDPAN for a Standard Token any other value for Custom Token. Using :FORCED: before the token, it’s possible to have the token even if the transaction is not authorized.

2. Required only when a Token is needed within the transaction response.

PaymentTypes

If you want to enable only Credit Card for this payment, you can send the request like this:

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>985</amount>
  <shopTransactionId>34az85ord19</shopTransactionId> 
  <paymentTypes>
    <paymentType>CREDITCARD</paymentType> 
  </paymentTypes>
<Encrypt>

If you only specify one payment type, Axerve Ecommerce Solutions won’t show the payment page but will redirect directly to the third party payment page:

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>985</amount>
  <shopTransactionId>34az85ord19</shopTransactionId> 
  <paymentTypes>
    <paymentType>CREDITCARD</paymentType>
  </paymentTypes>
<Encrypt>

Axerve Ecommerce Solutions provides a way for merchants to dinamically define which payment methods must be displayed for each transaction.

In order to do that, merchants must properly set the tag paymentType that can be repeated as many times as needed, inside the tag paymentTypes (with a final “s”).

Name max length description
paymentTypes container of one or more paymentType
paymentType 25 Set of tags to set the visibility of payment systems on payment page (see Payment Type Codes table)

Encrypt result

A succesful Encrypt call would be like this:

<EncryptResult>
  <GestPayCryptDecrypt>
    <TransactionType>ENCRYPT</TransactionType>
    <TransactionResult>OK</TransactionResult>
    <CryptDecryptString>897543..</CryptDecryptString>
    <ErrorCode>0</ErrorCode>
    <ErrorDescription/>
  </GestPayCryptDecrypt>
</EncryptResult>

Encrypt web service returns back the following information in xml:

Name max length description
TransactionType 7 Decode the transaction type request (DECRYPT, ENCRYPT)
TransactionResult 2 Transaction result (OK/ KO)
CryptDecryptString ….. Encrypted string get by parameter set in the xml request
ErrorCode  9 Error code
ErrorDescription 255 Error description

Decrypt

A Decrypt request:

 <Decrypt>
  <shopLogin>9000001</shopLogin>
  <CryptedString>HT987YU....</CryptedString>
  ...
 </Decrypt>

Axerve Ecommerce Solutions communicates the payment transaction result to the merchant through an encrypted string (parameter b of the call to the url preconfigured by the merchant) with a set of transaction’s informations.

To Decrypt the data it is necessary to use Decrypt method passing the following parameters, the tags’ names are case sensitive:

Name max length description
shopLogin 30 Shop Login
CryptedString …… Encrypted string get by parameter b of the call to the url preconfigured by the merchant
apikey If you have selected the apiKey authentication method, add the apikey field to the call. More details about the apiKey here.

Decrypt result

Axerve Ecommerce Solutions authenticates the calling server and checks the encrypted data string. If the checks are passed, it returns an unencrypted data string containing the transaction result:

 <DecryptResult>
  <GestPayCryptDecrypt xmlns="">
    <TransactionType>DECRYPT</TransactionType>
    <TransactionResult>OK</TransactionResult>
    <ShopTransactionID>34az85ord19</ShopTransactionID>
    <BankTransactionID>656</BankTransactionID>
    <AuthorizationCode>983RT4</AuthorizationCode>
    <Currency>242</Currency>
    <Amount>985.40</Amount>
    <ErrorCode>0</ErrorCode>
    <ErrorDescription>Transazione correttamente effettuata</ErrorDescription>
    <RiskResponseCode>created</RiskResponseCode>
    <RiskResponseDescription/>
  </GestPayCryptDecrypt>
</DecryptResult>

Decrypt webservice returns back the following information in the xml.

The minimum information returned back as transaction result is marked in bold.

Name max length description
TransactionType 7 Decode the transaction type request (DECRYPT, ENCRYPT)
TransactionResult 2 Transaction result (OK/KO)
ShopTransactionID 50 Identifier attributed to merchant’s transaction
BankTransactionID 9 Identifier attributed to the transaction by Axerve Ecommerce Solutions
AuthorizationCode 6 Transaction authorisation code
Currency 3 Code identifying currency in which transaction amount is denominated (see Currency Codes table)
Amount 9 Transaction amount. Decimals (max. 2 numbers) are optional and separator is the point (see examples)
Country 30 Nationality of the issuing card institute
CustomInfo 1000  String that has the specific information as configured in themerchant’s profile. Each field can be up to a maximum of 300 characters in length.
Buyer.BuyerName 50 Buyer’s name and surname
Buyer.BuyerEmail 50 Buyer’s e-mail address
TDLevel 255 Level of authentication for VBV Visa / Mastercard Securecode transactions. The string may have the value FULL or HALF
ErrorCode 9 Error code
ErrorDescription 255 Error description (localized in your language)
AlertCode 9 Alert code. See Better Risk Management for an accurate description.
AlertDescription 255 Alert description in chosen language. See Better Risk Management for an accurate description.
CVVPresent 1 Credit Card security code flag
MaskedPAN 25 Masked Pan string
PaymentMethod 100 Indicates the used Payment Method
TOKEN  25 String containing the token value
ProductType 100  String containing Card Type
TokenExpiryMonth  2 String containing the token expiry month
TokenExpiryYear 2 String containing the token expiry year
TransactionKey  18 Transaction identifier for 3D transactions. Not used in transactions managed with the Payment Page. It is useful only in Server-Server transactions
VbV 2 Verified By Visa Flag
VbVRisp Encrypted string containing information for 3D- Secure transactions. Not used in transactions managed with the Payment Page. It is useful only in Server-Server transactions
VbVBuyer 2 Information about the enrolment of the buyer’s card to 3D-Secure protocol: OK means that the card is enrolled, KO means that the card is not enrolled
VbVFlag 2 Information about the 3D-Secure status. Not used in transactions managed with the Payment Page. It is useful only in Server-Server transactions.
RiskResponseCode 10 Risk Fraud Score of the transaction, given by Axerve Guaranteed Payment. Possible values are:
  • created: transaction has been received by the Axerve Guaranteed Payment
  • submitted: transaction is under review
  • approved: transaction approved by Axerve Guaranteed Payment
  • declined: transaction not approved by Axerve Guaranteed Payment
  • captured: For Select&Submit plan, captured is returned for transactions that are not marked for review.
  • any other value is an error returned by Axerve Guaranteed Payment.
RiskResponseDescription 255 Risk Description of the RiskResponseCode
ThreeDS sandbox Object Object with information about 3ds authentication (described below)

Other information is defined as optional and will be returned according to the merchant’s profile settings made in the Axerve Back Office environment.

A transaction result can be interpreted by verifying the TransactionResult field value. The possible values are:

Transaction Result Description
OK  Positive transaction result
KO  Negative transaction result
XX  Suspended transaction result. This is not a final result: Axerve Ecommerce Solutions will send XX when the outcome is asynchronous. Right now these systems are MyBank, Sofort, IDeal, Bank Transfer. In the future, this code might be returned with other payment systems (bitcoins, for example).
A new communication will be provided to the merchant when the transaction will assume the final OK/KO status.
If you receive a XX code, don’t send your goods but wait to receive the actual payment. The customer with XX transaction is redirect to URL for positive response.

The ThreeDS sandbox object contains two objects:

Name max length description
authenticationLevel 2 Transaction is successfully athenticated by 3DS:
  • 1H: 3DS 1.0 half
  • 1F: 3DS 1.0 full
  • 2F: 3DS 2.0 frictionless
  • 2C: 3DS 2.0 challenge
  • 2E: 3DS 2.0 exemption
  • OL: One Leg - Authentication not required
  • NA: No Authentication
authenticationStatus 1 Status of authentication
authStatusReason 2 Provides information on why the Transaction Status field has the specified value
XID 36 Transaction unique id assigned by Directory Server
AV 28 Cardholder Authentication Verification Value, proof of authentication done
ECI 2 Electronic Commerce Indicator
AVAlgorithm 2 Cardholder Authentication Verification Algoritm, valorized only with 3DS 1.0
threeDsVersion 8 EMVco protocol version identifier
Name max length description
authData string Transaction Authentication Data
authMethod 2 Transaction Authentication Method Possible values:
  • 01: Frictionless authentication occurred by ACS
  • 02: Cardholder challenge occurred by ACS
  • 03: AVS verified
  • 04: Other issuer methods
authTimestamp 12 Transaction Authentication Timestamp
acsID 36 ACS Transaction ID

WsS2S API

Server to Server communication between merchants and Axerve Ecommerce Solutions is managed by consuming WSs2s SOAP web service.

Consuming WSs2s methods allow merchants to send requests and retrieve responses in XML format.

callPagamS2S

This service performs an authorization request.

Merchants can use this method to perform the transaction, passing all the parameters useful to define all the transaction’s features.

 Request parameters

request example:

<callPagamS2S>
  <shopLogin>9000002</shopLogin>
  <uicCode>242</uicCode><!-- euro -->
  <amount>24.21</amount>
  <shopTransactionId>MYSHOP-0001</shopTransactionId>
  <!-- here we have choosen to pay with credit card data -->
  <cardNumber>1234567812345678</cardNumber>
  <expiryMonth>06</expiryMonth>
  <expiryYear>21</expiryYear>
  <!-- if we wanted to pay by token: 
  <tokenValue>ABCD12345678EFGD</tokenValue>
  -->
  <buyerName>John Fitzgerald Kennedy</buyerName>
  <buyerEmail>johnny.kennedy@usa.com</buyerEmail>
  <languageId>2</languageId><!-- english -->
  <cof>Y</cof>
  <cvv>987</cvv>
  <PARes />
  <transKey />
  <customInfo></customInfo>
  <requestToken>MASKEDPAN</requestToken>
  <itemType>physical</itemType>
  <recurrent>false</recurrent>
  <executionDate>20200828</executionDate>
  <shippingDetails>
    <shipToName>Jonny Kennedy</shipToName>
    <shipToStreet>83 Beals street</shipToStreet>
    <shipToCity>Brookline</shipToCity>
    <shipToState>MA</shipToState>
    <shipToCountryCode>US</shipToCountryCode>
    <shipToZip>02446</shipToZip>
    <shipToStreet2 />
  </shippingDetails>
  <OrderDetails>
  ... 
  </OrderDetails>
  <transDetails>
    ...
  </transDetails>
</callPagamS2S>

First we describe the mandatory attributes.

Name Description Data Type max length
shopLogin  shopLogin value string 30
uicCode  currency code number 3
amount the amount of the transaction numeric 9
shopTransactionId shop transaction ID value string 50

Depending on the payment method, you can choose to send Credit Card data:

Name Description Data Type max length
cardNumber card account number string 50
expiryMonth card expiration month string 2
expiryYear card expiration year string 2

Or a token:

Name Description Data Type max length
tokenValue String containing the token value returned by Axerve Ecommerce Solutions.
In case of PayPalBillingAgreement this token value is the token returned by PayPal during the Billing Agreements.
string 25

The following features may be optionally assigned:

Name Description Data Type max length
apikey If you have selected the apiKey authentication method, add the apikey field to the call. More details about the apiKey here.
buyerEmail buyer’s e-mail address. Using :NOSEND: before the email address, it’ s possible to pass the email information but avoid to send an email to the buyer. this field is Mandatory for Banca Sella customers (see Risk Based Authentication (RBA)). string 50
buyerName buyer’s name. Mandatory for Banca Sella customers (see Risk Based Authentication (RBA)). string 50
customInfo A string containing optional customised parameters. See customInfo section for more details. string 1000
cvv security code of the card. Refer to this page to enable and use it. string 4
cof Card On File flag, Y for “Card On File” transaction, null or other values for no “Card On File” transaction. See the Card On File section for more information. string 1
languageId language to use for e-mails to the buyer number 2
PARes   encrypted string returned by Issuer (for 3D-Secure transactions only. See 3D-secure transactions for more details.)  string 4096
transKey transaction ID value for 3D-Secure transactions. See 3D-secure transactions for more details. number 18
requestToken MASKEDPAN for a Standard Token any other value for Custom Token string 25
clientIP For PayPal Billing Agreements it is required only in “one click” mode transaction.
For AMEX transaction not in Euro, in this field the merchant could provide the client IP address to activate the Enhanced Authorization AAV.
Mandatory if you use Axerve Guaranteed Payment with S2S.
string 45
itemType Item Category: digital/physical (If physical the ShippingDetails have to be filled) string 250
recurrent true if it’s a recurrent payment, false if not. boolean 5
executionDate Date of charge on the buyer’s banking account. (SEPA) date 7
shippingDetails contains the shipping address. Used for paypal seller protection.
OrderDetails contains every other info needed to handle the payment. It is used by Axerve Guaranteed Payment.
transDetails Contians informations for 3DS 2.0 authentication object -


executionDate allows the merchant to define the date of charge on the buyer’s banking account. To follow SEPA rules, if the date it’s not on a working day, the charge will be postponed to the next working day. It must be in yyyymmdd format


shipToName shipping name string 32
shipToStreet shipping address string 100
shipToState  shipping state (see Paypal State Codes table) string 40
shipToCountryCode shipping country code (see Paypal Country Codes table) string 2
shipToZip the shipping Zip string 20
shipToStreet2 an additional field for the shipping address string 200
Name Description Format/length
type Transaction type. Possible values:
  • 01F: Recurring first
  • 01N: Recurring next
  • 03F: Unscheduled MIT first
  • 03N: Unscheduled MIT next
  • 08: Mail Order
  • 09: Telephone Order
  • EC: Ecommerce
  • NPA: only authentication - not payment
If not evaluated, the Axerve Ecommerce Solutions rule is applied.
3
authenticationAmount 3DS authentication amount. If not filled, the authentication amount used will be the amount of the transaction (amount field previously described). The authenticationAmount should be equal or higher than amount, otherwise it will be ignored and the authentication will be made using the amount value. If the authenticationAmount field is used and it is higher than the transaction amount, it is recommended to notify the buyer that the authentication amount will differ from the authorization amount. max 9 (see the amount field)
threeDSAuthResult Result of the 3DS authentication done with another provider (Axerve will manage the authorization request, considering the 3DS phase already completed) object
authenticationLevel
Transaction is successfully authenticated by 3DS:
  • 1H: 3DS 1.0 half
  • 1F: 3DS 1.0 full
  • 2F: 3DS 2.0 frictionless
  • 2C: 3DS 2.0 challenge
  • 2E: 3DS 2.0 exemption
  • OL: One Leg - Authentication not required
2
authenticationStatus
Status of the authentication 1
XID
Transaction unique id assigned by Directory Server 36
AV
Cardholder Authentication Verification Value, proof of authentication done 28
ECI
Electronic Commerce Indicator 2
AVAlgorithm
Cardholder Authentication Verification Algoritm, valorized only with 3DS 1.0 2
threeDsVersion
EMVco protocol version identifier 8
threeDsContainer Container of additional data defined in 3DS2 protocol, that better define the transaction. The data here included will be used for assessing the risk level of the transaction with the purpose of ensuring security without affecting the buyer’s experience object
recurringTransaction Contains informations necessary in case of recurring payment object
expiry
Required for Recurring Payments. Date after which no further transaction shall be performed.
Format: YYYYMMDD
8
frequency
Required for Recurring Payments. It indicates the minimum number of days between two transactions of the same plan 4
previousTransDetails Contains the details of a previous authenticated transaction for the same cardholder on the same merchant. If present, it can help to increase the chances of a frictionless authentication object
authData
Prior Transaction Authentication Data string
authMethod
Prior Transaction Authentication Method. Possible values:
  • 01: Frictionless authentication occurred by ACS
  • 02: Cardholder challenge occurred by ACS
  • 03: AVS verified
  • 04: Other issuer methods
2
authTimestamp
Prior Transaction Authentication Timestamp.
Format: YYYYMMDDHHMM
12
acsID
Prior Transaction Authentication Reference (ACS Transaction ID) 36
bankTransactionID
Prior Transaction Bank ID (if it was managed by Axerve Ecommerce Solutions) 18
XID
Prior Transaction unique ID assigned by Directory Server 36

Response fields

response example:

<GestPayS2S xmlns="">
  <TransactionType>PAGAM</TransactionType>
  <TransactionResult>OK</TransactionResult>
  <ShopTransactionID>MYSHOP-0001</ShopTransactionID>
  <BankTransactionID>65</BankTransactionID>
  <AuthorizationCode>365530</AuthorizationCode>
  <Currency>242</Currency>
  <Amount>24.21</Amount>
  <Country>US</Country>
  <Buyer>
    <BuyerName>John Fitzgerald Kennedy</BuyerName>
    <BuyerEmail>johnny.kennedy@usa.com</BuyerEmail>
  </Buyer>
  <CustomInfo/>
  <TDLevel/>
  <ErrorCode>0</ErrorCode>
  <ErrorDescription>Transazione correttamente effettuata</ErrorDescription>
  <AlertCode/>
  <AlertDescription/>
  <TransactionKey>579428899</TransactionKey>
  <VbV>
    <VbVFlag>KO</VbVFlag>
    <VbVBuyer/>
    <VbVRisp/>
  </VbV>
  <MaskedPAN>40L76FDIEFMH1112</MaskedPAN>
  <PaymentMethod>VISA VBV</PaymentMethod>
  <ProductType></ProductType>
  <CVVPresent>Y</CVVPresent>
  <TOKEN>40L76FDIEFMH1112</TOKEN>
  <TokenExpiryMonth></TokenExpiryMonth>
  <TokenExpiryYear></TokenExpiryYear>
  <tokenDetails>
    <tokenValue>40L76FDIEFMH1112</tokenValue>
    <tokenExpiryMonth >02</tokenExpiryMonth >
    <tokenExpiryYear >23</tokenExpiryYear >
    <tokenProvider />
    <cardDetails>
      <cardExpiryMonth />
      <cardExpiryYear />
      <cardHolderName />
      <cardSuffix />
    </cardDetails>
    <cardAssets>
      <cardArt>
        <height />
        <mediaContents />
        <type />
        <width />
      </cardArt>
      <brandLogo>
        <height />
        <mediaContents />
        <type />
        <width />
      </brandLogo>
    </cardAssets>
  </tokenDetails>

  <PayPalFee></PayPalFee>
  <RiskResponseCode>approved</RiskResponseCode>
  <RiskResponseDescription>the transaction is approved</RiskResponseDescription>

  <ThreeDS>
    <authenticationResult>
      <authenticationLevel></authenticationLevel>
      <authenticationStatus />
      <authStatusReason />
      <XID />
      <AV />
      <ECI></ECI>
      <AVAlgorithm />
      <threeDsVersion></threeDsVersion>
    </authenticationResult>
    <transDetails>
      <authData />
      <authMethod />
      <authTimeStamp />
      <acsID />
    </transDetails>
  </ThreeDS>
</GestPayS2S>
Name Description
TransactionType PAGAM in response to CallPagamS2S
TransactionResult Returns transaction result with OK or KO
shopTransactionID shop transaction ID value
BankTransactionID code given by bank to transaction
AuthorizationCode authorisation code
Currency currency code
Country nationality of the card issuer
CustomInfo custom parameters, if passed to the request
BuyerType Returns address name and e-mail of thebuyer divided as follows:
  • BuyerEmail: Returns the e-mail of the buyer
  • BuyerName: Returns the name of the buyer
ErrorCode a code related to the transaction result
ErrorDescription the description connected to the ErrorCode value
AlertCode the violation code of the risk management criteria. See Better Risk Management for an accurate description.
AlertDescription the description connected to the AlertCode value. See Better Risk Management for an accurate description.
Amount the amount of the transaction
TransKey transaction ID value for 3D-Secure transactions
VBV Returns the values for 3D-Secure as follows:
  • VbVFlag: 3D-secure flag (OK or KO)
  • VbVBuyer:returns the flag Full Verified by Visa transaction
  • VbVRisp: Returns the encrypted string obtained by 3D-Secure directory
MaskedPAN this field returns a token (to not confuse with TOKEN) that should not be stored or used as a credit card token. With this parameter the merchant can assess some risk management analisys, for example he can check if the same MaskedPAN has already done some purchases or is involved in frauds.
PaymentMethod the credit card circuit / payment system used
ProductType can be Credit, Debit, or empty.
CVVPresent Y if the CVV is present, N if not.
TOKEN  contains a token that represents the credit card number. See Handling Subscriptions in the docs.
TokenExpiryMonth  the token exiration month
TokenExpiryYear  the token expiration year
PayPalFee the fee owed to paypal.
TDLevel Level of authentication for 3D-Secure transactions. FULL or HALF
RiskResponseCode Risk Fraud Score of the transaction, given by Axerve Guaranteed Payment. Possible values are:
  • created: transaction has been received by the Axerve Guaranteed Payment
  • submitted: transaction is under review
  • approved: transaction approved by Axerve Guaranteed Payment
  • declined: transaction not approved by Axerve Guaranteed Payment
  • captured: For Select&Submit plan, captured is returned for transactions that are not marked for review.
  • any other value is an error returned by Axerve Guaranteed Payment.
ThreeDS sandbox Object with information about 3ds authentication (described below)

The ThreeDS sandbox object contains three object:

Name max length description
authenticationLevel 2 Transaction is successfully athenticated by 3DS:
  • 1H: 3DS 1.0 half
  • 1F: 3DS 1.0 full
  • 2F: 3DS 2.0 frictionless
  • 2C: 3DS 2.0 challenge
  • 2E: 3DS 2.0 exemption
  • OL: One Leg - Authentication not required
  • NA: No Authentication
authenticationStatus 1 Status of authentication
authStatusReason 2 Provides information on why the Transaction Status field has the specified value
XID 36 Transaction unique id assigned by Directory Server
AV 28 Cardholder Authentication Verification Value, proof of authentication done
ECI 2 Electronic Commerce Indicator
AVAlgorithm 2 Cardholder Authentication Verification Algoritm, valorized only with 3DS 1.0
threeDsVersion 8 EMVco protocol version identifier
Name max length description
authData string Transaction Authentication Data
authMethod 2 Transaction Authentication Method Possible values:
  • 01: Frictionless authentication occurred by ACS
  • 02: Cardholder challenge occurred by ACS
  • 03: AVS verified
  • 04: Other issuer methods
authTimestamp 12 Transaction Authentication Timestamp
acsID 36 ACS Transaction ID
Name Description
threeDSServerTransID Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.
acsSignedContent Contains the JWS object (represented as a string) created by the ACS for the ARes message.
acsTransID Universally Unique transaction identifier assigned by the ACS to identify a single transaction.
acsURL Fully qualified URL of the ACS to be used for the challenge.
cardholderInfo Text provided by the ACS/Issuer to Cardholder during a Frictionless or Decoupled transaction. The Issuer can provide information to Cardholder. For example, “Additional authentication is needed for this transaction, please contact (Issuer Name) at xxx-xxx-xxxx.”
messageExtension Data necessary to support requirements not otherwise defined in the 3- D Secure message are carried in a Message Extension.
sdkTransID Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction

tokenDetails details:

Name Description
tokenValue String containing the token value returned by Axerve Ecommerce Solutions.
tokenExpiryMonth The token expiration month.
tokenExpiryYear The token expiration year.
tokenProvider The entity providing the token. It can be: AXERVE, VISA, MASTERCARD, PAYPAL, AMAZON, APPLE, SEPADD.
cardDetails.cardSuffix The last 4 digit of the card PAN.
cardDetails.cardExpiryMonth The card expiry month.
cardDetails.cardExpiryYear The card expiry Year.
cardDetails.cardHolderName The cardholder name.
cardAssets.cardArt.type The file format of the card art (card image)
cardAssets.cardArt.mediaContents The card image (Base64)
cardAssets.cardArt.height The card art (card image) height
cardAssets.cardArt.width The card art (card image) width
cardAssets.brandLogo.type The file format of the brand logo (e.g. Visa, Mastercard, etc..)
cardAssets.brandLogo.mediaContents The brand logo (e.g. Visa, Mastercard, etc..) image (Base64)
cardAssets.brandLogo.height The brand logo (e.g. Visa, Mastercard, etc..) height
cardAssets.brandLogo.width The brand logo (e.g. Visa, Mastercard, etc..) width

CallSettleS2S

This is the financial confirmation operation which may follow a positive authorisation.

It exists only for merchants with a M.O.T.O. configuration when a separation between the authorisation and the settlement phase is anticipated.

Merchants can use this method to settle the transaction. Since it’s possible to settle only a part of the amount, the amount value has to be passed.

Request details

Request example:

<callSettleS2S>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode><!-- Euro -->
  <amount>55.00</amount>
  <shopTransID>MYSHOP-00142</shopTransID>
  <bankTransID>159247522</bankTransID>
  <settlementID></settlementID>
  <FullFillment>
    <FullFillmentlst>
      <FullfillmentDetail>
        <Status>success</Status>
        <TrackingCompany>Shippers, Inc.</TrackingCompany>
        <TrackingNumbers>GD-52563-2233-4422</TrackingNumbers>
        <TrackingUrls>www.shippers.com/track?id=GD-52563-2233-4422</TrackingUrls>
        <Message>items in stock</Message>
        <Receipt>s.f. 351</Receipt>
        <ProductDetails>
          <ProductCode>223311</ProductCode>
          <SKU>ART-244742-1231</SKU>
          <Name>Unicorn</Name>
          <Description>a horse with a horn</Description>
          <Quantity>1</Quantity>
          <Price>3500</Price>
          <UnitPrice>3500</UnitPrice>
          <Type>horse</Type>
          <Vat>22</Vat>
          <Discount>0</Discount>
          <RequiresShipping>true</RequiresShipping>
          <Condition>new</Condition>
          <Seller>Flying Horses</Seller>
          <Category>Horse</Category>
          <SubCategory>Special Horse</SubCategory>
          <Brand>Custom</Brand>
          <DeliveryAt>19/05/2016</DeliveryAt>
        </ProductDetails>
      </FullfillmentDetail>
    </FullFillmentlst>
  </FullFillment>
</callSettleS2S>

Parameters in bold are mandatory.

parameter name description type length
shopLogin the merchant’s code string 30
amount amount   number 9
uicCode currency code number 3
bankTransID BankTransactionID assigned to the transaction number 18
shopTransID shop transaction ID value string 50
settlementID Optional identifier of the settlement string 20
FullFillment An object describing the final fulfillment status of an order.
apikey If you have selected the apiKey authentication method, add the apikey field to the call. More details about the apiKey here.

FullFillment tag must be filled if you are using Axerve Guaranteed Payment, an anti fraud evaluating system. If you are not using it, you can skip this.

When you settle a payment, Axerve Guaranteed Payment wants to be notified that an existing order has been fulfilled, both the success and error case.

FillFillment contains a FullFillmentlst that contains one or more FullfillmentDetail, whose fields are:

parameter name description
Status
  • success: the fulfillment was successful.
  • cancelled: the fulfillment was cancelled.
  • error: there was an error with the fulfillment request.
  • failure: the fulfillment request failed.
TrackingCompany the name of the shipping company
TrackingNumbers A list of shipping numbers, provided by the shipping company.
TrackingUrls The URLs to track the fulfillment.
Message Additional textual description regarding the fulfillment status.
Receipt  Information about the Receipt
ProductDetails container object that contains info about the fulfilled item.

Here is a description of the children of ProductDetails:

parameter name description
ProductCode Article’s product Code
SKU Article’s Stock Keeping Unit
Name Article’s name
Description Article’s description
Quantity The number of products
Price Article’s price
UnitPrice Article’s Unit price
Type The type of article: digital , downloadable, physical,composite, event, travel
Vat Value-Added Tax (the value of the tax)
Discount
RequiresShipping boolean, States whether or not the fulfillment requires shipping. This field is important for merchants dealing with digital goods.
Condition Description of the physical condition of the item, mostly relevant for used items.
Seller Details about the seller of the item, relevant for marketplace orders.
Category The category of the item. For event tickets: the category of the event.
SubCategory The sub-category of the item. For event tickets: the sub-category of the event.
Brand The brand name of the item.
DeliveryAt The planned delivery date of the product or item.

 Response details

Response example:

<callSettleS2SResponse xmlns="https://ecomms2s.sella.it/">
  <callSettleS2SResult>
    <GestPayS2S>
      <TransactionType>Settle</TransactionType>
      <TransactionResult>OK</TransactionResult>
      <ShopTransactionID>MYSHOP-00142</ShopTransactionID>
      <BankTransactionID>159247522</BankTransactionID>
      <ErrorCode>0</ErrorCode>
      <ErrorDescription>Transazione correttamente effettuata</ErrorDescription>
    </GestPayS2S>
  </callSettleS2SResult>
</callSettleS2SResponse>
parameter name description
TransactionType  for CallSettleS2S, the value will be Settle
TransactionResult OK or KO
BankTransactionID Bank transaction ID assigned to the transaction
ShopTransactionID Shop transaction ID value assigned to the transaction
ErrorCode transaction error code
ErrorDescription transaction error description

CallDeleteS2S

This operation deletes an authorized transaction.

It exists only for merchants with a M.O.T.O. configuration when a separation between the authorisation and the settlement phase is anticipated.

Request details

Request example:

<callDeleteS2S>
  <shopLogin>9000001</shopLogin>
  <shopTransactionId>MYSHOP-4838</shopTransactionId>
  <bankTransactionId>334488931</bankTransactionId>
  <CancelReason>potential fraud</CancelReason>
</callDeleteS2S>

Mandatory parameters are in bold.

parameter name description type length
shopLogin the merchant’s code string 30
bankTransactionId ID of the transaction assigned by Axerve Ecommerce Solutions number 18
shopTransactionId shop transaction ID value string 50
CancelReason free text of cancel reason. For Axerve Guaranteed Payment users, this field is mandatory. string 50
apikey If you have selected the apiKey authentication method, add the apikey field to the call. More details about the apiKey here.

 Response details

Response example:

<callDeleteS2SResponse xmlns="https://ecomms2s.sella.it/">
  <callDeleteS2SResult>
    <GestPayS2S>
      <TransactionType>Delete</TransactionType>
      <TransactionResult>OK</TransactionResult>
      <ShopTransactionID>MYSHOP-00142</ShopTransactionID>
      <BankTransactionID>159247522</BankTransactionID>
      <ErrorCode>0</ErrorCode>
      <ErrorDescription>Transazione ritirata</ErrorDescription>
    </GestPayS2S>
  </callSettleS2SResult>
</callSettleS2SResponse>
parameter name description
TransactionType  for CallDeleteS2S, the value will be Delete
TransactionResult OK or KO
BankTransactionID Bank transaction ID assigned to the transaction
ShopTransactionID Shop transaction ID value assigned to the transaction
ErrorCode transaction error code
ErrorDescription transaction error description

CallRefundS2S

Merchants can use this method to perform a partial or complete transaction amount refund.

Request details

Request example:

<callRefundS2S>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode><!-- Euro -->
  <amount>55.00</amount>
  <shopTransactionId>MYSHOP-00142</shopTransactionId>
  <bankTransactionId>159247522</bankTransactionId>
  <settlementID></settlementID>
  <RefundReason>item our of stock</RefundReason>
  <chargeBackFraud>N</chargeBackFraud>
  <OrderDetail>
    <ProductDetails>
      ...
    </ProductDetails>
  </OrderDetail>
</callRefundS2S>

Mandatory parameters are in bold.

parameter name description type length
shopLogin the merchant’s code string 30
bankTransactionId ID of the transaction assigned by Axerve Ecommerce Solutions number 18
shopTransactionId shop transaction ID value string 50
amount the amount to refund number 9
uicCode currency code numeric 3
settlementID Optional identifier of the settlement string 20
RefundReason a free-text reason for the refund. Used with fraud protection. string 50
chargeBackFraud Flag for risk:
  • Y - chargeback for fraud
  • N - chargeback not for a fraud
orderDetail.ProductDetails in case you are using Klarna, fill this fields with info about the products that are refunded. A description of this field is in OrderDetails.
apikey If you have selected the apiKey authentication method, add the apikey field to the call. More details about the apiKey here.

 Response details

Response example:

<callRefundS2SResponse xmlns="https://ecomms2s.sella.it/">
  <callRefundS2SResult>
    <GestPayS2S>
      <TransactionType>Refund</TransactionType>
      <TransactionResult>OK</TransactionResult>
      <ShopTransactionID>MYSHOP-00142</ShopTransactionID>
      <BankTransactionID>159247522</BankTransactionID>
      <ErrorCode>0</ErrorCode>
      <ErrorDescription/>
    </GestPayS2S>
  </callRefundS2SResult>
</callRefundS2SResponse>
parameter name description
TransactionType  for CallRefundS2S, the value will be Refund
TransactionResult OK or KO
BankTransactionID Bank transaction ID assigned to the transaction
ShopTransactionID Shop transaction ID value assigned to the transaction
ErrorCode transaction error code
ErrorDescription transaction error description

 CallReadTrxS2S

This method will return the transaction status.

This method can be called with a mandatory shopLogin, then it’s possible to pass shopTransactionId or bankTransactionId or both. If only shopLogin and shopTransactionId are passed, it’s mandatory that the last one is unique.

Request details

Example request:

<callReadTrxS2S>
  <shopLogin>9000001</shopLogin>
  <shopTransactionId>MYSHOP-4838</shopTransactionId>
  <bankTransactionId>334488931</bankTransactionId>
</callReadTrxS2S>

Parameters in bold are mandatory.

parameter name description type length
shopLogin the merchant’s code string 30
bankTransactionId ID of the transaction assigned by Axerve Ecommerce Solutions number 18
shopTransactionId shop transaction ID value string 50
apikey If you have selected the apiKey authentication method, add the apikey field to the call. More details about the apiKey here.

 Response details

Response example

<callReadTrxS2SResult>
  <GestPayS2S xmlns="">
    <TransactionType>QUERYTX</TransactionType>
    <TransactionResult>OK</TransactionResult>
    <TransactionState>CAN</TransactionState>
    <ShopTransactionID>MYSHOP-4838</ShopTransactionID>
    <BankTransactionID>334488931</BankTransactionID>
    <AuthorizationCode>971773</AuthorizationCode>
    <Currency>242</Currency>
    <Country>ITALIA</Country>
    <Company>MASTERCARD SECURECODE</Company>
    <TDLevel>FULL</TDLevel>
    <Events>
      <event>
        <eventtype>AUT</eventtype>
        <eventamount>0.10</eventamount>
        <eventdate>19/08/16 16:13:14</eventdate>
        <eventARN></eventARN>
        <eventID></eventID>
      </event>
      <event>
        <eventtype>CAN</eventtype>
        <eventamount>0.10</eventamount>
        <eventdate>20/08/16 00:13:57</eventdate>
        <eventARN></eventARN>
        <eventID></eventID>
      </event>
    </Events>
    <Buyer>
      <BuyerName/>
      <BuyerEmail/>
    </Buyer>
    <RISK>
      <RiskResponseCode>approved<RiskResponseCode>
      <RiskResponseDescription/>
    </RISK>
    <ErrorCode>0</ErrorCode>
    <ErrorDescription>Transaction correctly processed</ErrorDescription>
    <AlertCode/>
    <AlertDescription/>
  </GestPayS2S>
</callReadTrxS2SResult>

Response example for Amazon Pay

<callReadTrxS2SResult>
  <GestPayS2S xmlns="">
      <TransactionType>QUERYTX</TransactionType>
      <TransactionResult>OK</TransactionResult>
      <TransactionState>MOV</TransactionState>
      <ShopTransactionID>af22</ShopTransactionID>
      <BankTransactionID>117</BankTransactionID>
      <AuthorizationCode>008152</AuthorizationCode>
      <Currency>242</Currency>
      <Country/>
      <Company>AMAZONPAY</Company>
      <TDLevel/>
      <Events>
        <event>
            <eventtype>AUT</eventtype>
            <eventamount>10.00</eventamount>
            <eventdate>13/11/17 11:32:45</eventdate>
            <eventARN></eventARN>
            <eventID></eventID>
        </event>
        <event>
            <eventtype>MOV</eventtype>
            <eventamount>10.00</eventamount>
            <eventdate>13/11/17 11:32:45</eventdate>
            <eventARN></eventARN>
            <eventID></eventID>
        </event>
      </Events>
      <Buyer>
        <BuyerName/>
        <BuyerEmail/>
      </Buyer>
      <RISK>
        <RiskResponseCode/>
        <RiskResponseDescription/>
      </RISK>
      <ErrorCode>0</ErrorCode>
      <ErrorDescription>Transazione correttamente effettuata</ErrorDescription>
      <AlertCode/>
      <AlertDescription/>

      <!-- Here you'll see buyer' 
          shipping and billing address 
          for Amazon Pay -->
      <OrderReferenceDetails>
        <OrderReferenceStatus>
            <State>Draft</State>
        </OrderReferenceStatus>
        <OrderLanguage>it-IT</OrderLanguage>
        <Destination>
            <DestinationType>Physical</DestinationType>
            <PhysicalDestination>
              <StateOrRegion>BI</StateOrRegion>
              <Phone>33333333</Phone>
              <City>BIELLA</City>
              <CountryCode>IT</CountryCode>
              <PostalCode>13900</PostalCode>
              <Name>Marco Rossi</Name>
              <AddressLine1>via Gobe 15</AddressLine1>
            </PhysicalDestination>
        </Destination>
        <ExpirationTimestamp>2018-05-13T07:24:02.186Z</ExpirationTimestamp>
        <IdList/>
        <SellerOrderAttributes>
            <SellerOrderId>4354395804398dkfjlhsdfk</SellerOrderId>
        </SellerOrderAttributes>
        <OrderTotal>
            <CurrencyCode>EUR</CurrencyCode>
            <Amount>10.00</Amount>
        </OrderTotal>
        <Buyer>
            <Name>Ale</Name>
            <Email>marco.rossi@email.it</Email>
        </Buyer>
        <ReleaseEnvironment>Sandbox</ReleaseEnvironment>
        <AmazonOrderReferenceId>S02-0319513-4657042</AmazonOrderReferenceId>
        <CreationTimestamp>2017-11-14T07:24:02.186Z</CreationTimestamp>
        <BillingAddress>
            <PhysicalAddress>
              <City>Neunkirchen</City>
              <CountryCode>DE</CountryCode>
              <PostalCode>66538</PostalCode>
              <Name>Liam Barker</Name>
              <AddressLine1/>
              <AddressLine2>Meininger Strasse 58</AddressLine2>
            </PhysicalAddress>
            <AddressType>Physical</AddressType>
        </BillingAddress>
        <RequestPaymentAuthorization>false</RequestPaymentAuthorization>
      </OrderReferenceDetails>
  </GestPayS2S>
  </callReadTrxS2SResult>

parameter name description
TransactionType  for  CallReadTrxS2S, the value will be QUERYTX
TransactionResult OK or KO
BankTransactionID Bank transaction ID assigned to the transaction
ShopTransactionID Shop transaction ID value assigned to the transaction
ErrorCode transaction error code
ErrorDescription transaction error description
AuthorizationCode the authorisation code
Currency the currency code
Country the nationality of the card issuer
Company the card company: Visa, Mastercard, etc.
TransactionState the status of the transaction: one of AUT, MOV, CAN, STO. Follow the link for a detailed explanation of transaction statuses.
AlertCode the violation code of the risk management criteria. See Better Risk Management for an accurate description.
AlertDescription the description connected to the AlertCode value. See Better Risk Management for an accurate description.
Buyer.BuyerName Returns the name of the buyer
Buyer.BuyerEmail Returns the email of the buyer
Events contains event elements. see the next table for more.
RiskResponseCode Risk Fraud Score of the transaction, given by Axerve Guaranteed Payment. Possible values are:
  • created: transaction has been received by the Axerve Guaranteed Payment
  • submitted: transaction is under review
  • approved: transaction approved by Axerve Guaranteed Payment
  • declined: transaction not approved by Axerve Guaranteed Payment
  • captured: For Select&Submit plan, caputred is returned for transactions that are not marked for review.
  • any other value is an error returned by Axerve Guaranteed Payment.
RiskResponseDescription Risk Description of the RiskResponseCode
OrderReferenceDetails Informations about Shipping and Billing addresses, returned for some payment methods.

As said, <Events> can contain one or more <event> tags. the <event> tag is composed of:

name description
eventtype one of AUT, MOV, PRE, CAN, REQ, STO. There will be a node event for each existing event regarding the transaction. Follow the link for a detailed explanation of transaction statuses.
eventamount Relative value of the event
eventdate event date
eventID Unique identifier of the event

 OrderReferenceDetails

here we’ll describe the most important fields returned by third-party payments. Not all fields are relevant.

name description
Destination.PhysicalDestination Represents the address selected by the buyer through the AddressBook widget.
BillingAddress Represents the billing address that is associated with the payment method selected by the buyer in the Wallet widget.
OrderReferenceStatus Indicates the current status of the order reference. States can be: Draft, Open, Suspended, Canceled, Closed.
OrderLanguage Represents the Language last used, on the Login or Consent screens, by the buyer.
ExpirationTimestamp The date and time, in UTC, when the order reference will expire and will no longer be valid for authorization requests. In ISO 8601 format.
SellerOrderAttributes Provides more context about the order represented by this order reference.
OrderTotal Represents the total amount for this Order Reference object.
Buyer Provides details about the buyer.
ReleaseEnvironment Indicates if the order is for a Live (Production) or Sandbox environment.
AmazonOrderReferenceId The order reference identifier retrieved from the Amazon Button widget.
CreationTimestamp The date and time, in UTC, when the order reference was created. In ISO 8601 format.

callCheckCartaS2S

Merchants can use this method to check the Credit Card.

It’s possible to check with or without verifying the Authorization, setting the flag withAuth.

 Request details

Check a credit card:

<callCheckCartaS2S>
  <shopLogin>GEST13578</shopLogin>
  <shopTransactionId>MY-SHOP1234</shopTransactionId>
  <!-- check a card --> 
  <cardNumber>1234567812345678</cardNumber>
  <expMonth>12</expMonth>
  <expYear>21</expYear>
  <CVV2>931</CVV2>
  <withAuth>Y</withAuth>
</callCheckCartaS2S> 

Check a token:

<callCheckCartaS2S>
  <shopLogin>GEST13578</shopLogin>
  <shopTransactionId>MY-SHOP1234</shopTransactionId>
  <tokenValue>ABCD12345678EFGD</tokenValue>
  <withAuth>Y</withAuth>
</callCheckCartaS2S> 

Parameters in bold are mandatory.

parameter name description type length
shopLogin the merchant’s code string 30
shopTransactionId shop transaction ID value string 50
withAuth tries to authorize the card.
Y on N
string 1
apikey If you have selected the apiKey authentication method, add the apikey field to the call. More details about the apiKey here.

If you want to check a credit card by credit card number, month and year of expiration, use these fields:

parameter name description type length
cardNumber credit card number string 20
expMonth card expiration month string 2
expYear card expiration year string 2
CVV2 security code of the card string 4

Alternatively, you can use tokenValue to check if a token is still valid:

parameter name description type length
tokenValue String containing the token value returned by Axerve Ecommerce Solutions.
In case of PayPalBillingAgreement this token value is the token returned by PayPal during the Billing Agreements.
string 25

Response details

Response example:

<callCheckCartaS2SResult>
  <GestPayS2S xmlns="">
    <TransactionType>CHECKCARD</TransactionType>
    <TransactionResult>OK</TransactionResult>
    <TransactionErrorCode>0</TransactionErrorCode>
    <TransactionErrorDescription>Transaction correctly processed</TransactionErrorDescription>
    <AuthorizationErrorCode>0</AuthorizationErrorCode>
    <AuthorizationResult>KO</AuthorizationResult>
    <AuthorizationCodeDescription>negative balance</AuthorizationCodeDescription>
    <CardCountry>ITALIA</CardCountry>
    <CardCountryCode>380</CardCountryCode>
    <CheckCVV>OK</CheckCVV>
    <CheckCVVDescription>CVV VALID</CheckCVVDescription>
    <IssuerCountry>ITALIA</IssuerCountry>
    <IssuerCountryCode>380</IssuerCountryCode>
    <CompanyDescription>MASTERCARD</CompanyDescription>
    <CompanyCode>3</CompanyCode>
    <Commercial>N</Commercial>
    <ProductDescription>Standard MasterCard® Card</ProductDescription>
    <ProductType>Credit</ProductType>
    <CheckDigit>OK</CheckDigit>
    <CheckDigitDescription>CheckDigit VALID</CheckDigitDescription>
    <CheckDate>OK</CheckDate>
    <CheckDateDescription>DATE VALID</CheckDateDescription>
    <EnrolledCode>Y</EnrolledCode>
    <EnrolledDescription>ENROLLED</EnrolledDescription>
    <Prepaid>N</Prepaid>
  </GestPayS2S>
</callCheckCartaS2SResult>
name description
TransactionType CHECKCARD
TransactionResult OK or KO
TransactionErrorDescription transaction error description
AuthorizationErrorCode authorisation error code if an error occurred
AuthorizationResult authorization result. It can be OK or KO or NULL
AuthorizationCodeDescription code description
CardCountry nationality of the card
CardCountryCode nationality code of the card
CheckCVV result of the check CVV. It can be OK or KO or NULL
CheckCVVDescription description of CVV check results
IssuerCountry nationality of the card issuer
IssuerCountryCode nationality code of the card issuer
CompanyDescription Description of the Card company
CompanyCode Code of the Company
Commercial Flag that indicates if the Card is commercial or not. Y or N
ProductDescription Description of the product linked to the card
ProductType type of the product: Credit or Debit
CheckDigit OK or KO, acording to the check digit of the card
CheckDigitDescription description of the check digit response
CheckDate OK or KO, acording to the check date of the card
CheckDateDescription description of the check date response
EnrolledCode 3D Secure enabled:
  • Y enabled
  • N not enabled
  • E error: could not contact the credit card company
  • U could not verify
EnrolledDescription enrolment description
Prepaid indicates if the card is prepaid of not (Y, N, or empty)

CallRequestTokenS2S

Merchants can use this method to request the token generation for a Credit Card. This token can be generated as Standard Format or Custom Format. Tokens created by merchants belonging to a group will be available to all the merchants of the same group.

 Request details

Request example:

<CallRequestTokenS2S>
  <shopLogin>GEST13578</shopLogin>
  <requestToken>MASKEDPAN</requestToken>
  <cardNumber>1234567812345678</cardNumber>
  <expiryMonth>12</expiryMonth>
  <expiryYear>21</expiryYear>
  <withAuth>Y</withAuth>
  <cvv>931</cvv><!-- optional -->
</CallRequestTokenS2S>

Parameters in bold are mandatory.

parameter name description type length
shopLogin the merchant’s code string 30
requestToken MASKEDPAN for a Standard Token; any other value for Custom Token string 24
cardNumber credit card number string 20
expiryMonth card expiration month string 2
expiryYear card expiration year string 2
cvv security code of the card string 4
withAuth tries to authorize the card.
Y on N
string 1
apikey If you have selected the apiKey authentication method, add the apikey field to the call. More details about the apiKey here.

Response details

Response example:

<CallRequestTokenS2SResult>
  <GestPayS2S xmlns="">
    <TransactionType>REQUESTTOKEN</TransactionType>
    <TransactionResult>OK</TransactionResult>
    <TransactionErrorCode>0</TransactionErrorCode>
    <TransactionErrorDescription>Transaction correctly processed</TransactionErrorDescription>
    <AuthorizationErrorCode/>
    <AuthorizationResult/>
    <AuthorizationCodeDescription/>
    <CardCountry>POLONIA</CardCountry>
    <CardCountryCode>616</CardCountryCode>
    <CheckCVV/>
    <CheckCVVDescription/>
    <IssuerCountry>POLONIA</IssuerCountry>
    <IssuerCountryCode>616</IssuerCountryCode>
    <CompanyDescription>VISA</CompanyDescription>
    <CompanyCode>1</CompanyCode>
    <Commercial>N</Commercial>
    <ProductDescription>Visa Gold</ProductDescription>
    <ProductType>Credit</ProductType>
    <CheckDigit>OK</CheckDigit>
    <CheckDigitDescription>CheckDigit VALID</CheckDigitDescription>
    <CheckDate>OK</CheckDate>
    <CheckDateDescription>DATE VALID</CheckDateDescription>
    <EnrolledCode>E</EnrolledCode>
    <EnrolledDescription>CREDIT CARD UNVERIFIABLE</EnrolledDescription>
    <Prepaid/>
    <CardBIN/>
    <Token>44MRWNA710AC4448</Token>
    <TokenExpiryMonth>12</TokenExpiryMonth>
    <TokenExpiryYear>21</TokenExpiryYear>
  </GestPayS2S>
</CallRequestTokenS2SResult>
name description
TransactionType REQUESTTOKEN
TransactionResult OK or KO
TransactionErrorDescription transaction error description
AuthorizationErrorCode authorisation error code if an error occurred
AuthorizationResult Authorization result. It can be OK or KO or NULL
AuthorizationCodeDescription code description
CardCountry nationality of the card
CardCountryCode nationality code of the card
CheckCVV result of the check CVV. It can be OK or KO or NULL
CheckCVVDescription description of CVV check results
IssuerCountry nationality of the card issuer
IssuerCountryCode nationality code of the card issuer
CompanyDescription Description of the Card company
CompanyCode Code of the Company
Commercial Flag that indicates if the Card is commercial or not. Y or N
ProductDescription Description of the product linked to the card
ProductType type of the product: Credit or Debit
CheckDigit OK or KO, acording to the check digit of the card
CheckDigitDescription description of the check digit response
CheckDate OK or KO, acording to the check date of the card
CheckDateDescription description of the check date response
EnrolledCode 3D Secure enabled:
  • Y enabled
  • N not enabled
  • U could not verify
  • E error: could not contact the credit card company
EnrolledDescription enrolment description
Prepaid indicates if the card is prepaid of not (Y, N, or empty)
Token the token value
TokenExpiryMonth the token expiry month
TokenExpiryYear the token expiry year

callDeleteTokenS2S

Merchants can use this method to disable a token linked to a Credit Card or to cancel a PayPal Billing Agreement. Merchants belonging to a group are allowed to delete also tokens created by other merchants of the same group.

Request details

Request example:

<callDeleteTokenS2S>
  <shopLogin>90000001</shopLogin>
  <tokenValue>1234WJFXABCD5678</tokenValue>
</callDeleteTokenS2S>

Mandatory parameters are in bold.

parameter name description type length
shopLogin the merchant’s code string 30
tokenValue Token value to delete string 25

Response details

Response example:

<callDeleteTokenS2SResult>
  <GestPayS2S xmlns="">
    <TransactionType>DisableToken</TransactionType>
    <TransactionResult>OK</TransactionResult>
    <ErrorCode>0</ErrorCode>
    <ErrorDescription />
  </GestPayS2S>
</callDeleteTokenS2SResult>
parameter name description
TransactionType DisableToken
TransactionResult OK or KO
ErrorCode transaction error code
ErrorDescription transaction error description

CallUpdateTokenS2S

Merchants can use this method to update the expiry date of a token.

Merchants belonging to a group are allowed to update also tokens created by other merchants of the same group. If a merchant belongs to a group, can update also token created by the other group’s merchants.

Request details

Request example:

<CallUpdateTokenS2S>
  <shopLogin>90000001</shopLogin>
  <token>1234WJFXABCD5678</token>
  <expiryMonth>12</expiryMonth>
  <expiryYear>21</expiryYear>
  <withAut>Y</withAut>
</CallUpdateTokenS2S>

Mandatory parameters are in bold.

parameter name description type length
shopLogin the merchant’s code string 30
token Token value to update string 25
expiryMonth Assigns card expiration month string 2
expiryYear Assigns card expiration year string 2
withAut tries also to authorize the card.
Y on N
string 1
apikey If you have selected the apiKey authentication method, add the apikey field to the call. More details about the apiKey here.

Response details

Response example:

<CallUpdateTokenS2SResult>
  <GestPayS2S xmlns="">
    <TransactionType>UpdateToken</TransactionType>
    <TransactionResult>OK</TransactionResult>
    <ErrorCode>0</ErrorCode>
    <ErrorDescription />
  </GestPayS2S>
</CallUpdateTokenS2SResult>
parameter name description
TransactionType UpdateToken
TransactionResult OK or KO
ErrorCode transaction error code
ErrorDescription transaction error description

 CallIdealListS2S

Merchants can use this method to have the list of the Banks available for their customers for IDeal payment method.

Request details

Request example:

<CallIdealListS2S>
  <shopLogin>900000001</shopLogin>
</CallIdealListS2S>

Mandatory parameters are in bold.

parameter name description type length
shopLogin the merchant’s code string 30
apikey If you have selected the apiKey authentication method, add the apikey field to the call. More details about the apiKey here.

 Response details

Response example:

<CallIdealListS2SResult>
    <GestPayS2S xmlns="">
        <TransactionType>RequestIdealBankList</TransactionType>
        <TransactionResult>OK</TransactionResult>
        <ErrorCode>0</ErrorCode>
        <ErrorDescription />
        <BankList>
          <Bank>
            <BankCode>0001</BankCode>
            <BankName>E-Corp</BankName>
          </Bank>
          <Bank>
            ... 
          </Bank>
        </BankList>
    </GestPayS2S>
</CallIdealListS2SResult>
parameter name description
TransactionType  for  CallIdealListS2S, the value will be RequestIdealBankList
TransactionResult OK or KO
ErrorCode transaction error code
ErrorDescription transaction error description
BankList.Bank.BankCode  Returns Ideal Bank List, for each bank returns the Bank Code
BankList.Bank.BankName  Returns Ideal Bank List, for each bank returns the Bank Name

CallMyBankListS2S

Merchants can use this method to have the list of the Banks available for their customers for MyBank payment method.

Request details

Request example:

<CallMyBankListS2S>
  <shopLogin>900000001</shopLogin>
  <languageId>1</languageId>
</CallMyBankListS2S>

Mandatory parameters are in bold.

parameter name description type length
shopLogin the merchant’s code string 30
languageId Assigns the response language of the Bank list. Values:
  • 1 Italian
  • 2 English
  • 3 Spanish
  • 4 French
  • 5 German
number 2
apikey If you have selected the apiKey authentication method, add the apikey field to the call. More details about the apiKey here.

 Response details

Response example:

<CallMyBankListS2SResult>
    <GestPayS2S xmlns="">
        <TransactionType>MyBank</TransactionType>
        <TransactionResult>OK</TransactionResult>
        <ErrorCode>0</ErrorCode>
        <ErrorDescription />
        <BankList>
          <Bank>
            <BankCode>0001</BankCode>
            <BankName>E-Corp</BankName>
          </Bank>
          <Bank>
            ... 
          </Bank>
        </BankList>
    </GestPayS2S>
</CallMyBankListS2SResult>
parameter name description
TransactionType  for callMyBankListS2S, the value will be MyBank
TransactionResult OK or KO
ErrorCode transaction error code
ErrorDescription transaction error description
BankList.Bank.BankCode  Returns MyBank Bank List, for each bank returns the Bank Code
BankList.Bank.BankName  Returns MyBank Bank List, for each bank returns the Bank Name

CallUpdateOrderS2S

Merchants can use this method to update the order values for Risk Fraud management. For example, if the buyer changes the Shipping Address, this must be notified to Axerve Guaranteed Payment in order to review again the Order. Axerve Guaranteed Payment decides if the Order must be reviewed based on the changed values.

 Request parameters

request example:

<CallUpdateOrderS2S>
  <shopLogin>9000002</shopLogin>
  <shopTransactionId>MYSHOP-0001</shopTransactionId>
  <bankTransactionId>13675333225</bankTransactionId>
  <OrderDetails>
    ... <!-- the OrderDetails object -->
  <OrderDetails>
</CallUpdateOrderS2S>

Mandatory parameters are in bold. The attributes are:

Name Description Data Type max length
shopLogin  shopLogin value string 30
shopTransactionId shop transaction ID value string 50
bankTransactionId the bank ID value string 50
OrderDetails contains every other info needed to evaluate the payment. Refer to OrderDetails for a detailed description of its fields.
apikey If you have selected the apiKey authentication method, add the apikey field to the call. More details about the apiKey here.

Response fields

response example:

<GestPayS2S xmlns="">
  <TransactionType>RiskifiedUpdateOrder</TransactionType>
  <TransactionResult>OK</TransactionResult>
  <ErrorCode>0</ErrorCode>
  <ErrorDescription>Transazione correttamente effettuata</ErrorDescription>
</GestPayS2S>
Name Description
TransactionType RiskifiedUpdateOrder in response to CallUpdateOrderS2S
TransactionResult Returns transaction result with OK or KO
ErrorCode a code related to the transaction result
ErrorDescription the description connected to the ErrorCode value

callExchangeRateS2S

Merchants can use this method to retrieve the exchange rates for a specified currency, in the last 7 days (current day and 6 previous days).

Exchange rates are meant as the conversion rates applied on that day to that currency by the phases that credit that amount on the bank account of the merchant, in order to get the corresponding EUR value.

A more descriptive explanation of callExchangeRateS2S is in the docs.

 Request details

Request example:

<callExchangeRateS2S>
    <shopLogin>GESPAY65987</shopLogin>
    <uicCode>1</uicCode>
    <isoCode>USD</isoCode>
    <numericIsoCode>840</numericIsoCode>
</callExchangeRateS2S>

Parameters in bold are mandatory.

parameter name description type length
shopLogin the merchant’s code string 30
uicCode the UIC code string 10
isoCode the ISO code - see the Code column. string 10
numericIsoCode the ISO code - see the Num column. string 10
apikey If you have selected the apiKey authentication method, add the apikey field to the call. More details about the apiKey here.

Response details

Response example:

<callExchangeRateS2SResult>
  <GestPayS2S xmlns="">
    <TransactionType>ExchangeRate</TransactionType>
    <TransactionResult>OK</TransactionResult>
    <ErrorCode>0</ErrorCode>
    <ErrorDescription>Transazione correttamente effettuata</ErrorDescription>
    <ExchangeRates>
        <ExchangeRate>
            <UICCode>1</UICCode>
            <ISOCode>USD</ISOCode>
            <NumericISOCode>840</NumericISOCode>
            <ExchangeRate>1,0617</ExchangeRate>
            <CreditDate DateFormat="DD/MM/YYYY">TODAY_CONST</CreditDate>
        </ExchangeRate>
        <ExchangeRate>
            <UICCode>1</UICCode>
            <ISOCode>USD</ISOCode>
            <NumericISOCode>840</NumericISOCode>
            <ExchangeRate>1,0602</ExchangeRate>
            <CreditDate DateFormat="DD/MM/YYYY">YESTERDAY_CONST</CreditDate>
        </ExchangeRate>
        <ExchangeRate>
            <UICCode>1</UICCode>
            <ISOCode>USD</ISOCode>
            <NumericISOCode>840</NumericISOCode>
            <ExchangeRate>1,0603</ExchangeRate>
            <CreditDate DateFormat="DD/MM/YYYY">MINUS_2_CONST</CreditDate>
        </ExchangeRate>
        <ExchangeRate>
            <UICCode>1</UICCode>
            <ISOCode>USD</ISOCode>
            <NumericISOCode>840</NumericISOCode>
            <ExchangeRate>1,0599</ExchangeRate>
            <CreditDate DateFormat="DD/MM/YYYY">MINUS_3_CONST</CreditDate>
        </ExchangeRate>
        <ExchangeRate>
            <UICCode>1</UICCode>
            <ISOCode>USD</ISOCode>
            <NumericISOCode>840</NumericISOCode>
            <ExchangeRate>1,0595</ExchangeRate>
            <CreditDate DateFormat="DD/MM/YYYY">MINUS_4_CONST</CreditDate>
        </ExchangeRate>
        <ExchangeRate>
            <UICCode>1</UICCode>
            <ISOCode>USD</ISOCode>
            <NumericISOCode>840</NumericISOCode>
            <ExchangeRate>1,0595</ExchangeRate>
            <CreditDate DateFormat="DD/MM/YYYY">MINUS_5_CONST</CreditDate>
        </ExchangeRate>
        <ExchangeRate>
            <UICCode>1</UICCode>
            <ISOCode>USD</ISOCode>
            <NumericISOCode>840</NumericISOCode>
            <ExchangeRate>1,0595</ExchangeRate>
            <CreditDate DateFormat="DD/MM/YYYY">MINUS_6_CONST</CreditDate>
        </ExchangeRate>
    </ExchangeRates>
  </GestPayS2S>
  </callExchangeRateS2SResult>
name description
TransactionType ExchangeRate
TransactionResult OK or KO
ErrorCode error code occurred
ErrorDescription error description relative to error code
ExchangeRates Tag for list of exchange rates
ExchangeRate Tag for exchange rate detail
UICCode UIC code
ISOCode ISO code
NumericISOCode Numeric ISO code
ExchangeRate Value of exchange rate
CreditDate Day of validity for this Exchange Rate

callCheckTokenS2S

Merchants can use this method to check the existence of a specific token value. If the token exists, the method provides all the token details (expiration, card details, card art if applicable, etc…)

Request details

Request example:

<callCheckTokenS2S>
  <shopLogin></shopLogin>
  <TokenValue></TokenValue>
  <apikey></apikey>
</callCheckTokenS2S>
Name Description Data Type max length
shopLogin  shopLogin value string 30
tokenValue String containing the token value returned by Axerve Ecommerce Solutions. string 25

 Response details

Response example:

<callCheckTokenS2SResult>
  <GestPayS2S xmlns="">
    <TransactionType>CHECKTOKEN</TransactionType>
    <TransactionResult>OK</TransactionResult>
    <TransactionErrorCode>0</TransactionErrorCode>
    <TransactionErrorDescription>Transazione correttamente effettuata</TransactionErrorDescription>
    <tokenDetails>
      <tokenValue>42V8ZN2BA0144011</tokenValue>
      <tokenExpiryMonth >02</tokenExpiryMonth >
      <tokenExpiryYear >23</tokenExpiryYear >
      <tokenProvider />
      <cardDetails>
        <cardExpiryMonth />
        <cardExpiryYear />
        <cardHolderName />
        <cardSuffix />
      </cardDetails>
      <cardAssets>
        <cardArt>
          <height />
          <mediaContents />
          <type />
          <width />
        </cardArt>
        <brandLogo>
          <height />
          <mediaContents />
          <type />
          <width />
        </brandLogo>
      </cardAssets>
    </tokenDetails>             
  </GestPayS2S>
</callCheckTokenS2SResult>
Name Description
TransactionType  For callCheckTokenS2S, the value will be CHECKTOKEN.
TransactionResult OK or KO.
TransactionErrorCode Transaction error code.
TransactionErrorDescription Transaction error description.
tokenDetails Token details. The contents of this field are shown below in detail.

tokenDetails details:

Name Description
tokenValue String containing the token value returned by Axerve Ecommerce Solutions.
tokenExpiryMonth The token expiration month.
tokenExpiryYear The token expiration year.
tokenProvider The entity providing the token. It can be: AXERVE, VISA, MASTERCARD, PAYPAL, AMAZON, APPLE, SEPADD.
cardDetails.cardSuffix The last 4 digit of the card PAN.
cardDetails.cardExpiryMonth The card expiry month.
cardDetails.cardExpiryYear The card expiry Year.
cardDetails.cardHolderName The cardholder name.
cardAssets.cardArt.type The file format of the card art (card image)
cardAssets.cardArt.mediaContents The card image (Base64)
cardAssets.cardArt.height The card art (card image) height
cardAssets.cardArt.width The card art (card image) width
cardAssets.brandLogo.type The file format of the brand logo (e.g. Visa, Mastercard, etc..)
cardAssets.brandLogo.mediaContents The brand logo (e.g. Visa, Mastercard, etc..) image (Base64)
cardAssets.brandLogo.height The brand logo (e.g. Visa, Mastercard, etc..) height
cardAssets.brandLogo.width The brand logo (e.g. Visa, Mastercard, etc..) width

js_GestPay.js API

To start using this feature, import the script:

 <script src="https://ecomm.sella.it/pagam/JavaScript/js_GestPay.js"
    type="text/javascript"></script>

Once the script is imported, it will do some security checks. You can see this with the BrowserEnabled variable:

if ( BrowserEnabled ) {
    //The Browser is supported! 
    //Proceed to create the Payment page
} else {
    //The browser is not supported 
    //Place here error handle code
}

js_Gestpay.js is a javascript that enable you to process payments on your website, leaving you with the ability to completely design your custom payment page.

To use the following functionalities, you should first call `WSCryptDecrypt.Encrypt webservice.

CreatePaymentPage

Syntax:

GestPay.CreatePaymentPage(
    shopLogin, //I.E. 90000001
    EncryptedString, // "CFD3732BB102..." 
    PaymentPageLoaded); // a callback to call on success

Example:

GestPay.CreatePaymentPage(
    '9000001',  //shopLogin
    'DcffrrnDNdjfnemfnermgnermNfdm,gnem/*ng', //EncryptedString 
    function (Result) {  //callback 
        if(Result.ErrorCode == 10){ 
            //iFrame created and payment page correctly loaded
        } else {
            //An error has occurred, check ErrorCode and ErrorDescription
            //properties of the Result object
        } 
    });

The first thing to do to accept payments securely is to call GestPay.CreatePaymentPage().

The function will create an hidden iFrame into the body element and will load the payment page passing the merchant code and the generated encrypted string from the previous phase.

Name Type description
Shop Login string the code that identifies your shop.
Encrypted String string the string created with WSCryptEncrypt.Encrypt webservice.
callback function the callback that will be called with the result

SendPayment

Credit card authorization

syntax:

GestPay.SendPayment ({ 
    CC    : '1234567812345678', 
    EXPMM : '06', 
    EXPYY : '12', 
    CVV2 : '123', //optional
    Name : 'Some Dude', //optional 
    Email: 'some@dude.net' //optional  
  },
  callBackObj);

example:

GestPay.SendPayment({
    CC : document.getElementById('CC').value, 
    EXPMM : document.getElementById('EXPMM').value, 
    EXPYY: document.getElementById('EXPYY').value, 
    CVV2: document.getElementById('CVV2').value, 
    Name: document.getElementById('Name').value, 
    Email: document.getElementById('Email').value
  },
  function (Result) {
    if(Result.ErroCode == 0) {
      //Transaction correctly processed
      //Decrypt the Result.EncryptedString property to read the 
      //transaction result
    } else {
      //An error has occurred, check ErrorCode and ErrorDescription 
      //properties of the Result object
    }
});

To send the credit card data to the hidden iFrame, the checkout page will assign a function to the OnSubimt event of the credit card form, this function will retrieve the credit card data and will call the GestPay.SendPayment method providing an object with the credit card number (CC), the expiration month (EXPMM) and the expiration year (EXPYY), the CVV (CVV2) if enabled, and a CallBack object.

The input is composed of two arguments:

Name Description Type Size
CC Credit card number number min: 13, max: 19
EXPMM Expiration Month number 2
EXPYY Expiration Year number 2
CVV2 (optional) Cvv/4DBC number min:3, max:4
Name (optional) Buyer’s name string 
Email (optional) Buyer’s email string

CVV2, Name and Email are optional but highly recommended.

Call after 3D Authentication

Syntax:

GestPay.SendPayment({
    PARes : '', 
    TransKey : ''
  },  
  callbackFunction
});

Example:

GestPay.SendPayment ({
  PARes : 'xMNjdsre23214hjksBBDsjkrhewGSD/*dwhjdkhawNDAHDGUY', 
  TransKey : 'eFtstSStefgd23432'
  },
  function (Result) {
    if(Result.ErroCode == 0){
      // Transaction correctly processed ! 
      // Decrypt the Result.EncryptedString property to read the 
      // transaction result
    }else{
      // An error has occurred, check ErrorCode and ErrorDescription
      // properties of the Result object
    }
});

If during the first SendPayment call Result.ErrorCode == 8006, you should redirect the user to the pagam3d.aspx page. You can read about the process at this link: Customizing the payment page.

When card holder is verified and authorized, you have to re-call SendPayment() with some new parameters:

ping

syntax:

GestPay.ping(callBackObj);

example:

GestPay.ping(function (Result) {
    if(Result.ErroCode == 1111) {
      //connection estabilished: servers are available
      console.log(Result.ErrorDescription) // outputs 'Ping Back'
    } else {
      //An error has occurred, check ErrorCode and ErrorDescription 
      //properties of the Result object
    }
});

The Ping function checks that there is an active connection with Axerve Ecommerce Solutions.

Useful for troubleshooting connection errors.

getLastAnswer

syntax:

GestPay.getLastAnswer(callBackObj);

example:

GestPay.getLastAnswer(function (Result) {
  // asks Axerve Ecommerce Solutions to re-send the last Result object. 
  });

getLastAnswer asks Axerve Ecommerce Solutions to send back the last received Result object.

checkCC

syntax:

GestPay.checkCC(CCNum, callBackObj);

example:

GestPay.checkCC('12345678', function (Result) {
  if (Result.ErrorCode != 0) {
    console.log(Result.ErrorCode); // i.e. 1119
    console.log(Result.ErrorDescription); // 'Credit card number with wrong length'
    ... //handle the error
  } else {
    console.log('the Credit Card Number is valid');
  }
});

checkCC checks the formal correctness of the credit card number.

checkCVV

syntax:

GestPay.checkCVV(CVVNum, callBackObj);

example:

var CVV = 'XY@Z';

GestPay.checkCVV(CVV, function (Result) {
  if (Result.ErrorCode != 0) {
    console.log(Result.ErrorCode); // i.e. 1149
    console.log(Result.ErrorDescription); // 'Missing or wrong CVV2'
    ... //handle the error
  } else {
    console.log('the CVV value is valid'); 
  }
});

checkCVV checks the formal correctness of the value sent as CVV.

checkEXPMM

syntax:

GestPay.checkEXPMM(EXPMMVal, callBackObj);

example:

var EXPMMVal = '123'; //not valid ! 

GestPay.checkEXPMM(EXPMMVal, function (Result) {
  if (Result.ErrorCode != 0) {
    console.log(Result.ErrorCode); // i.e. 1124
    console.log(Result.ErrorDescription); // 'Invalid expiry month'
    ... //handle the error
  } else {
    console.log('the expiring month value is valid'); 
  }
});

checkEXPMM checks the formal correctness of the value sent as EXPMMVal. It represents the expiring month so it should be a value between 0 and 12.

checkEXPYY

syntax:

GestPay.checkEXPYY(EXPYYVal, callBackObj);

example:

var EXPYYVal = '99999'; //not a valid year ! 

GestPay.checkEXPYY(EXPYYVal, function (Result) {
  if (Result.ErrorCode != 0) {
    console.log(Result.ErrorCode); // i.e. 1125
    console.log(Result.ErrorDescription); // 'Invalid expiry year'
    ... //handle the error
  } else {
    console.log('the expiring year is valid'); 
  }
});

checkEXPYY checks the formal correctness of the value sent as EXPYYVal. It represents the expiring year so it should be a value between 0 and 99.

checkEXPDATE

syntax:

GestPay.checkEXPDATE(EXPMMVal, EXPYYVal, callBackObj);

example:

var EXPMMVal = '11';
var EXPYYVal = '211'; 

GestPay.checkEXPDATE(EXPMMVal, EXPYYVal, function (Result) {
  if (Result.ErrorCode != 0) {
    console.log(Result.ErrorCode); // i.e. 1125
    console.log(Result.ErrorDescription); // 'Invalid expiry year'
    ... //handle the error
  } else {
    console.log('the expiring year is valid'); 
  }
});

checkEXPDATE checks the formal correctness of the expiry date, sent as two variables for month and year.

checkEMAIL

syntax:

GestPay.checkEMAIL(EmailVal, callBackObj);

example:

GestPay.checkEMAIL( 'email@example.com' , function (Result) {
  if (Result.ErrorCode != 0) { // mail is valid, ErrorCode is 0 
    console.log(Result.ErrorCode); 
    console.log(Result.ErrorDescription);
    ... //handle error
  } else {
    console.log('the email is valid');  //prints 'the email is valid'
  }
});

checkEMAIL checks the formal correctness of the email address.

 the Result Object

Example: Merchant not 3D enabled or credit card not enrolled.

LocalObj.CallBack = function(Result){ 
    if ( Result.ErrorCode != 0 ) {
        //Call failed an error has occurred 
        //.... place here error handle code...
    } else {
        // Transaction correctly processed proceed to decrypt the
        // Result.EncryptedResponse property
    } 
}

Example: Merchant 3D enabled and 3D enrolled credit card

LocalObj.CallBack = function (Result) { 
    if (Result.ErrorCode != 0){
        if (Result.ErrorCode == 8006){
            //3D Transaction - Card holder authorization required 
            //Get the TransKey
            //NOTE you have to store this value in your server for 
            //further use
            var TransKey = Result.TransKey;
            //Get the VBVRisp
            var VBVRisp = Result.VBVRisp;
            //place here the code to redirect the card holder to the 
            //authentication website
        } else {
            //Call failed an error has occurred 
            //.... place here error handle code...
        } 
    } else {
      //Transaction correctly processed proceed to decrypt the
      //Result.EncryptedResponse property
    }
}

When callbacks are executed, the Result object will contain useful properties, needed to understand if an error has occurred.

name description
Result.ErrorCode the error code
Result.ErrorDescription the error description
Result.EncryptedResponse returns the encrypted response string
Result.TransKey return the TransKey in case of 3D enrolled credit card
Result.VBVRisp return the ciphered string needed for the cardholder authentication in case of 3D enrolled credit card

The GestPay.SendPayment() function will send an asynchronous call to the hidden iFrame windows, the CallBack object will retrieve the Result object once the transaction result is thrown from the hidden payment page.

Alternative Payments Examples

Encrypt can be used to start a payment process in one of the several alternative payments that Axerve Ecommerce Solutions supports.

You can see the complete list of Axerve Ecommerce Solutions supported alternative payments in the docs.

As a recap, you can use the <paymentType> tag to specify which payment methods you want to enable. In the next paragraphs we will show some alternative payment examples.

WsS2S Example: Apple Pay

Apple Pay example:

<callPagamS2S>
  <!-- mandatory data -->
  <shopLogin>9000002</shopLogin>
  <uicCode>242</uicCode><!-- code for euro -->
  <amount>24.21</amount>
  <shopTransactionId>MYSHOP-0001</shopTransactionId>
  <!-- insert here data from Apple Pay -->
  <applePay> 
    <applePayPKPaymentToken>
    {
      "paymentData": {
        "data": "Q0tfx6QzXdx...",
        "signature": "MIAGCSqGSIb3DQEHAq...",
        "header": {
          "publicKeyHash": "b9OHKov7pD...",
          "ephemeralPublicKey": "MFkwE...",
          "transactionId": "df9ea7239074..."
        },
        "version": "EC_v1"
      },
      "transactionIdentifier": "DF9EA72390...",
      "paymentMethod": {
        "network": "Visa",
        "type": "debit",
        "displayName": "Visa0492"
      }
    }
    </applePayPKPaymentToken>
  </applePay>
  <!-- fill the remaining fields with usual data --> 
  ...
</callPagamS2S>

Please read the detailed setup process for Apple Pay in the docs.

Once you have received a Payment Token Package, you can call callPagamS2S with the relevant data.

Note that, if using Apple Pay, no Credit Card or Token data are needed.

For a real example of Payment Token Package, contained in applePayPKPaymentToken, click here.

The most important field in this process is applePayPKPaymentToken. Here is a description:

Key Value Description
applePayPKPaymentToken string contains a UTF-8 serialization of a plain-text JSON dictionary.

Once you have submitted callPagamS2S, Axerve Ecommerce Solutions will behave exactly as always and your payment will be processed.

Encrypt Example: Alipay

Alipay example:

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>100</amount>
  <shopTransactionId>34az85ord19</shopTransactionId>
  <paymentTypes>
    <paymentType>S2PALI</paymentType>
  </paymentTypes>
  <OrderDetails>
    <CustomerDetail>
      <PrimaryEmail>alfred.nobel@dynamite.se</PrimaryEmail>
    </CustomerDetail>
  </OrderDetails>
</Encrypt>

Alipay does not need any mandatory parameters. Just specify the PaymentType S2PALI and the payment page will show to your user.

If you specify the PrimaryEmail in the OrderDetails tag, you will redirect your user to Alipay payment page where some fields are already filled.

January 2019 breaking changes

If you are using Alipay via Ecommerce you need to update your integration because from 21/01/2019 more mandatory fields will be required from Aliplay.

New mandatory fields are ProductDetail: you need to add one field for each item in the cart with the product name and the quantity. All these fields must me wrapped inside a ProductDetails tag.

Alipay January 2019 example

<ecom:Encrypt>
  <ecom:shopLogin>tests2p</ecom:shopLogin>
  <ecom:uicCode>144</ecom:uicCode>
  <ecom:amount>1</ecom:amount>
  <ecom:shopTransactionId>alipay_test</ecom:shopTransactionId>
  <ecom:paymentTypes>
    <ecom:paymentType>S2PALI</ecom:paymentType>
  </ecom:paymentTypes>
  <ecom:OrderDetails>
    <ecom:CustomerDetail>
      <ecom:PrimaryEmail></ecom:PrimaryEmail>
    </ecom:CustomerDetail>
    <ecom:ProductDetails>
      <ecom:ProductDetail>
        <ecom:Name>product1</ecom:Name>
        <ecom:Quantity>1</ecom:Quantity>
      </ecom:ProductDetail>
      <ecom:ProductDetail>
        <ecom:Name>product2</ecom:Name>
        <ecom:Quantity>5</ecom:Quantity>
      </ecom:ProductDetail>
      ...
      ...
    </ecom:ProductDetails>
  </ecom:OrderDetails>
</ecom:Encrypt>

Other product information like the product code and its price are optional. Keep in mind that the total must be exactly the sum of all items price.

Encrypt Example: Amazon Pay

Amazon Pay example:

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>100</amount>
  <shopTransactionId>34az85ord20</shopTransactionId>
  <paymentTypes>
    <paymentType>AMAZONPAY</paymentType>
  </paymentTypes>
  <!-- OPTIONAL: to retrieve a token for recurrent 
  payments, fill out this tag -->
  <amazonPayBillingAgreementDescription />
</Encrypt>

Amazon Pay does not need any mandatory parameters. Use AMAZONPAY as Payment Type and the user will be redirected to Amazon Pay.

Recurring payments with Amazon Pay

If you want to perform recurring payments, by filling this field you obtain a token that you can use with callPagamS2S.

Accepted values for amazonPayBillingAgreementDescription:

Value Description
Empty or missing no token is returned.
paynowandrecurring a payment is performed instantly and a token is generated for subsequent payments.
onlyrecurring only a token is returned.

WSS2S Example: Amazon Pay

Amazon Pay example via S2S:

<callPagamS2S>
    <shopLogin>9000002</shopLogin>
    <uicCode>242</uicCode><!-- euro -->
    <amount>24.21</amount>
    <shopTransactionId>MYSHOP-0001</shopTransactionId>
    <paymentTypes>
        <paymentType>AMAZONPAY</paymentType>
    <paymentTypes>
    <transKey>123456789sdfasdgdgf...</transkey>
</callPagamS2S>

If you implement AmazonPay in your shop by using Amazon widgets for address and cards, you can finalize the call by calling CallPagamS2S.

Use AMAZONPAY for the paymentType and send the Amazon Order Reference ID in the transKey field.

Encrypt Example: BancomatPay

BancomatPay example:

You must use BANCOMATPAY as paymentType.

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>100</amount>
  <shopTransactionId>34az85ord20</shopTransactionId>
  <paymentTypes>
    <paymentType>BANCOMATPAY</paymentType>
  </paymentTypes>
  <paymentTypeDetail>
    <BancomatPayPhoneNumber>+393454...</BancomatPayPhoneNumber>
  </paymentTypeDetail>
</Encrypt>

Encrypt Example: Bizum

Bizum example:

You must use BIZUM as paymentType.

<Encrypt>
    <shopLogin>9000001</shopLogin>
    <apikey>dGVxxxxxxxxxxNToxMQ==</apikey>
    <uicCode>242</uicCode>
    <amount>1</amount>
    <shopTransactionId>bizum_test</shopTransactionId>
    <languageId>1</languageId>
    <paymentTypes>
        <paymentType>BIZUM</paymentType>
    </paymentTypes>
  <OrderDetails> 
    <CustomerDetail>
      <FirstName>Galileo</FirstName>
      <Lastname>Galilei</Lastname>
      <PrimaryEmail>mymail@mail.com</PrimaryEmail>
      <PrimaryPhone>700000000</PrimaryPhone>
    </CustomerDetail>
    </OrderDetails>
</Encrypt>

Encrypt Example: Consel

Consel example:

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>985</amount>
  <shopTransactionId>34az85ord19</shopTransactionId>
  <paymentTypes>
    <paymentType>CONSEL</paymentType><!-- select CONSEL -->
  </paymentTypes>
  <Consel_MerchantPro>WIK</Consel_MerchantPro>
  <Consel_CustomerInfo>
    <Surname>Rossi</Surname>
    <Name>Mario</Name> 
    <TaxationCode>RSSMRA70D23H501H</TaxationCode> 
    <Address>Via Torino</Address>
    <City>Roma</City> 
    <StateCode>RM</StateCode> 
    <DateAddress>11/04/1999</DateAddress> 
    <Phone>0632...</Phone> 
    <MobilePhone>331...</MobilePhone>
  </Consel_CustomerInfo>
</Encrypt>

More information about Consel (Sella Personal Credit) can be found in the documentation.

Name max length description
Consel_MerchantPro 3 Merchant Promotional Code (Mandatory to show Consel in the pagam’s Payment Method)
Consel_CustomerInfo Wrapper for Consel tags)
Surname 30 Customer Surname
NAme 30 Customer Name
TaxationCode 30 Customer Taxation Code
Address 30 Customer Address
City 30 Customer City
StateCode 30 Customer State Code
DateAddress 30 Date since the customer lives in the declared address (dd/mm/yyyy)
Phone 30 Customer Phone
MobilePhone 30 Customer Mobile phone

Encrypt Example: EPS

EPS example:

<Encrypt>
  <shopLogin>90000001</shopLogin>
  <uicCode>242</uicCode><!-- Euro -->
  <amount>0.10</amount>
  <shopTransactionId>MYSHOP_001</shopTransactionId>
  <paymentTypes>
    <paymentType>S2PEPS</paymentType>
  </paymentTypes>
</Encrypt>

EPS does not need mandatory parameters.

You must use S2PEPS as paymentType.

More informations about EPS are in the doc.

Encrypt Example: Giropay

Giropay example:

<Encrypt>
  <shopLogin>90000001</shopLogin>
  <uicCode>242</uicCode><!-- Euro -->
  <amount>0.10</amount>
  <shopTransactionId>MYSHOP_001</shopTransactionId>
  <paymentTypes>
    <paymentType>S2PGIR</paymentType>
  </paymentTypes>
</Encrypt>

Giropay does not need mandatory parameters.

You must use S2PGIR as paymentType.

More informations about Giropay are in the doc.

Encrypt Example: IDeal and MyBank

MyBank example:

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>985</amount>
  <shopTransactionId>34az85ord19</shopTransactionId>
  <paymentTypes>
    <paymentType>MYBANK</paymentType>
  </paymentTypes>
  <paymentTypeDetail> 
    <MyBankBankCode>Code0000X</MyBankBankCode>
  </paymentTypeDetail> 
</Enrcypt>

IDeal example:

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>10</amount>
  <shopTransactionId>34az85ord19</shopTransactionId>
  <paymentTypes>
    <paymentType>IDEAL</paymentType>
  </paymentTypes>
  <paymentTypeDetail> 
    <IdealBankCode>Code0000Y</IdealBankCode>
  </paymentTypeDetail> 
</Enrcypt>

If you choose let your users pay with MyBank or IDeal, you have to compile other two fileds.

More details can be found in at the MyBank and IDeal page.

Name max length description
paymentTypeDetail container of one of MyBankBankCode or IdealBankCode
MyBankBankCode 25 Tag to set the Bank to show on payment page (the bank List is retrieved from WsS2S.CallMyBankListS2S)
IdealBankCode 25 Tag to set the Bank to show on payment page (the bank List is retrieved from WsS2S.CallIdealListS2S)

Encrypt Example: Klarna

Here is an example of how to enable Klarna with Axerve Ecommerce Solutions.

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>100</amount>
  <shopTransactionId>34az85ord19</shopTransactionId>
  <paymentTypes>
    <paymentType>KLARNA</paymentType>
  </paymentTypes>
  <OrderDetails>
    <CustomerDetail>
      <FirstName>Alfred</FirstName>
      <Lastname>Nobel<Lastname>
      <PrimaryEmail>alfred.nobel@dynamite.se</PrimaryEmail>
      <PrimaryPhone>00491522113356</PrimaryPhone>
      <SocialSecurityNumber>410321-9202</SocialSecurityNumber>
    </CustomerDetail>
    <BillingAddress>
      <StreetNumber>14<StreetNumber>
      <StreetName>Sturegatan</StreetName><!--mandatory-->
      <City>Stockholm</City><!--mandatory-->
      <ZipCode>SE-102</ZipCode><!--mandatory-->
      <CountryCode>SE</CountryCode><!--mandatory-->
    </BillingAddress>
    <ProductDetails>
      <ProductDetail><!-- mandatory -->
        <ProductCode>1</ProductCode>
        <SKU>AK-7</SKU> 
        <Name>TV2000</Name> 
        <Description>Television</Description> 
        <Quantity>1</Quantity> 
        <Price>100</Price> 
        <UnitPrice>100</UnitPrice> 
        <Type>1</Type> 
        <Vat>10</Vat> 
        <Discount>0</Discount>
      </ProductDetail> 
    </ProductDetails>
  </OrderDetails>
</Encrypt>

Klarna requires these parameters as mandatory, children of OrderDetails:

Name max length description
BillingAddress.StreetName 100 Shipping street name. Accepts only alpha-numeric characters.
BillingAddress.City 50 Shipping city name
BillingAddress.ZipCode 50 Shipping zip code
BillingAddress.CountryCode 2 one of [AT | DK | FI | DE | NL | NO | SE]
ProductDetails.ProductDetail the list of ordered products

We strongly suggest you to read these notes on BillingAddress and ShippingAddress.

If you send other fields, your customer will find them already filled:

CustomerDetail.FirstName 65 Customer First Name
CustomerDetail.Lastname 65 the list of ordered products
CustomerDetail.PrimaryEmail 100 Customer primary email
CustomerDetail.PrimaryPhone 100 Customer’s phone including prefix. See below on how to use it.
CustomerDetail.SocialSecurityNumber 20 Customer’s social or fiscal identifier (for Klarna Use)
BillingAddress.StreetNumber 5 Shipping Street Number. Accepts only numbers.

ProductDetails can have one or more ProductDetail. Here is a description of its fields:

ProductCode 12 Article’s product Code
SKU 50 Article’s Stock Keeping Unit
Name 100 Article’s name
Description 255 Article’s description
Quantity 3 The number of products
Price 12 Article’s price
UnitPrice 12 Article’s Unit Price
Type 2 The type of article: visit the klarna page in the docs to set the right value
Vat 2 Value-Added Tax (the value of the tax)
Discount 2 The amount offered by you as discount, in percentage. 10 means 10% and it is subtracted to the price.

More details about Klarna are in the documentation.

Encrypt Example: Konbini

Konbini example:

<Encrypt>
  <shopLogin>90000001</shopLogin>
  <uicCode>242</uicCode><!-- Euro -->
  <amount>0.10</amount>
  <shopTransactionId>MYSHOP_001</shopTransactionId>
  <paymentTypes>
    <paymentType>S2PKON</paymentType>
  </paymentTypes>
  <!--optional, to skip authentication -->
  <OrderDetails>
    <CustomerDetail>
      <PrimaryEmail>yamauchi.fusajiro@nintendo.jp</PrimaryEmail>
    </CustomerDetail>
  </OrderDetails>
</Encrypt>

Konbini does not need mandatory parameters.

You must use S2PKON as paymentType.

If you pass the PrimaryEmail tag, the customer will be redirected directly to the payment page.

More informations about Konbini are in the doc.

Encrypt Example: MercadoPago

MercadoPago example:

<Encrypt>
  <shopLogin>90000001</shopLogin>
  <uicCode>242</uicCode><!-- Euro -->
  <amount>0.10</amount>
  <shopTransactionId>MYSHOP_001</shopTransactionId>
  <paymentTypes>
    <paymentType>S2PMER</paymentType>
  </paymentTypes>
  <OrderDetails>
    <BillingAddress>
      <!-- mandatory: -->
      <CountryCode>BR</CountryCode>
    </BillingAddress>
  </OrderDetails>
</Encrypt>

MercadoPago requires the parameter BillingAddress.CountryCode, children of OrderDetails:

Name max length description
BillingAddress.CountryCode 2 one of [ BR, MX, CO ]

You must use S2PMER as paymentType.

More informations about MercadoPago are in the doc.

Encrypt Example: Multibanco

Multibanco example:

<Encrypt>
  <shopLogin>90000001</shopLogin>
  <uicCode>242</uicCode><!-- Euro -->
  <amount>0.10</amount>
  <shopTransactionId>MYSHOP_001</shopTransactionId>
  <paymentTypes>
    <paymentType>S2PMUL</paymentType>
  </paymentTypes>
</Encrypt>

Multibanco does not need mandatory parameters.

You must use S2PMUL as paymentType.

More informations about Multibanco are in the doc.

Encrypt example: Paypal

Enabling Paypal

If you only specify PAYPAL payment type, Axerve Ecommerce Solutions won’t show the payment page but will redirect directly to Paypal’s payment page:

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>985</amount>
  <shopTransactionId>34az85ord19</shopTransactionId> 
  <paymentTypes>
    <paymentType>PAYPAL</paymentType>
  </paymentTypes>
<Encrypt>

A detailed description of Axerve Ecommerce Solutions integration with Paypal is in the docs.

Paypal Seller Protection

Paypal Seller Protection example:

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>985</amount>
  <shopTransactionId>34az85ord19</shopTransactionId>
  <ppSellerProtection>1</ppSellerProtection>
  <shippingDetails>
    <shipToName>Marco Bianchi</shipToName>
    <shipToStreet>Via Milano 1</shipToStreet>
    <shipToCity>Torino</shipToCity>
    <shipToState>TO</shipToState>
    <shipToCountryCode>IT</shipToCountryCode>
    <shipToZip>10100</shipToZip>
    <shipToStreet2/>
  </shippingDetails>
</Encrypt>

For more information, check out the Paypal Seller Protection section.

If you want to activate the Paypal Seller Protection you must:

Name max length description
ppSellerProtection 1 Parameter to set the use of a confirmed addresses

 Paypal recurring payments

In this way you can activate recurring payments on paypal. Note that no paymentType is needed.

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>985</amount>
  <shopTransactionId>34az85ord19</shopTransactionId> 
  <payPalBillingAgreementDescription>
    description of the agreement 
  </payPalBillingAgreementDescription>
<Encrypt>

A Buyer will be able to subscribe a Billing Agreement on PayPal website so authorizing the Merchant to debit his/her PayPal account in future transactions.

To use PayPal Reference Transaction it’s necessary to fill the tag PayPalBillingAgreementDescription that can be present or not (in case of a normal PayPal payment it will be left empty or not passed at all).

Name max length description
payPalBillingAgreementDescription 127 Description of the goods, terms and conditions of the billing agreement

The Encryption service, if field payPalBillingAgreementDescription is present and not empty, assumes that the payment method is PayPal (so paymentType field in this case is not mandatory: if present it must be valued PAYPAL).

If this tag is passed to Encryption, Axerve Ecommerce Solutions bypasses the Pagam page in every case (even if other payment methods are enabled for the Merchant).

This tag has to be filled with description of the goods, terms and conditions of the billing agreement.

Encrypt Example: Paysafecard

Paysafecard example:

<Encrypt>
  <shopLogin>90000001</shopLogin>
  <uicCode>242</uicCode><!-- Euro -->
  <amount>0.10</amount>
  <shopTransactionId>MYSHOP_001</shopTransactionId>
  <paymentTypes>
    <paymentType>S2PPSC</paymentType>
  </paymentTypes>
</Encrypt>

Paysafecard does not need mandatory parameters.

You must use S2PPSC as paymentType.

More informations about Paysafecard are in the doc.

Encrypt Example: Przelewy24

Przelewy24 example:

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>100</amount>
  <shopTransactionId>34az85ord19</shopTransactionId>
  <paymentTypes>
    <paymentType>PRZELEWY24</paymentType>
  </paymentTypes>
  <OrderDetails>
    <CustomerDetail>
      <PrimaryEmail>fryderyk.chopin@pianolessons.pl</PrimaryEmail>
    </CustomerDetail>
  </OrderDetails>
</Encrypt>

Przelewy24 does not need mandatory parameters.

You must use S2PPSC as paymentType.

More informations about Przelewy24 are in the doc.

Encrypt Example: Satispay

Satispay example:

<Encrypt>
  <shopLogin>90000001</shopLogin>
  <uicCode>242</uicCode><!-- Euro -->
  <amount>0.10</amount>
  <shopTransactionId>MYSHOP_001</shopTransactionId>
  <paymentTypes>
    <paymentType>SATISPAY</paymentType>
  </paymentTypes>
</Encrypt>

Satispay does not need mandatory parameters.

You must use SATISPAY as paymentType.

More informations about Satispay are in the doc.

Encrypt Example: SEPA

SEPA Direct Debit example:

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>10</amount><!-- mandatory, but not used -->
  <shopTransactionId>34az85ord19</shopTransactionId>
  <paymentTypes>
    <paymentType>SEPADD</paymentType>
  </paymentTypes>
  <OrderDetails>
    <CustomerDetail>
      <FirstName>Stephen</FirstName>
      <Lastname>Hawk</Lastname>
      <PrimaryEmail>stephen@hawk.com</PrimaryEmail>
      <PrimaryPhone>+390123456789</PrimaryPhone>
    </CustomerDetail>
    <BillingAddress>
      <StreetNumber>8</StreetNumber>
      <StreetName>Piazza Martiri della Liberta</StreetName>
      <City>Biella</City>
      <ZipCode>13900</ZipCode>
      <CountryCode>IT</CountryCode>
    </BillingAddress>
  </OrderDetails>
</Encrypt>

To get a pre-approval from SEPA you must specify the paymentType SEPADD.

This payment method requires some other mandatory data, like customer details and billing address.

The amount used in the Encrypt is mandatory, but it is discarded since the Encrypt call is used only to get a pre-approval token.

The effectively charged amount is passed to callPagamS2S after the pre-approval token is received.

If you are using API REST integration, you can find more information in payment/submit.

Encrypt Example: Sofort

SOFORT example:

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>10</amount>
  <shopTransactionId>34az85ord19</shopTransactionId>
  <paymentTypes>
    <paymentType>S2PSOF</paymentType>
  </paymentTypes>
  <OrderDetails>
    <CustomerDetail>
      <FirstName>Albert</FirstName>
      <Lastname>Einstein</Lastname>
      <PrimaryEmail>albert.einstein@princeton.edu</PrimaryEmail>
    </CustomerDetail>
    <BillingAddress>
      <CountryCode>DE</CountryCode>
    </BillingAddress>
  </OrderDetails>
</Encrypt>

Sofort does not need mandatory parameters, but if you send the following parameters, you will jump straight to the SOFORT payment page without authenticating. All these fields are children of OrderDetails.

Name max length description
CustomerDetail.FirstName 65 Customer First Name
CustomerDetail.Lastname 65 Customer Last name
CustomerDetail.PrimaryEmail 100 Customer primary email
BillingAddress.CountryCode 2 Alpha-2 code. For example, use US for USA

Encrypt Example: UnionPay

UnionPay example:

<Encrypt>
  <shopLogin>90000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>10</amount>
  <shopTransactionId>SP_S2P_UnionPay_001</shopTransactionId>
  <paymentTypes>
    <paymentType>S2PUNI</paymentType>
  </paymentTypes>
  <OrderDetails>
    <CustomerDetail>
      <PrimaryPhone>+85211112222</PrimaryPhone>
      <PrimaryEmail>yangchenning@physics.cn</PrimaryEmail>
    </CustomerDetail>
  </OrderDetails>
</Encrypt>

Unipay does not need mandatory parameters.

You must use S2PUNI as paymentType.

However, if you send the PrimaryEmail and PrimaryPhone fields in the OrderDetails tag, you will jump straight to the UnionPay payment page; otherwise, an intermediary page asking for the email address is showed.

Encrypt Example: WebMoney

WebMoney example:

<Encrypt>
  <shopLogin>90000001</shopLogin>
  <uicCode>242</uicCode><!-- Euro -->
  <amount>0.10</amount>
  <shopTransactionId>MYSHOP_001</shopTransactionId>
  <paymentTypes>
    <paymentType>S2PWMO</paymentType>
  </paymentTypes>
</Encrypt>

WebMoney does not need mandatory parameters.

You must use S2PWMO as paymentType.

More informations about WebMoney are in the doc.

Encrypt Example: WeChat

WeChat example:

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>144</uicCode>
  <amount>100</amount>
  <shopTransactionId>34az85ord19</shopTransactionId>
  <paymentTypes>
    <paymentType>WECHAT</paymentType>
  </paymentTypes>
  <OrderDetails>
    <CustomerDetail>
      <PrimaryEmail>bruce.lee@jetkunedo.com</PrimaryEmail>
    </CustomerDetail>
  </OrderDetails>
</Encrypt>

WeChat does not need mandatory parameters.

You must use WECHAT as paymentType.

More informations about WeChat are in the doc.

Encrypt Example: Yandex

Yandex Example:

<Encrypt>
  <shopLogin>9000001</shopLogin>
  <uicCode>242</uicCode>
  <amount>10</amount>
  <shopTransactionId>34az85ord19</shopTransactionId>
  <paymentTypes>
    <paymentType>S2PYAN</paymentType>
  </paymentTypes>
  <OrderDetails>
    <CustomerDetail>
      <PrimaryEmail>alfred.nobel@dynamite.se</PrimaryEmail>
    </CustomerDetail>
  </OrderDetails>
</Encrypt>

Yandex does not need mandatory parameters; but if you send CustomerDetail.PrimaryEmail in the OrderDetails tag you can have a frictionless call directly to the first screen of Yandex where authentication data are asked.

Name max length description
CustomerDetail.PrimaryEmail 100 Customer primary email

This mean that no others values are asked to the buyer; if this field is not sent with the payment, a page will ask the necessary fields.

REST APIs

Welcome to Axerve Ecommerce Solutions REST APIs. With these APIs you’ll be able to perform a big set of operations.

URLs, endpoints and versions

Axerve Ecommerce Solutions provides two endpoints:

URL
Sandbox https://sandbox.gestpay.net/api/{version}/{object}/{method}
Production https://ecomms2s.sella.it/api/{version}/{object}/{method}

Methods are versioned, for example v1.

Methods marked with sandbox are available in sandbox only.

Handling Responses & Errors

Success response:
200 OK

{
  "error":{
    "code":"0",
    "description":"request correctly processed"
  },
  "payload":{
    //Here you'll find the response 
    ...
  }
}

Client Error
400 Bad Request

{
   "error":{
      "code":"1105",
      "description":"Invalid parameter value"
   },
   "payload":{}
}

Unauthorized request:
403 Forbidden Access

{
  "error": {
    "code": "1166",
    "description": "Invalid ApiKey"
  },
  "payload": {}
}

General error:
500 System Error

{
  "error": {
    "code": "9999",
    "description": "Technical error"
  },
  "payload": {}
}

Axerve Ecommerce Solutions uses HTTP status codes to indicate the result of an operations.

Axerve Ecommerce Solutions uses an HTTP status code that indicates the success (2xx) or failure (4xx, 5xx) of the request.

Along with the status code, Axerve Ecommerce Solutions sends a json in the body of the response, to better explain the response.

The error code is one of the error code list.

The error description contains the error explanation in common language.

The payload is eventually filled with the response, in case of success.

Payment token

paymentToken is generated during the creation of a new payment with payment/create and it’s unique for every transaction. It can be insert in the headers for authenticate call for that payment.

The token is valid util the payment is not authorized (before the payment/submit).

Check API

With the Check REST APIs you’ll be able to syntactically check credit card numbers, emails, dates and CVV.

POST check/cvv

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/check/cvv/

Production URL:

POST https://ecomms2s.sella.it/api/v1/check/cvv/

Request body:

{
    "shopLogin":"",
    "creditcard":{
        "cvv":""
    }
}

Provides a formal validity check of the CVV.

Request

Headers:

To receive a valid response from Axerve Ecommerce Solutions you must use one of these headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.
paymentToken {paymentToken} A payment token received during the payment process

request body details:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.
creditcard.cvv A string composed of digits.

Response

Success response example:
200 OK

{
  "error":{  
    "code":"0",
    "description":"request correctly processed"
  },
  "payload": {
    "result": "OK"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
result OK of KO

POST check/email

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/check/email/

Production URL:

POST https://ecomms2s.sella.it/api/v1/check/email/

Request body:

{
    "shopLogin":"",
    "email":""
}

Provides a formal validity check of the email address.

Request

Headers:

To receive a valid response from Axerve Ecommerce Solutions you must use one of these headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.
paymentToken {paymentToken} A payment token received during the payment process

request body details:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.
email A string containing the email to validate.

Response

Success response example:
200 OK

{
  "error":{  
    "code":"0",
    "description":"request correctly processed"
  },
  "payload": {
    "result": "OK"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
result OK of KO

POST check/expirydate

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/check/expirydate/

Production URL:

POST https://ecomms2s.sella.it/api/v1/check/expirydate/

Request body:

{
  "shopLogin":"",
  "creditcard":{
    "expMonth":"",
    "expYear":""
  }
}

Provides a formal validity check of the Exipry Date.

Request

Headers:

To receive a valid response from Axerve Ecommerce Solutions you must use one of these headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.
paymentToken {paymentToken} A payment token received during the payment process

request body details:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.
creditcard.expMonth The credit card exiry month
creditcard.expYear The credit card exiry year

Response

Success response example:
200 OK

{
  "error":{  
    "code":"0",
    "description":"request correctly processed"
  },
  "payload": {
    "result": "OK"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
result OK of KO

POST check/pan

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/check/pan/

Production URL:

POST https://ecomms2s.sella.it/api/v1/check/pan/

Request body:

{
  "shopLogin":"",
  "creditcard": {
    "number": ""
  }
}

Provides a check of the digits of the PAN.

Request

Headers:

To receive a valid response from Axerve Ecommerce Solutions you must use one of these headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.
paymentToken {paymentToken} A payment token received during the payment process

request body details:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.
creditcard.number The credit card number to check.

Response

Success response example:
200 OK

{
  "error":{  
    "code":"0",
    "description":"request correctly processed"
  },
  "payload":{
    "checkDigit":"{OK/KO}",
    "company":"",
    "logo":{
      "large":"{url_logo_desktop_lage_PNG}",
      "mobile":"{url_logo_mobile_lage_PNG}",
      "vector":"{url_logo_svg}"
    }
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
checkDigit OK of KO
company the card issuer
logo contains URLs for images in different formats: large, mobile, vector.

POST check/DCC

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/check/DCC/

Production URL:

POST https://ecomms2s.sella.it/api/v1/check/DCC/

Request body:

{
  "shopLogin" : "",
  "creditcard":{
      "number":""
  },
  "languageId":""
}

Checks if the card is elegible for Dynamic Currency Conversion.

Request

Header:

Header Value Description
paymentToken {paymentToken} A payment token received during the payment process

request body details:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.
creditcard.number The credit card number.
languageId A language ID.

Response

Success response example:
200 OK

{  
  "DCC":{  
    "eligible":"TRUE",
    "currency":"PLN",
    "amount":"100",
    "disclaimer":"https://{domain}/DCC/disclaimer.aspx?transkey=dsajklq31223",
    "exchangeRate":"2%",
    "source":""
  },
  "paymentID":"111213213"
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
eligible TRUE or FALSE
currency The current currency of the card
amount the amount of the transaction
disclaimer A URL that points to a disclaimer, explaining DCC.
exchangeRate a percentage indicating the commission on the money exchange
paymentId the payment ID
source In this field you’ll find the source from whom information is taken, like exchange rates, etc.

POST check/creditCard

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/check/creditCard/

Production URL:

POST https://ecomms2s.sella.it/api/v1/check/creditCard/

Request body:

{
  "shopLogin" : "",
  "shopTransactionID" : "",
  "withAuth":"",
  "creditcard":{
    "number":"",
    "token":"",
    "expMonth":"",
    "expYear":"",
    "CVV":""
  }
}

Provides a formal validity check of the credit card.

Request

Headers:

To receive a valid response from Axerve Ecommerce Solutions you must use one of these headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

request body details:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.
shopTransactionID The shop transaction ID.
withAuth TRUE or FALSE (default). Tries to authorize the card.
creditcard.number The number of the credit card.
creditcard.token If you have a token, Axerve Ecommerce Solutions can check it for validity.
creditcard.expMonth The expiry month.
creditcard.expYear The expiry year.
creditcard.CVV The CVV.

Response

Success response example:
200 OK

{  
  "transactionType":"CreditCard",
  "transactionResult":"OK",
  "authorizationResult":"OK",
  "authorizationErrorCode":"0",
  "authorizationCodeDescription":"Transaction correctly processed",
  "country":"ITALIA",
  "countryCode":"380",
  "cvv":"OK",
  "cvvDescription":"CVV VALID",
  "issuerCountry":"ITALIA",
  "issuerCountryCode:":"380",
  "company":"MASTERCARD",
  "companyCode":"3",
  "commercial":"N",
  "productDescription":"Standard MasterCard® Card",
  "productType":"Credit",
  "checkDigit":"OK",
  "checkDigitDescription":"CheckDigit VALID",
  "expiryDate":"OK",
  "expiryDateDescription":"DATE VALID",
  "3DS":"Y",
  "3DSDescription":"ENROLLED",
  "prepaid":"N"
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
transactionType CreditCard
transactionResult OK or KO
authorizationResult authorization result. It can be OK or KO or NULL
authorizationErrorCode authorisation error code if an error occurred
authorizationCodeDescription code description
country nationality of the card
countryCode nationality code of the card
cvv result of the check CVV. It can be OK or KO or NULL
cvvDescription description of CVV check results
issuerCountry nationality of the card issuer
issuerCountryCode nationality code of the card issuer
company Description of the Card company
companyCode Code of the Company
commercial Flag that indicates if the Card is commercial or not. Y or N
productDescription Description of the product linked to the card
productType type of the product: Credit or Debit
checkDigit OK or KO, acording to the check digit of the card
checkDigitDescription description of the check digit response
expiryDate OK or KO, acording to the check date of the card
expiryDateDescription description of the check date response
3DS 3D Secure enabled:
  • Y enabled
  • N not enabled
  • E error: could not contact the credit card company
  • U could not verify
3DSDescription enrolment description
prepaid indicates if the card is prepaid of not (Y, N, or empty)

POST check/token

Merchants can use this method to check the existence of a specific token value. If the token exists, the method provides all the token details (expiration, card details, card art if applicable, etc…)

Request details

Request example:

{
  "shopLogin": "",
  "token": ""
}

Headers:

Header Value Description
Authorization  apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

Request body details:

Name Description Data Type max length
shopLogin  shopLogin value string 30
token String containing the token value returned by Axerve Ecommerce Solutions. string 25

 Response details

Response example:

{
  "error": {
    "code": "0",
    "description": "request correctly processed"
  },
  "payload": {
    "tokenValue": "",
    "tokenExpiryMonth": "",
    "tokenExpiryYear": "",
    "tokenProvider": "",
    "cardDetails": {
      "cardSuffix": "",
      "cardExpiryMonth": "",
      "cardExpiryYear": "",
      "cardHolderName": ""
    },
    "cardAssets": {
      "cardArt": {
        "type": "",
        "mediaContents": "",
        "height": "",
        "width": ""
      },
      "brandLogo": {
        "type": "",
        "mediaContents": "",
        "height": "",
        "width": ""
      }
    }
  }
}

payload details:

Name Description
tokenValue String containing the token value returned by Axerve Ecommerce Solutions.
tokenExpiryMonth The token expiration month.
tokenExpiryYear The token expiration year.
tokenProvider The entity providing the token. It can be: AXERVE, VISA, MASTERCARD, PAYPAL, AMAZON, APPLE, SEPADD.
cardDetails.cardSuffix The last 4 digit of the card PAN.
cardDetails.cardExpiryMonth The card expiry month.
cardDetails.cardExpiryYear The card expiry Year.
cardDetails.cardHolderName The cardholder name.
cardAssets.cardArt.type The file format of the card art (card image)
cardAssets.cardArt.mediaContents The card image (Base64)
cardAssets.cardArt.height The card art (card image) height
cardAssets.cardArt.width The card art (card image) width
cardAssets.brandLogo.type The file format of the brand logo (e.g. Visa, Mastercard, etc..)
cardAssets.brandLogo.mediaContents The brand logo (e.g. Visa, Mastercard, etc..) image (Base64)
cardAssets.brandLogo.height The brand logo (e.g. Visa, Mastercard, etc..) height
cardAssets.brandLogo.width The brand logo (e.g. Visa, Mastercard, etc..) width

Dashboard API

With the dashboard REST APIs you’ll be able to query Axerve Ecommerce Solutions for dashboard services, like searching for transactions.

POST dashboard/search

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/dashboard/search

Production URL:

POST https://ecomms2s.sella.it/api/v1/dashboard/search

Example search:

{
    "shopLogin": "",
    "search": {
        "name": "",
        "searchID": ""
    },
    "dateFrom": "",
    "dateTo": "",
    "authorizedAmount": {
        "from": "",
        "to": ""
    },
    "capturedAmount": {
        "from": "",
        "to": ""
    },
    "lastNDays": "",
    "invoiceID": "",
    "currency": [],
    "bankTransactionID": "",
    "shopTransactionID": "",
    "authorizationCode": "",
    "transactonErrorCode": "",
    "paymentID": "",
    "authorizationResult": [],
    "tdLevel": "",
    "event": {
        "type": "",
        "from": "",
        "to": "",
        "lastNDays": "",
        "includeToday": ""
    },
    "creditDate": {
        "from": "",
        "to": "",
        "lastNDays": "",
        "includeToday": ""
    },
    "debitDate": {
        "from": "",
        "to": "",
        "lastNDays": "",
        "includeToday": ""
    },
    "chargeback": {
        "type": "",
        "from": "",
        "to": "",
        "lastNDays": "",
        "includeToday": ""
    },
    "transactionState": [],
    "paymentMethod": [
        {
            "paymentType": "",
            "name": [""]
        }
    ],
    "riskAlert": "",
    "customFields": [
        {
            "customName": "customvalue"
        }
    ],
    "rangeResults": ""
}

Queries Axerve Ecommerce Solutions for transactions of the past, filtering by many fields.

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

Body data:

(Fields in bold are mandatory)

Field Description Example
shopLogin Your shop login GESPAY12345
search.name The name of a saved search. today_transactions
search.searchID The searchID of a saved search. 00001
dateFrom Search start date 01/01/2017
dateTo Search end date 31/12/2017
authorizedAmount.from Search for transactions that have an authorized amount greater than authorizedAmount.from. 100.01
authorizedAmount.to Search for transactions that have an authorized amount lower than authorizedAmount.to. 300.00
capturedAmount.from Search for transactions that have a captured amount greater than capturedAmount.from. 15.67
capturedAmount.to Search for transactions that have a captured amount lower than capturedAmount.to. 100
lastNDays retrieve transactions for the last N days 3
invoiceID an invoice ID to search 00000353
currency an array containing the values to be checked against the transaction. They must be a valid ISO code. [EUR, USD]
bankTransactionID An ID assigned by the bank. 33
shopTransactionID The shopTransactionID is the ID assigned by the shop. my_shop_id_42
authorizationCode The authorization code is a code released by the payment circuit. 1123454
transactionErrorCode The transaction error code 74
paymentID Assigned by Axerve Ecommerce Solutions, identifies the payment 12365344752
authorizationResult select transactions whose authorizationResult is contained in the array. UNSUBMITTED, WAITING, PENDING (or XX), APPROVED (or OK), DECLINED (or KO)
tdLevel 3dSecure level HALF, FULL
event.type One of the event types MOV
event.from Search for events occurred after this date 01/01/2018
event.to Search for events occurred before this date 31/12/2018
event.lastNDays Search the last N days 7
event.includeToday True or false True
creditDate Allows to search by credit date. Works very similarly to event seen before.
debitDate Allows to search by debit date. Works very similarly to event seen before.
chargeBack Allows to search by disputes. Works very similarly to event seen before.
chargeBack.type You can search by a chargeback type, a value in the ALL, OPEN, CLOSE, CLOSE WITH CHARGE set. ALL
transactionState the last state of the transaction. See event types for details MOV
paymentMethod.paymentType the paymentType for this transaction e.g. CREDITCARD, PAYPAL
paymentMethod.name The common name of the payment method VISA BVB
riskAlert use true to select transactions associated with a high risk true or false
customFields.customName You can even search by a custom parameter and its value. Just put the customName set as the key and use the value as the search field. { "MY_CUSTOM_PARAM" : "customValue123" }
rangeResults Specify which records you want to read. The first number is the starting point, the last number is the last element. 11/20

Response

Success response:
200 OK

{
    "error": {
        "code": "0",
        "description": "request correctly processed"
    },
    "payload": {
        "nResults": "30",
        "rangeResults": "1/5",
        "payments": [
            {
                "Date": "26/02/2018 12:22:29",
                "transactionResult": "KO",
                "transactionState": "AUT",
                "bankTransactionID": "2304",
                "shopTransactionID": "Cryptest2602201811",
                "authorizationCode": "",
                "transactionErrorCode": "",
                "transactionErrorDescription": "",
                "paymentID": "22131121123",
                "amount": "0.10",
                "currency": "EUR",
                "paymentMethod": {
                    "paymentType": "CREDITCARD",
                    "name": "VISA VBV",
                    "logo": {
                        "large": "https://{domain}/logos/VisaVbv_Large.png",
                        "mobile": "https://{domain}/logos/VisaVbv_mobile.png",
                        "vector": "https://{domain}/logos/VisaVbv.svg"
                    }
                },
                "riskAlert": "",
                "disputeState": {
                    "status": "",
                    "chargeback": ""
                },
                "tdLevel": "HALF",
                "fraudAlert": "",
                "guaranteePaymentResult": ""
            },
            {
                "Date": "22/02/2018 10:20:09",
                "transactionResult": "OK",
                "transactionState": "AUT",
                "bankTransactionID": "2303",
                "shopTransactionID": "Cryptest2202201811",
                "authorizationCode": "1123454",
                "amount": "0.10",
                "currency": "EUR",
                "paymentMethod": {
                    "paymentType": "CREDITCARD",
                    "name": "VISA VBV",
                    "logo": {
                        "large": "https://{domain}/logos/VisaVbv_Large.png",
                        "mobile": "https://{domain}/logos/VisaVbv_mobile.png",
                        "vector": "https://{domain}/logos/VisaVbv.svg"
                    }
                },
                "riskAlert": "Y",
                "disputeState": {
                    "status": "",
                    "chargeback": ""
                },
                "tdLevel": "FULL",
                "fraudAlert": "",
                "guaranteePaymentResult": ""
            }
            //...
        ]
    }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

In case of success the response is paginated. Use the rangeResults property to retrieve more results.

error details:

Field Description
error.code 0 means no error, otherwise check the error codes and error.description to debug the problem.
error.description If error.code != 0 will contain a description of the error.

payload details:

Field Description
nResults the number items returned by the search.
rangeResults the range of items returned (of all items)
payments an array of payment objects, see the next section for details.

payments details:

Field Description
Date the transaction date
transactionResult OK or KO
transactionState the state of the transaction.
bankTransactionID a transaction identifier assigned by the bank, guaranteed to be unique.
shopTransactionID a transaction identifier assigned by the merchant.
authorizationCode the authorization code given by the circuit
transactionErrorCode The transaction error code
transactionErrorDescription The transaction error description in common language
paymentID the payment ID
amount the amount of the transaction
currency the ISO currency for the transaction
paymentMethod.paymentType The payment type.
paymentMethod.name The circuit name
paymentMethod.logo a logo of the payment method, in several resolutions.
riskAlert if the transaction is suspicious, riskAlert is marked with Y.
disputeState.status Showm for transactions that have been disputed. Possible values: Open, Closed
disputeState.chargeback Shown for transactions that have resulted in a chargeback. Possible values: True, False, Null
tdLevel Level of authentication for 3D-Secure transactions. FULL or HALF
fraudAlert True or False if the transaction is suspicious.
guaranteedPaymentResult If you’re using Axerve Guaranteed Payment, you’ll receive the fraud risk associated with the transaction.

POST dashboard/export/file

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/dashboard/export/file

Production URL:

POST https://ecomms2s.sella.it/api/v1/dashboard/export/file

Request Body:

{
  "shopLogin":"",
  "searchID":"",
  "fileType":"",
  "template":"",
  "email":"",
  "prefix":"",
  "password":""
}

Creates an export file based on the given template name and returns a temporary URL to download it.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

Request Body:

(Fields in bold are mandatory)

Parameter Description
shopLogin your Shop Login, e.g. GESPAY12345 or XX12345678
searchID The Search ID
fileType The file type extension, one of txt, xls, csv
template The template to use, referenced by name
email The email where the file output will be sent
prefix This value is put before the filename generated automatically by Axerve Ecommerce Solutions.
password If you want to setup a password for the zip file, fill this field with a password value

Response

Success Response:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{
    "result":"OK",
    "href":"https://ecomm.sella.it/backoffice/export/12342141asadfsa.txt"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
result OK ok KO
href the url where the file can be downloaded

POST dashboard/export/batch

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/dashboard/export/batch/

Production URL:

POST https://ecomms2s.sella.it/api/v1/dashboard/export/batch/

Example POST for a NEW batch

{
  "shopLogin":"myShopLogin",
  "name":"Batch No 1",
  "ID":"",
  "search":{
    "ID":"11122121"
  },
  "fileType":"xls",
  "template":{
    "ID":"362"
  },
  "recipient":{
    "email":{
      "value":"myname@mydomain.co.in",
      "enabled":"true"
    },
    "ftp":{
      "value":"",
      "enabled":""
    }
  },
  "frequency":{
    "ID":"1S"
  },
  "level": [
    {"ID": ""}
    {"ID": ""}
  ],
  "prefix":"Su_",
  "password":"myPWD"
}

Creates a new export batch or modify an existing one.

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

Body details:

(Fields in bold are mandatory)

Field Description
shopLogin your Shop Login, e.g. GESPAY12345 or XX12345678
name The batch name
ID If empty, creates a new batch. Otherwise it will update a previous one. Mandatory on update.
sarch.ID The Search ID that originates the batch.
template.ID The Template ID used by the export.
fileType The output file type: txt, xls, csv
recipient.email.value The email where the batch output will be sent
recipient.email.enabled True if the email should be sent to this address.
recipient.ftp.value The FTP address to upload the file
recipient.ftp.enabled True if the batch should be uploaded via ftp.
frequency.ID Determines the start day of the batch interval.See the related table.
prefix This value is put before the filename generated automatically by Axerve Ecommerce Solutions.
level Event level
  • A: TRANSACTION
  • E: ALL EVENTS
  • AUT: AUT
  • CAN: CAN
  • MOV: MOV
  • PRE: PRE
  • STO: STO

At least one of recipient.email.enabled and recipient.ftp.enabled must be True.

Response

Success Response:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{
    "result":"OK",
    "batch":{
      "name":"Batch No 1",
      "batchID":"1111"
    }
}
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
result OK ok KO
batch.name The name of the batch
batch.id The batch ID

GET dasboard/export/batch

Sandbox URL:

GET https://sandbox.gestpay.net/api/v1/dashboard/export/batch/{shopLogin}/

Production URL:

GET https://ecomms2s.sella.it/api/v1/dashboard/export/batch/{shopLogin}/

This endpoint will return the list of batches saved in Axerve Ecommerce Solutions.

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

URL params:

(Fields in bold are mandatory)

Parameter Description
shopLogin your Shop Login, e.g. GESPAY12345 or XX12345678

Response

Success response:
200 OK

{  
  "error":{  
    "code":"0",
    "description":"request correctly processed"
  },
  "payload": {
    "batch":[
      {
        "name":"Batch No 1",
        "ID":"1111",
        "search":{
          "ID":"127617",
          "name":"MAESTRO"
        },
        "template":{
          "ID":"1345",
          "name":"My Template 1"
        },
        "fileType":"xls",
        "recipient":{
          "email":{
            "value":"myname@mydomain.co.in",
            "enabled":"true"
          },
          "ftp":{
            "value":"ftp://ftp.mydomain.co.in",
            "enabled":"false"
          }
        },
        "frequency":{
          "ID":"1S",
          "name":"Sunday"
        },
        "prefix":"Su_",
        "level": [
          {"ID": "A", "name": "TRANSACTION"},
          {"ID": "E", "name": "ALL EVENTS"}
        ]
      },
      {
        "name":"Batch No 2",
        "ID":"3112",
        "search":{
          "ID":"127618",
          "name":"MAESTRO SC"
        },
        "template":{
          "ID":"1345",
          "name":"My Template 1"
        },
        "fileType":"xls",
        "recipient":{
          "email":{
            "value":"",
            "enabled":""
          },
          "ftp":{
            "value":"ftp://ftp.mydomain.co.in",
            "enabled":"true"
          }
        },
        "frequency":{
          "ID":"2S",
          "name":"Monday"
        },
        "prefix":"Monthly1st",
        "level": [
          {"ID": "A", "name": "TRANSACTION"},
          {"ID": "E", "name": "ALL EVENTS"}
        ]
      }
    ]
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

payload details:

Field Description
batch An array of batches, see next table.

batch details:

Field Description
name The batch name
ID An ID assigned by Axerve Ecommerce Solutions
sarch.ID The Search ID that originates the batch.
sarch.name The Search Name that originates the batch.
template.ID The Template ID used by the export.
template.name The Template Name used by the export.
fileType The output file type.
recipient.email.value The email where the batch output will be sent
recipient.email.enabled True if the email should be sent to this address.
recipient.ftp.value The FTP address to upload the file
recipient.ftp.enabled True if the batch should be uploaded via ftp.
frequency.ID Determines the start day of the batch interval. See the related table.
frequency.name Displays a description based on the frequency value. See the related table.
prefix This value is put before the filename generated automatically by Axerve Ecommerce Solutions.
level Event level
  • A: TRANSACTION
  • E: ALL EVENTS
  • AUT: AUT
  • CAN: CAN
  • MOV: MOV
  • PRE: PRE
  • STO: STO

DELETE dashboard/export/batch

Sandbox URL:

DELETE https://sandbox.gestpay.net/api/v1/dashboard/export/batch/{shopLogin}/{batchID}

Production URL:

DELETE https://ecomms2s.sella.it/api/v1/dashboard/export/batch/{shopLogin}/{batchID}

Deletes a batch.

Request

Specify in the URL the shopLogin and the batchID.

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

URL params:

(Fields in bold are mandatory)

Parameter Description
shopLogin your Shop Login, e.g. GESPAY12345 or XX12345678
batchID the batch you want to delete

Response

Success response payload:
200 OK

{
  "result":"OK",
  "batch":{
    "name":"Batch No 1",
    "batchID":"1111"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Field Detail
result the result (OK/KO) of the operation
batch.name The deleted batch name
batch.batchID The deleted batch ID

GET dashboard/statistic

Sandbox URL:

GET https://sandbox.gestpay.net/api/v1/dashboard/statistic/{shopLogin}

Returns a bunch of statistics for your shop.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

URL parameters:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.

Response

Success response example:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{
    "statistics":[
      {
        "currency":"EUR",
        "from":"04/04/2018",
        "to":"10/04/2018",
        "elapsed":"5D",
        "totalNumber":"489",
        "totalAmount":"82.118,61",
        "transactions":{
          "authorized":{
            "number":"455",
            "amount":"80.716,41",
          },
          "suspended":{
            "number":"442",
            "amount":"80.543,84"
          },
          "deleted":{
            "number":"0",
            "amount":"0,00"
          },
          "captured":{
            "number":"12",
            "amount":"66,71"
          },
          "reversed":{
            "number":"1",
            "amount":"105,86"
          },
          "declined":{
            "number":"34",
            "amount":"1.402,20"
          }
        },
        "paymentTypes":[
          {
            "paymentType":"CREDITCARD",
            "company":"MASTERCARD SECURECODE",
            "number":"2",
            "amount":"42,34"
          },
          {
            "paymentType":"CREDITCARD",
            "company":"MASTERCARD",
            "number":"1",
            "amount":"1,00"
          },
          {
            "paymentType":"CREDITCARD",
            "company":"VISA",
            "number":"20",
            "amount":"134,11"
          },
          {
            "paymentType":"FidelityCARD",
            "company":"",
            "number":"9",
            "amount":"0,09"
          },
          {
            "paymentType":"MYBANK",
            "company":"",
            "number":"4",
            "amount":"12,64"
          },
          {
            "paymentType":"S2PALI",
            "company":"",
            "number":"390",
            "amount":"68.521,46"
          },
          {
            "paymentType":"S2PIDE",
            "company":"",
            "number":"3",
            "amount":"227,03"
          },
          {
            "paymentType":"KLARNA",
            "company":"",
            "number":"7",
            "amount":"1.568.50"
          },
          {
            "paymentType":"S2PMUL",
            "company":"",
            "number":"10",
            "amount":"258,11"
          },
          {
            "paymentType":"S2PSOF",
            "company":"",
            "number":"22",
            "amount":"7.311,51"
          },
          {
            "paymentType":"S2PUNI",
            "company":"",
            "number":"21",
            "amount":"7.301,36"
          }
        ]
      }
    ]
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

payload.statistics can contain zero or more items, each referring to a temporal frame.

For every statistic in payload.statistics:

Field Description
currency ISO currency code
from the starting date for these statistics
to the end date
elapsed the amount of days elapsed
totalNumber total number of transactions
totalAmount the total amount of authorized, suspended, deleted, captured, reversed and declined transactions.
transactions An object that contains the number, along with the amount, of transactions authorized, suspended, deleted, captured, reversed and declined. See the table below.
paymentTypes a fine-grained statistic for every payment type. See the next table for details.
transactions details
Field Description
authorized Statistics about authorized transactions.
suspended Statistics about suspended transactions.
deleted Statistics about deleted transactions.
captured Statistics about captured transactions.
reversed Statistics about reversed transactions.
declined Statistics about declined transactions.

For each category we have:

Field Description
number The number of transactions for this category.
amount The sum of all amounts for this category.
paymentTypes details

For every payment type, Axerve Ecommerce Solutions returns an object containing the number of transactions and the amount.

Field Description
paymentType The payment type.
company A company involved in this payment type. For example, if the payment type is CREDITCARD, the company is VISA, MASTERCARD, etc.
number the number of transactions for this payment type and company.
amount The amount collected for this payment type and company.

POST dashboard/export/template

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/dashboard/export/template/

Production URL:

POST https://ecomms2s.sella.it/api/v1/dashboard/export/template/

Example request body:

{
  "shopLogin":"myshoplogin",
  "templateId":"",
  "description":"New template 1",
  "default":"True",
  "columns":[
    "Email compratore",
    "ID Banca",
    "Stato",
    "Cardnumber",
    ...
  ]
}

Creates or modifies a template. If the templateId is present, the template is updated.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

Body parameters:

(Fields in bold are mandatory)

Field Description
shopLogin The shop identifier.
template.templateId Leave empty if you’re creating a new template. Otherwise, you must use an existing templateId to update one.
template.description A description of the template in common language
template.default True or False
template.columns an array of strings, representing the name of the properties that compose a transaction.

Response

Success response example:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{
    "result":"OK",
    "template":[
      {
        "templateId":"121212212",
        "description":"New template 1",
        "default":"True",
        "columns":[
          "date",
          "shopTransactionID",
          "bankTransactionID",
          "transactionResult",
          "authorizedAmount",
          "capturedAmount",
          "paymentID",
          "currency"
        ]
      }
    ]
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
result OK or KO
template An array containing one or more templates.
template.templateID The template ID of the template created or updated
template.description A description of the template in common language
template.default True or False
template.columns an array of strings, representing the name of the properties that compose a transaction.

GET dashboard/export/template

Sandbox URL:

GET https://sandbox.gestpay.net/api/v1/dashboard/export/template/{shopLogin}

Production URL:

GET https://ecomms2s.sella.it/api/v1/dashboard/export/template/{shopLogin}

Returns a list of all templates created for your shopLogin.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

URL parameters:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.

Response

Success response example:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{
    "template":[
      {
        "templateId":"121212212",
        "description":"New template 1",
        "creationDate":"12/04/2018 11:23",
        "default":"True",
        "columns":[
          "date",
          "shopTransactionID",
          "bankTransactionID",
          "transactionResult",
          "capturedAmount",
          "paymentID",
          "currency",
          ...
        ]
      },
      {
        "templateId":"121214442",
        "description":"Exporting Mov",
        "creationDate":"12/04/2018 11:23",
        "default":"False",
        "columns":[
          "date",
          "shopTransactionID",
          "bankTransactionID",
          "transactionResult",
          "capturedAmount",
          "paymentID",
          "currency",
          ...
        ]
      }
    ]
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
template An array containing one or more templates.
template.templateId The template ID.
template.description A description of the template in common language
template.creationDate The creation date for this template
template.default True or False
template.columns an array of strings, representing the name of the properties that compose a transaction.

DELETE dashboard/export/template

Sandbox URL:

DELETE https://sandbox.gestpay.net/api/v1/dashboard/export/template/{shopLogin}/{templateID}

Production URL:

DELETE https://ecomms2s.sella.it/api/v1/dashboard/export/template/{shopLogin}/{templateID}

Deletes a template.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

URL parameters:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.
templateID The template you want to delete.

Response

Success response example:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{
    "result":"OK",
    "template":{
      "templateId":"121212212",
      "description":"New template 1"
    }
  } 
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
result OK or KO
template.templateId The deleted template ID.
template.description The deleted template description.

GET dasboard/search/saved

Sandbox URL:

GET https://sandbox.gestpay.net/api/v1/dashboard/search/saved/{shopLogin}/

Production URL:

GET https://ecomms2s.sella.it/api/v1/dashboard/search/saved/{shopLogin}/

Returns the list of saved searches in Axerve Ecommerce Solutions.

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

URL params:

(Fields in bold are mandatory)

Parameter Description
shopLogin your Shop Login, e.g. GESPAY12345 or XX12345678

Response

Success response:
200 OK

{
  "search":[
    {
      "save":{
        "name":"",
        "searchID":""
      },
      "authorizedAmount":{
        "from":"",
        "to":""
      },
      "capturedAmount":{
        "from":"",
        "to":""
      },
      "currency":[

      ],
      "bankTransactionID":"",
      "shopTransactionID":"",
      "authorizationCode":"",
      "transactionErrorCode":"",
      "transactionErrorDescription":"",
      "paymentID":"",
      "authorizationResult":"",
      "tdLevel":"",
      "event": {
        "type":"",
        "from":"",
        "to":"",
        "lastNDays":"",
        "includeToday":""
      },
        "creditDate": {
            "from": "",
            "to": "",
            "lastNDays": "",
            "includeToday": ""
        },
        "debitDate": {
            "from": "",
            "to": "",
            "lastNDays": "",
            "includeToday": ""
        },
        "chargeback": {
            "type": "",
            "from": "",
            "to": "",
            "lastNDays": "",
            "includeToday": ""
        },
      "transactionState":[],
      "paymentMethod":[{       
        "paymentType":"",
        "name":[]
      }],
      "riskAlert":"",
      "customFields":[
        {
          "customName":"customvalue"
        }
      ],
      "invoiceID":""
    }
  ]
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

payload details:

Field Description
search An array of search objects, see next table.

search details:

Field Description
save.name The search name.
save.searchID The ID assigned by Axerve Ecommerce Solutions for this search.
authorizedAmount.from the from amount range. If 10, only authorized amounts greater than 10 are returned.
authorizedAmount.to The to amount range. If 20, only authorized amounts lower than 20 are returned.
capturedAmount.from the from amount range. If 10, only captured amounts greater than 10 are returned.
capturedAmount.to The to amount range. If 20, only captured amounts lower than 20 are returned.
currency An array of valid currencies to search for.
bankTransactionID the bank transaction ID.
shopTransactionID The shop transaction ID.
authorizationCode The authorization code released by the payment circuits.
transactionErrorCode A transaction error code.
transactionErrorDescription A transaction error description, in common language.
paymentID The payment ID
authorizationResult The authorization result.
tdLevel 3D-Secure level
event Accepted events. See below.
creditDate Allows to search by credit date. Works very similarly to event seen before.
debitDate Allows to search by debit date.
chargeBack Allows to search by disputes. Works very similarly to event seen before.
chargeBack.type You can search by a chargeback type, a value in the ALL, OPEN, CLOSE, CLOSE WITH CHARGE set.
transactionState An array of transaction states. Follow the link for a detailed explanation of transaction statuses.
paymentMethod an array containing payment types and payment names.
riskAlert true to select transactions associated with a high risk
customFields.customName You can even search by a custom parameter and its value. Just put the customName set as the key and use the value as the search field.
invoiceID the invoice ID.

search.event details:

Name Description
type One of the events defined in Event Types.
from The from date for the specified event type.
to The to date for the specified event type.
lastNDays an integer defining if this event should be searched in the last N days. Alternative to from and to.
includeToday If true, it includes today in the search.

POST dashboard/search/saved

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/dashboard/search/saved/

Production URL:

POST https://ecomms2s.sella.it/api/v1/dashboard/search/saved/

Example request body:

{  
  "shopLogin":"",
  "authorizedAmount":{  
    "from":"",
    "to":""
  },
  "capturedAmount":{  
    "from":"",
    "to":""
  },
  "currency":[  

  ],
  "bankTransactionID":"",
  "shopTransactionID":"",
  "authorizationCode":"",
  "transactionErrorCode":"",
  "paymentID":"",
  "authorizationResult":[],
  "tdLevel":"",
  "event": {  
    "type":"",
    "from":"",
    "to":"",
    "lastNDays":"",
    "includeToday":""
  },
    "creditDate": {
        "from": "",
        "to": "",
        "lastNDays": "",
        "includeToday": ""
    },
    "debitDate": {
        "from": "",
        "to": "",
        "lastNDays": "",
        "includeToday": ""
    },
    "chargeback": {
        "type": "",
        "from": "",
        "to": "",
        "lastNDays": "",
        "includeToday": ""
    },
  "transactionState":[],
  "paymentMethod":[{  
    "paymentType":"",
    "name":[]
  }],
  "riskAlert":"",
  "customFields":[{  
    "customName":"customvalue"
  }],
  "save":{  
    "name":""
  },
  "invoiceID":""
}

Creates a saved search. If the templateId is present, the template is updated.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

Body parameters:

(Fields in bold are mandatory)

Field Description
shopLogin The shop identifier.
save.name A user friendly name of the custom search.
capturedAmount.from the from amount range. If 10, only captured amounts greater than 10 are returned.
capturedAmount.to The to amount range. If 20, only captured amounts lower than 20 are returned.
authorizedAmount.from the from amount range. If 10, only authorized amounts greater than 10 are returned.
authorizedAmount.to The to amount range. If 20, only authorized amounts lower than 20 are returned.
currency An array of valid currencies to search for.
bankTransactionID the bank transaction ID.
shopTransactionID The shop transaction ID.
authorizationCode The authorization code.
transactionErrorCode A transaction error code.
paymentID The payment ID
authorizationResult The authorization result: can be one of OK, KO, XX, APPROVED, DECLINED, PENDING
tdLevel 3D-Secure level
event An accepted event. See below.
creditDate Allows to search by credit date. Works very similarly to event seen before.
debitDate Allows to search by debit date.
chargeBack Allows to search by disputes. Works very similarly to event seen before.
chargeBack.type You can search by a chargeback type, a value in the ALL, OPEN, CLOSE, CLOSE WITH CHARGE set.
transactionState An array of transaction states. Follow the link for a detailed explanation of transaction statuses.
paymentMethod an array of payment types and payment names.
riskAlert true to select transactions associated with a high risk
customFields.customName You can even search by a custom parameter and its value. Just put the customName set as the key and use the value as the search field.
invoiceID the invoice ID.

event details:

Name Description
type One of the events defined in Event Types.
from The from date for the specified event type.
to The to date for the specified event type.
lastNDays an integer defining if this event should be searched in the last N days. Alternative to from and to.
includeToday If true, it includes today in the search.

Response

Success response example:
200 OK

{
    "result":"OK",
    "search":{
        "name":"mySavedSearch1",
        "searchID":"12423785932",
        "description": "My saved search"
    }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
result OK or KO
search An array containing one or more templates.
search.name The name you assigned in the request
search.searchID An ID generated by Axerve Ecommerce Solutions
search.description A textual dscription of the saved search.

DELETE dasboard/search/saved

Sandbox URL:

DELETE https://sandbox.gestpay.net/api/v1/dashboard/search/saved/{shopLogin}/{searchID}

Production URL:

DELETE https://ecomms2s.sella.it/api/v1/dashboard/search/saved/{shopLogin}/{searchID}

Returns the list of saved searches in Axerve Ecommerce Solutions.

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

URL params:

(Fields in bold are mandatory)

Parameter Description
shopLogin your Shop Login, e.g. GESPAY12345 or XX12345678
searchID an existing searchID

Response

Success response:
200 OK

{  
  "result":"OK",
  "search":{  
    "name":"mySavedSearch1",
    "searchID":"12423785932",
    "description":"My saved search"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

payload details:

Field Description
result OK or KO
search an object with info on the deleted search object.

search details:

Field Description
name The search name.
searchID The ID assigned by Axerve Ecommerce Solutions for this search.
description A textual description for the saved search.

Payment API

With the Payment REST API you can automate every aspect of the payment process.

POST payment/create

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/payment/create/

Production URL:

POST https://ecomms2s.sella.it/api/v1/payment/create/

Example request:

{  
  "shopLogin":"",
  "amount":"",
  "currency":"",
  "shopTransactionID":"",
  "buyerName":"",
  "buyerEmail":"",
  "languageId":"",
  "customInfo":{  
    "{myCustomInfo1}":"{myCustomInfoValue1}",
    "{myCustomInfo2}":"{myCustomInfoValue2}"
  },
  "paymentChannel":{
    "channelType":["(EMAIL/QRCODE/LINK)"],
    "validityPeriod":{
      "validityStart":{
        "minutesFromNow": 0,
        "UTCDateTime": "" //yyyy-mm-ddThh24:mi:00 (ex. "2024-01-29T13:14:00")
      },
      "validityEnd":{
        "minutesFromNow": 1440,
        "UTCDateTime": "",
        "validityMinutes": 0
      }
    },
  },
  "requestToken":"",
  "clientIP":"",
  "itemType":"",
  "recurrent":"",
  "paymentType":[],
  "shippingDetails":{  
    "shipToName":"",
    "shipToStreet":"",
    "shipToState":"",
    "shipToCountryCode":"",
    "shipToZip":"",
    "shipToStreet2":""
  },
  "payPalDescription": "",
  "ppSellerProtection": "",
  "orderDetails":{  
    "fraudPrevention":{  
      "submitForReview":"",
      "orderDateTime":"",
      "orderNote":"",
      "submissionReason":"",
      "beaconSessionID":"",
      "vendorID":"",
      "vendorName":"",
      "source":""
    },
    "customerDetail":{  
      "profileID":"",
      "merchantCustomerID":"",
      "firstName":"",
      "middleName":"",
      "lastname":"",
      "primaryEmail":"",
      "secondaryEmail":"",
      "homePhone":"",
      "mobilePhone":"",
      "dateOfBirth":"",
      "gender":"",
      "socialSecurityNumber":"",
      "company":"",
      "createdAtDate":"",
      "verifiedEmail":"",
      "accountType":"",
      "social":{  
        "network":"",
        "publicUsername":"",
        "communityScore":"",
        "profilePicture":"",
        "email":"",
        "bio":"",
        "accountUrl":"",
        "following":"",
        "followed":"",
        "posts":"",
        "id":"",
        "authToken":"",
        "socialData":""
      }
    },
    "shippingAddress":{  
      "profileID":"",
      "firstName":"",
      "middleName":"",
      "lastname":"",
      "streetName":"",
      "streetname2":"",
      "houseNumber":"",
      "houseExtention":"",
      "city":"",
      "zipCode":"",
      "state":"",
      "countryCode":"",
      "email":"",
      "primaryPhone":"",
      "secondaryPhone":"",
      "company":"",
      "stateCode":""
    },
    "billingAddress":{  
      "profileID":"",
      "firstName":"",
      "middleName":"",
      "lastname":"",
      "streetName":"",
      "streetname2":"",
      "houseNumber":"",
      "houseExtention":"",
      "city":"",
      "zipCode":"",
      "state":"",
      "countryCode":"",
      "email":"",
      "primaryPhone":"",
      "secondaryPhone":"",
      "company":"",
      "stateCode":""
    },
    "ProductDetails": [{
        "ProductCode": "135798642",
        "SKU": "AB-333222-WFG-4",
        "Name": "Porche Carrera scale model",
        "Description": "Porche Carrera scale model",
        "Quantity": "1",
        "Price": "50.5",
        "UnitPrice": "50.5",
        "Type": "1",
        "Vat": "22",
        "Category": "Scale Models",
        "Subcategory": "cars",
        "Brand": "LittleCars",
        "RequiresShipping": "true",
        "DeliveryAt": "2017-12-29",
        "Condition": "new"
      },
      {
        "ProductCode": "135798642",
        "SKU": "AB-333222-WFG-5",
        "Name": "Ferrari scale model",
        "Description": "Ferrari scale model",
        "Quantity": "1",
        "Price": "50.5",
        "UnitPrice": "50.5",
        "Type": "1",
        "Vat": "22",
        "Category": "Scale Models",
        "Subcategory": "cars",
        "Brand": "LittleCars",
        "RequiresShipping": "true",
        "DeliveryAt": "2017-12-29",
        "Condition": "new"
      }
    ],
    "discountCodes":[{  
      "Amount":"",
      "Code":""
    }],
    "shippingLines":[{  
      "Price":"",
      "Title":"",
      "Code":""
    }]
  },
  "transDetails": {
    ...
  }
}

Initialize the payment

Request

Headers:

Header Value Description
Content-Type application/json
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

Input Body:

(Fields in bold are mandatory)

Field Max length Description
shopLogin 30 Your shop login.
amount 9 The amount to capture.
currency 3 ISO currency code.
shopTransactionID 50 the shop transaction ID.
buyerName 50 buyer’s name. Mandatory for Banca Sella customers (see Risk Based Authentication (RBA)).
buyerEmail 50 buyer’s e-mail address. Mandatory for Banca Sella customers (see Risk Based Authentication (RBA)).
customInfo 1000 An object containing optional customised parameters. Use the customInfo parameter name as the key.
paymentChannel Information about The payment channel for this payment. See the table below for a breakdown of all the fields.
requestToken 25 MASKEDPAN for a Standard Token; any other value for Custom Token.
languageId 2 language to use for e-mails to the buyer.
clientIP 45 For PayPal Billing Agreements it is required only in “one click” mode transaction.
For AMEX transaction not in Euro, in this field the merchant could provide the client IP address to activate the Enhanced Authorization AAV.
Mandatory if you use Axerve Guaranteed Payment with S2S.
itemType 250 Item Category: digital/physical (If physical the ShippingDetails have to be filled).
recurrent 5 True if it’s a recurrent payment, False if not.
responseURLs where to redirect the user after the payment.
shippingDetails contains the shipping address. Used for paypal seller protection.
payPalDescription 127 Description of the goods, terms and conditions of the PayPal billing agreement.
ppSellerProtection 1 Set to 1 to use Paypal Seller Protection.
OrderDetails contains every other info needed to handle the payment. It is used by Axerve Guaranteed Payment.
transDetails Contains informations for 3DS 2.0 authentication
Field Description
channelType The payment channel for this payment. Can be EMAIL, QRCODE or LINK, in any combination.
validityPeriod structure to set the validity period of the link/QR code that will be created. If not specified, the validity will be set to the default value of 2880 minutes (48 hours).
validityPeriod.validityStart.minutesFromNow the offset in minutes of the start of the validity of the link from the creation timestamp
validityPeriod.validityStart.UTCDateTime the starting validity date of the link; must be a valid UTC date
validityPeriod.validityEnd.minutesFromNow the offset in minutes of the end of the validity of the link from the creation timestamp
validityPeriod.validityEnd.UTCDateTime the end validity date of the link; must be a valid UTC date
validityPeriod.validityEnd.validityMinutes minutes from validity starting timestamp; can have a value only when minutesFromNow and UTCDateTime are not set
Field Max length Description
shipToName 32 shipping name
shipToStreet 100 shipping address
shipToState 40 shipping state (see Paypal State Codes table)
shipToCountryCode 2 shipping country code (see Paypal Country Codes table)
shipToZip 20 the shipping Zip
shipToStreet2 200 an additional field for the shipping address
Name Format/Max length Description
type 3 Transaction type. Possible values:
  • 01F: Recurring first
  • 01N: Recurring next
  • 03F: Unscheduled MIT first
  • 03N: Unscheduled MIT next
  • 08: Mail Order
  • 09: Telephone Order
  • EC: Ecommerce
  • NPA: only authentication - not payment
If not evaluated, the Axerve Ecommerce Solutions rule is applied.
authenticationAmount max 9 (see the amount field) 3DS authentication amount. If not filled, the authentication amount used will be the amount of the transaction (amount field previously described). The authenticationAmount should be equal or higher than amount, otherwise it will be ignored and the authentication will be made using the amount value. If the authenticationAmount field is used and it is higher than the transaction amount, it is recommended to notify the buyer that the authentication amount will differ from the authorization amount.
threeDSAuthResult object Result of the 3DS authentication done with another provider (Axerve will manage the authorization request, considering the 3DS phase already completed)
authenticationLevel
2 Transaction is successfully authenticated by 3DS:
  • 1H: 3DS 1.0 half
  • 1F: 3DS 1.0 full
  • 2F: 3DS 2.0 frictionless
  • 2C: 3DS 2.0 challenge
  • 2E: 3DS 2.0 exemption
  • OL: One Leg - Authentication not required
authenticationStatus
1 Status of the authentication
XID
36 Transaction unique id assigned by Directory Server
AV
28 Cardholder Authentication Verification Value, proof of authentication done
ECI
2 Electronic Commerce Indicator
AVAlgorithm
2 Cardholder Authentication Verification Algoritm, valorized only with 3DS 1.0
threeDsVersion
8 EMVco protocol version identifier
threeDsContainer object Container of additional data defined in 3DS2 protocol, that better define the transaction. The data here included will be used for assessing the risk level of the transaction with the purpose of ensuring security without affecting the buyer’s experience
recurringTransaction object Contains informations necessary in case of recurring payment
expiry
8 Required for Recurring Payments. Date after which no further transaction shall be performed.
Format: YYYYMMDD
frequency
4 Required for Recurring Payments. It indicates the minimum number of days between two transactions of the same plan
previousTransDetails object Contains the details of a previous authenticated transaction for the same cardholder on the same merchant. If present, it can help to increase the chances of a frictionless authentication
authData
string Prior Transaction Authentication Data
authMethod
2 Prior Transaction Authentication Method. Possible values:
  • 01: Frictionless authentication occurred by ACS
  • 02: Cardholder challenge occurred by ACS
  • 03: AVS verified
  • 04: Other issuer methods
authTimestamp
12 Prior Transaction Authentication Timestamp.
Format: YYYYMMDDHHMM
acsID
36 Prior Transaction Authentication Reference (ACS Transaction ID)
paymentID
Prior payment identifier ID (if it was managed by Axerve Ecommerce Solutions)
XID
36 Prior Transaction unique ID assigned by Directory Server
Response URLs

With the REST Api you can set the redirect url for the success or failure case, along with the Server to server notification URL.

Field Max length Description
buyerOK 100 The URL where the user will be redirected in case of success.
buyerKO 100 The URL where the user will be redirected in case of failure.
serverNotificationURL 100 Axerve Ecommerce Solutions will try to reach this URL to notify the merchant of the payment result.

Response

Success Response:
200 OK

{
  "error":{  
    "code":"0",
    "description":"request correctly processed"
  },
  "payload":{  
    "paymentToken":"Asjdlfad5543AA33a",
    "paymentID":"0000000001",
    "userRedirect": {
      "href": ""
    }
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

payload details:

Field Description
paymentToken A token related to this transaction.
paymentID The ID of this transaction, assigned by Axerve Ecommerce Solutions.
userRedirect.href The address to whom redirect the user.

GET payment/dataForBuyer

Sandbox URL:

GET https://sandbox.gestpay.net/api/v1/payment/dataForBuyer/{paymentID}

Production URL:

GET https://ecomms2s.sella.it/api/v1/payment/dataForBuyer/{paymentID}

Retrieves the current payment data: amount, currency, Merchant Logo URL, Merchant Sign, addional fields sets by the merchant.

Before calling this method, you MUST have already called POST payment/create.

Request

Headers:

Header Value Description
paymentToken {paymentToken} The payment token returned by payment/create

URL parameter:

(Fields in bold are mandatory)

Parameter Description
paymentID The payment identifier.

Response

Success response example:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{  
      "merchantLogo":"https://ecomms2s.sella.it/temp/MerchantLogo.SVG",
      "sign":"MERCHANTSIGN",
      "amount":"1.00",
      "languageID":"ITA",
      "currency":"EUR",
      "visibleCustomFields":[  
        {  
            "myVisibleCustomField1":"myVisibleCustomField1",
            "myVisibleCustomField2":"myVisibleCustomField2"
        }
      ],
      "paymentID":"121213231"
    }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
merchantLogo The merchant logo image URL
sign The merchant’s name. This can correspond to the business name.
amount The transaction amount
languageID The buyer’s language
currency ` the payment currency ISO code
visibleCustomFields A list of custom fields that are set as visible to the user. These fields are set by the merchant. For further information see sending custom parameters to Axerve Ecommerce Solutions.

GET payment/methods

Sandbox URL:

GET https://sandbox.gestpay.net/api/v1/payment/methods/{paymentID}/{languageID}

Production URL:

GET https://ecomms2s.sella.it/api/v1/payment/methods/{paymentID}/{languageID}

Retrieves the list of the enabled and visible payment methods. For each method provides: - Method name - Logo url (.svg +.png) for Desktop and Mobile version - PaymentType - PaymentTypeDetail required (TRUE / FALSE)

Before calling this method, you MUST have already called POST payment/create.

Request

Headers:

Header Value Description
paymentToken {paymentToken} The payment token returned by payment/create

URL parameter:

(Fields in bold are mandatory)

Parameter Max Length Description
paymentID The payment identifier.
languageID 2 The chosen language for this payment. See the language codes table.

Response

Success response example:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload": {  
    "paymentMethod":[  
      {  
        "name":"PayPal",
        "logo":{  
          "large":"https://{domain}/logos/PayPal_Large.png",
          "mobile":"https://{domain}/logos/PayPal_mobile.png",
          "vector":"https://{domain}/logos/PayPal.svg"
        },
        "paymentType":"PAYPAL",
        "paymentTypeDetail":{  
          "href":""
        },
        "userRedirect":{  
          "href":"https://ecomm.sella.it/pagam/pagam.aspx?a=yourshoplogin&b=somePaymentToken&paymentType=PAYPAL"
        }
      },
      {  
        "name":"VisaVbv",
        "logo":{  
          "large":"https://{domain}/logos/VisaVbv_Large.png",
          "mobile":"https://{domain}/logos/VisaVbv_mobile.png",
          "vector":"https://{domain}/logos/VisaVbv.svg"
        },
        "paymentType":"CreditCard",
        "paymentTypeDetail":{  
          "href":""
        },
        "userRedirect":{  
          "href":""
        }
      },
      {  
        "name":"MyBank",
        "logo":{  
          "large":"https://{domain}/logos/MyBank_Large.png",
          "mobile":"https://{domain}/logos/MyBank_mobile.png",
          "vector":"https://{domain}/logos/MyBank.svg"
        },
        "paymentType":"MyBank",
        "paymentTypeDetail":{  
          "href":"/payment/method/detail/MyBank/{shopLogin}"
        },
        "userRedirect":{  
          "href":""
        }
      }
    ],
    "paymentID":"111214124"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
paymentMethod an array of payment methods. See next table.
paymentID The payment ID.

Children of paymentMethod:

Field Description
name The payment method
logo Logos for the payment method: desktop, mobile, vectorial are available.
paymentType The corresponding payment type for this payment method
paymentTypeDetail.href An url that points to more details for the current payment method. Empty if not applicable.
userRedirect.href The URL to redirect the user to pay with this payment method. Empty if not applicable.

GET payment/methods/detail

Sandbox URL:

GET https://sandbox.gestpay.net/api/v1/payment/methods/detail/{paymentID}/{paymentType}

Production URL:

GET https://ecomms2s.sella.it/api/v1/payment/methods/detail/{paymentID}/{paymentType}

Some payment methods need additional iformation to complete the payment process. For example, they might require to redirect the user to a specific page. With this method you can find the additional informations required.

Before calling this method, you MUST have already called POST payment/create.

Request

Headers:

Header Value Description
paymentToken {paymentToken} The payment token.

URL parameter:

(Fields in bold are mandatory)

Parameter Max Length Description
paymentID The payment identifier
paymentType 25 The payment type

Response

Success response example:
200 OK

{
  "error":{  
    "code":"0",
    "description":"request correctly processed"
  },
  "payload":{  
    "paymentTypeDetail":{  
      "bank":[  
        {  
          "bankCode":"001",
          "bankName":"E-Corp",
          "userRedirect":{  
            "href":"https://ecomm.sella.it/pagam/pagam.aspx?a=yourshoplogin&b=somePaymentToken&paymentType=thePaymentType&payment"
          }
        },
        {  
          "bankCode":"002",
          "bankName":"F-Corp",
          "userRedirect":{  
            "href":"https://ecomm.sella.it/pagam/pagam.aspx?a=yourshoplogin&b=somePaymentToken&paymentType=thePaymentType&payment"
          }
        }
      ]
    },
    "paymentID":"11232131242314"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
paymentTypeDetail.bank An array containing informations about specific banks for this payment method. See next table
paymentTypeDetail.paymentID the payment ID

Details for bank array:

Field Description
bankCode A code that identifies the bank
bankName The bank Name, useful to show the bank name to the user
userRedirect.href The url to redirect the user to pay with the chosen bank

POST payment/update

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/payment/update

Production URL:

POST https://ecomms2s.sella.it/api/v1/payment/update

Request Body:

{
  "shopLogin":"",
  "amount":"",
  "paymentID":"",
  "shippingDetails":{
    "shipToName":"",
    "shipToStreet":"",
    "shipToState":"",
    "shipToCountryCode":"",
    "shipToZip":"",
    "shipToStreet2":""
  },
  "orderDetails":{
    "fraudPrevention":{
      "submitForReview":"",
      "orderDateTime":"",
      "orderNote":"",
      "source":"",
      "submissionReason":"",
      "beaconSessionID":"",
      "vendorID":"",
      "vendorName":""
    },
    "customerDetail":{
      "profileID":"",
      "merchantCustomerID":"",
      "firstName":"",
      "middleName":"",
      "lastname":"",
      "primaryEmail":"",
      "secondaryEmail":"",
      "homePhone":"",
      "mobilePhone":"",
      "dateOfBirth":"",
      "gender":"",
      "socialSecurityNumber":"",
      "company":"",
      "createdAtDate":"",
      "verifiedEmail":"",
      "accountType":"",
      "social":{
        "network":"",
        "publicUsername":"",
        "communityScore":"",
        "profilePicture":"",
        "email":"",
        "bio":"",
        "accountUrl":"",
        "following":"",
        "followed":"",
        "posts":"",
        "id":"",
        "authToken":"",
        "socialData":""
      }
    },
    "shippingAddress":{
      "profileID":"",
      "firstName":"",
      "middleName":"",
      "lastname":"",
      "streetName":"",
      "streetname2":"",
      "houseNumber":"",
      "houseExtention":"",
      "city":"",
      "zipCode":"",
      "state":"",
      "countryCode":"",
      "email":"",
      "primaryPhone":"",
      "secondaryPhone":"",
      "company":"",
      "stateCode":""
    },
    "billingAddress":{
      "profileID":"",
      "firstName":"",
      "middleName":"",
      "lastname":"",
      "streetName":"",
      "streetname2":"",
      "houseNumber":"",
      "houseExtention":"",
      "city":"",
      "zipCode":"",
      "state":"",
      "countryCode":"",
      "email":"",
      "primaryPhone":"",
      "secondaryPhone":"",
      "company":"",
      "stateCode":""
    },
    "productDetails":[
      {
        "productCode":"",
        "SKU":"",
        "name":"",
        "description":"",
        "quantity":"",
        "price":"",
        "unitPrice":"",
        "type":"",
        "vat":"",
        "discount":"",
        "requiresShipping":"",
        "condition":"",
        "seller":"",
        "category":"",
        "subCategory":"",
        "brand":"",
        "deliveryAt":""
      }
    ],
    "discountCodes":[
      {
        "Amount":"",
        "Code":""
      }
    ],
    "shippingLines":[
      {
        "Price":"",
        "Title":"",
        "Code":""
      }
    ]
  }
}

Updates a payment with new information.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

Request Body:

(Fields in bold are mandatory)

Field Max Length Description
shopLogin 30 the merchant’s code
amount 9 the updated amount
paymentID The payment ID to update
shippingDetails if the payment method you’re using spports shippingDetails, you can pass updated fields. See shippingDetails for info.
orderDetails if the payment method you’re using spports orderDetails, you can pass updated fields. See orderDetails for info.

Response

Success Response:
200 OK

{
  "error":{  
    "code":"0",
    "description":"request correctly processed"
  },
  "payload":{
    "transactionType":"update",
    "transactionResult":"OK",
    "paymentID":"1112312421"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
transactionType always update for this operation
transactionResult OK ok KO
paymentID The payment ID

POST payment/submit

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/payment/submit

Production URL:

POST https://ecomms2s.sella.it/api/v1/payment/submit

Request Body:

{  
  "shopLogin":"",
  "paymentType":"",
  "buyer":{  
    "name":"",
    "email":""
  },
  "cof":"Y",
  "paymentTypeDetails":{  
    "creditcard":{
      "number":"",
      "token":"",
      "expMonth":"",
      "expYear":"",
      "CVV":"",
      "requestToken":"",
      "DCC": ""
    },
    "amazonPay":{  
      "amazonReferenceOrderId":"",
      "requestToken":"",
      "token":""
    },
    "applePay":{  
      "PKPaymentToken":"",
      "onlinePaymentCryptogram":"",
      "eciIndicator":"",
      "requestToken":"",
      "token":""
    },
    "bancomatPay": {
      "phoneNumber": ""
    },
    "googlePay": {
      "tokenizationData": {
        "token": {}
      }
    },
    "myBank":{  
      "bankCode":""
    },
    "iDeal":{  
      "bankCode":""
    },
    "payPal":{  
      "token":""
    }
  },
  "responseURLs":{  
    "buyerOK":"",
    "buyerKO":"",
    "serverNotificationURL":""
  },
  // SEPA
  "slimPay":{  
    "token":"SP7NYQTXYKG5CQFM",
    "executionDate":"20201212"
  },
}

Enables merchants to perform authorization requests for all the payment methods enabled for the merchant.

Before calling this method, you MUST have already called POST payment/create.

In case of a payment method that requires a widget (e.g. AmazonPay) it will provide the URL and the dimensions of the iFrame.

In case the payment method requires a selected redirect it will provide the URL to redirect the customer.

Note: Redirected url will require merchant return url and transkey.

This method will handle payment triangulations (e.g. 3DSecure, PayPal, S2Pay, etc.) through transkey and method related tokens in the 2nd calls.

In order to display transaction results to the user without requesting the server to retrieve it through paymentResult it should return it in the response payload.

Request

Headers:

Header Value Description
paymentToken {PaymentToken} The payment token, created via payment/create

Request Body:

(Fields in bold are mandatory)

Field Max Length Description
shopLogin 30 The merchant’s code
paymentType 100 The payment method chosen by the user
buyer.name 50 The buyer’s name
buyer.email 1000 The buyer’s email
cof 1 Card On File flag, Y for “Card On File” transaction, null or other values for no “Card On File” transaction. See the Card On File section for more information.
paymentTypeDetails Based on the chosen payment method, it will contain informations to complete the payment. See next sections.
responseURLs Where to redirect the user after the payment.
executionDate 7 Date of charge on the buyer’s banking account. (SEPA)


executionDate allows the merchant to define the date of charge on the buyer’s banking account. To follow SEPA rules, if the date it’s not on a working day, the charge will be postponed to the next working day. It must be in yyyymmdd format


paymentTypeDetails: Credit card

If the customer has chosen the credit card payment type, fill out these fields:

Field Max Length Description
number 50 The credit card number
token 25 The credit card token
expMonth 2 The expiry expMonth
expYear 2 The expiry year
CVV 4 The CVV code
requestToken 25 MASKEDPAN for a Standard Token; any other value for Custom Token
DCC 5 if the payment uses currency conversion. True or False
paymentTypeDetails: Amazon Pay

To pay with Amazon Pay, fill out the fields below:

Field Max Length Description
amazonReferenceOrderId The order reference identifier retrieved from the Amazon Button widget.
requestToken 25 MASKEDPAN for a Standard Token; any other value for Custom Token
token 25 A token representing the AmazonPay token.
paymentTypeDetails: Apple Pay

If your customers choose Apple Pay, these are the parameters to pass:

Field Max Length Description
PKPaymentToken An object that contains the user’s payment credentials.
onlinePaymentCryptogram a unique, one time use cryptogram used by Axerve Ecommerce Solutions to decrypt the payment data
eciIndicator optional data used for 3D secure transactions
requestToken 25 MASKEDPAN for a Standard Token; any other value for Custom Token
token 25 a token representing the ApplePay token
paymentTypeDetails: Bancomat Pay

If your customers choose Bancomat Pay, bancomatPay must be added

paymentTypeDetails: My Bank
Field Max Length Description
bankCode 25 A MyBank bank code
paymentTypeDetails: iDeal
Field Max Length Description
bankCode 25 An iDeal bank code
paymentTypeDetails: Paypal
Field Max Length Description
token 25 A token representing the Paypal token.
Response URLs

With the REST Api you can set the redirect url for the success or failure case, along with the Server to server notification URL.

Field Max Length Description
buyerOK 100 The URL where the user will be redirected in case of success.
buyerKO 100 The URL where the user will be redirected in case of failure.
serverNotificationURL 100 Axerve Ecommerce Solutions will try to reach this URL to notify the merchant of the payment result.

Response

Success response for a non 3D credit card:
200 OK

{
  "error":{  
    "code":"0",
    "description":"request correctly processed"
  },
  "payload": {
    "transactionType" : "submit",
    "transactionResult" :"OK",
    "transactionErrorCode" :"",   
    "transactionErrorDescription" :"",
    "bankTransactionID" : "11111111",
    "shopTransactionID":"myshoptransactionID",
    "authorizationCode":"1223321",
    "paymentID":"000000001",
    "currency":"EUR",
    "country":"ITALIA",
    "company":"VISA",
    "tdLevel":"NULL",
    "buyer":{
      "name":"buyerName Submitted",
      "email":"buyer@SubmittedEmail.com"
    },
    "risk":{
      "riskResponseCode":"",
      "riskResponseDescription":""
    }
    "customInfo":{
      "myCustomInfo1":"myCustomInfoValue1",
      "myCustomInfo2":"myCustomInfoValue2"
    },
    "alertCode":"",
    "alertDescription":"",
    "cvvPresent":"",
    "maskedPAN":"",
    "paymentMethod":"",
    "productType":"",
    "token":"444444xxxxxx4448",
    "tokenExpiryMonth":"01",
    "tokenExpiryYear":"25",
    "userRedirect":{
      "href": "https://ecomm.sella.it/pagam/pagam3d.aspx?a={shopLogin}&b={paymentToken}"
    }
  }
}

Success response for a 3D credit card:
200 OK

{
  "error":{  
    "code":"0",
    "description":"request correctly processed"
  },
  "payload": {
    "transactionType":"submit",
    "transactionResult":"",
    "transactionErrorCode" :"8006",   
    "transactionErrorDescription" :"Verify By Visa",
    "bankTransactionID":"",
    "shopTransactionID":"myshoptransactionID",
    "authorizationCode":"",
    "paymentID":"00000000001",
    "currency":"",
    "country":"",
    "company":"",
    "tdLevel":"",
    "buyer":{
      "name":"",
      "email":""
    },
    "risk":{
      "riskResponseCode":"",
      "riskResponseDescription":""
    },
    "customInfo":{

    },
    "alertCode":"",
    "alertDescription":"",
    "cvvPresent":"",
    "maskedPAN":"",
    "paymentMethod":"",
    "productType":"",
    "token":"",
    "tokenExpiryMonth":"",
    "tokenExpiryYear":"",
    "userRedirect":{
      "href":"https://ecomm.sella.it/pagam/pagam3d.aspx?a={shopLogin}&b={paymentToken}"
    }
  }
}

Success response for a redirect-based payment method (i.e. Paypal):
200 OK

{
  "error":{  
    "code":"0",
    "description":"request correctly processed"
  },
  "payload": {
    "transactionType":"submit",
    "transactionResult":"",
    "transactionErrorCode" :"",   
    "transactionErrorDescription" :"",
    "bankTransactionID":"",
    "shopTransactionID":"myshoptransactionID",
    "authorizationCode":"",
    "currency":"",
    "country":"",
    "company":"",
    "tdLevel":"",
    "buyer":{
      "name":"",
      "email":""
    },
    "risk":{
      "riskResponseCode":"",
      "riskResponseDescription":""
    },
    "customInfo":{

    },
    "alertCode":"",
    "alertDescription":"",
    "cvvPresent":"",
    "maskedPAN":"",
    "paymentMethod":"PayPal",
    "productType":"",
    "token":"",
    "tokenExpiryMonth":"",
    "tokenExpiryYear":"",
    "userRedirect":{
      "href":"https://ecomm.sella.it/pagam/pagam3d.aspx?a={shopLogin}&b={paymentToken}&paymentType=S2PX"
    }
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
transactionType Always submit for this method.
transactionResult OK or KO
transactionErrorCode The error code, in case of errors
transactionErrorDescription A description in common language of the occurred error.
bankTransactionID code assigned by Axerve Ecommerce Solutions this transaction.
shopTransactionID shop transaction ID value
authorizationCode authorisation code
paymentID The payment ID
currency The currency ISO code
country nationality of the card issuer
company Card issuer company
tdLevel The level of 3D-Secure authentication: FULL or HALF.
buyer Contains informations about the buyer. See the table below.
risk A risk code, assigned by Axerve Guaranteed Payment. See the table below for more informations.
customInfo An object containing optional customised parameters, created by the merchant in the form of key-value.
alertCode Alert code. See Better Risk Management for an accurate description.
alertDescription A textual description of the alertCode.
cvvPresent Credit Card security code flag
maskedPAN Masked Pan string
paymentMethod Indicates the used Payment Method
productType  String containing Card Type
token String containing the token value
tokenExpiryMonth String containing the token expiry month
TokenExpiryYear String containing the token expiry year
userRedirect.href a URL to redirect the user for 3D-Secure authentication, or to pay on alternative payment systems.
buyer details
Field Description
name The buyer’s name
email The buyer’s email
risk details
Field Description
riskResponseCode One of Axerve Guaranteed Payment response codes.
riskResponseDescription A textual description of the risk analisys.

GET payment/detail

Sandbox URL:

GET https://sandbox.gestpay.net/api/v1/payment/detail/{paymentID}

Production URL:

GET https://ecomms2s.sella.it/api/v1/payment/detail/{paymentID}

Retrieves the details of a payment.

Request

To authenticate, use one of the following headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.
paymentToken {paymentToken} A payment token received during the payment process

URL parameter:

(Fields in bold are mandatory)

Parameter Description
paymentID The payment identifier.

Response

Success Response
200 OK

{
  "error":{  
    "code": "0",
    "description": "request correctly processed"
  },
  "payload":{
    "transactionType": "detail",
    "transactionResult": "",
    "transactionState": "",
    "transactionErrorCode": "",
    "transactionErrorDescription": "",
    "bankTransactionID": "",
    "shopTransactionID": "",
    "authorizationCode": "",
    "paymentID": "",
    "currency": "",
    "country": "",
    "company": "",
    "tdLevel": "",
    "events":[{
      "event":{
        "eventtype": "",
        "eventamount": "",
        "eventdate": "",
        "eventARN": "",
        "eventID": "",
        "eventReferred": "",
      }
    }],
    "buyer":{
      "name": "",
      "email": ""
    },
    "risk":{
      "riskResponseCode": "",
      "riskResponseDescription": ""
    },
    "customInfo":{
      "{myCustomInfo1}": "{myCustomInfoValue1}",
      "{myCustomInfo2}": "{myCustomInfoValue2}"
    },
    "alertCode": "",
    "alertDescription": "",
    "cvvPresent": "{TRUE/FALSE}",
    "dcc":{
      "eligible": "{TRUE/FALSE}",
      "currency": ""
    },
    "maskedPAN": "",
    "paymentMethod": "",
    "productType": "",
    "token": "",
    "tokenExpiryMonth": "",
    "tokenExpiryYear": "",
    "tokenDetails": {
      "tokenValue": "42V8ZN2BA0144011",
      "tokenExpiryMonth": "02",
      "tokenExpiryYear": "23",
      "tokenProvider": {
        "-self-closing": "true"
      },
      "cardDetails": {
        "cardExpiryMonth": {
          "-self-closing": "true"
        },
        "cardExpiryYear": {
          "-self-closing": "true"
        },
        "cardHolderName": {
          "-self-closing": "true"
        },
        "cardSuffix": {
          "-self-closing": "true"
        }
      },
      "cardAssets": {
        "cardArt": {
          "height": {
            "-self-closing": "true"
          },
          "mediaContents": {
            "-self-closing": "true"
          },
          "type": {
            "-self-closing": "true"
          },
          "width": {
            "-self-closing": "true"
          }
        },
        "brandLogo": {
          "height": {
            "-self-closing": "true"
          },
          "mediaContents": {
            "-self-closing": "true"
          },
          "type": {
            "-self-closing": "true"
          },
          "width": {
            "-self-closing": "true"
          }
        }
      }
    },
    "vbv":{
      "flag": "",
      "buyer": ""
    },
    "payPalFee": "",
    "fraudPrevention":{
      "check": "{TRUE/FALSE}",
      "state": "",
      "description": "",
      "order": ""
    },
    "automaticOperation":{
      "type": "",
      "date": "",
      "amount": ""
    }
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

payload details:

Field Description
transactionType detail
TransactionResult UNSUBMITTED, WAITING, PENDING (or XX), APPROVED (or OK), DECLINED (or KO)
transactionState The last state of the transaction, as one of the states contained in event types.
bankTransactionID A transaction ID assigned by the bank.
shopTransactionID An ID assigned by the shop.
authorizationCode A code released by the payment circuit.
paymentID Assigned by Axerve Ecommerce Solutions, identifies the payment
currency One of the ISO currencies.
country The country originating the transaction
company The credit card / payment circuit
tdLevel FULL if the transaction is fully 3D-Secure protected, HALF.
alertCode Alert code. See Better Risk Management for an accurate description.
AlertDescription Alert description in chosen language. See Better Risk Management for an accurate description.
buyer Contains informations about the buyer name, if available. See the able below.
risk Contains informations about the risk score, assigned by Axerve Guaranteed Payment. See below.
customInfo An object containing optional customised parameters. set your parameters as key-value pairs.
events Contains informations about this payment history. See below.
cvvPresent TRUE if the payment has been executed by using a CVV security code.
dcc Stands for Dynamic Currency Conversion. See the table below.
maskedPAN Masked PAN string
paymentMethod the payment method used to perform the payment
productType String containing card type
token String containing the token value
tokenExpiryMonth String containing the token expiry month
TokenExpiryYear String containing the token expiry year
vbv Informations about the 3DSecure status.
payPalFee The fee owed to paypal.
fraudPrevention informations about fraud prevention. Responses by Axerve Guaranteed Payment will show here.
transactionErrorCode The error code for the transaction. See error codes page for details.
transactionErrorDescription The error code description in common language.
automaticOperation it refers to an automatic operation that has been programmed.
threeDS sandbox Object with information about 3ds authentication (described below)

events details:

Field Description
eventtype One of the event types
eventamount the amount involved in this event
eventdate The date of the event
eventARN The acquirer reference number
eventID Unique identifier of the event
eventReferred Unique identifier of the original event it refers to (IE In case of STO it contains the MOV eventide it refers to)
environment The environment that has generated the event: ONL (Online), BOF (Back Office), BAT (Batch)
operator The user code that has performed the operation

buyerdetails:

Field Description
name The buyer’s name
email The buyer’s email

riks details:

Field Description
RiskResponseCode Risk Fraud Score of the transaction, given by Axerve Guaranteed Payment. See here for a list of possible values.
RiskResponseDescription Risk Description for the RiskResponseCode value

dcc details:

Field Description
eligible TRUE if the payment is DCC eligible and is therefore converted at payment time; FALSE otherwise.
currency The exchange rate.

fraudPrevention details:

Field Description
check The kind of check applied.
state The status of the transaction.
description The status description
order the order reference

The threeDS sandbox object contains three objects:

Name max length description
authenticationLevel 2 Transaction is successfully athenticated by 3DS:
  • 1H: 3DS 1.0 half
  • 1F: 3DS 1.0 full
  • 2F: 3DS 2.0 frictionless
  • 2C: 3DS 2.0 challenge
  • 2E: 3DS 2.0 exemption
  • OL: One Leg - Authentication not required
  • NA: No Authentication
authenticationStatus 1 Status of authentication
authStatusReason 2 Provides information on why the Transaction Status field has the specified value
XID 36 Transaction unique id assigned by Directory Server
AV 28 Cardholder Authentication Verification Value, proof of authentication done
ECI 2 Electronic Commerce Indicator
AVAlgorithm 2 Cardholder Authentication Verification Algoritm, valorized only with 3DS 1.0
threeDsVersion 8 EMVco protocol version identifier
Name max length description
authData string Transaction Authentication Data
authMethod 2 Transaction Authentication Method Possible values:
  • 01: Frictionless authentication occurred by ACS
  • 02: Cardholder challenge occurred by ACS
  • 03: AVS verified
  • 04: Other issuer methods
authTimestamp 12 Transaction Authentication Timestamp
acsID 36 ACS Transaction ID
Name Description
threeDSServerTransID Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.
acsSignedContent Contains the JWS object (represented as a string) created by the ACS for the ARes message.
acsTransID Universally Unique transaction identifier assigned by the ACS to identify a single transaction.
acsURL Fully qualified URL of the ACS to be used for the challenge.
cardholderInfo Text provided by the ACS/Issuer to Cardholder during a Frictionless or Decoupled transaction. The Issuer can provide information to Cardholder. For example, “Additional authentication is needed for this transaction, please contact (Issuer Name) at xxx-xxx-xxxx.”
messageExtension Data necessary to support requirements not otherwise defined in the 3- D Secure message are carried in a Message Extension.
sdkTransID Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction

tokenDetails details:

Name Description
tokenValue String containing the token value returned by Axerve Ecommerce Solutions.
tokenExpiryMonth The token expiration month.
tokenExpiryYear The token expiration year.
tokenProvider The entity providing the token. It can be: AXERVE, VISA, MASTERCARD, PAYPAL, AMAZON, APPLE, SEPADD.
cardDetails.cardSuffix The last 4 digit of the card PAN.
cardDetails.cardExpiryMonth The card expiry month.
cardDetails.cardExpiryYear The card expiry Year.
cardDetails.cardHolderName The cardholder name.
cardAssets.cardArt.type The file format of the card art (card image)
cardAssets.cardArt.mediaContents The card image (Base64)
cardAssets.cardArt.height The card art (card image) height
cardAssets.cardArt.width The card art (card image) width
cardAssets.brandLogo.type The file format of the brand logo (e.g. Visa, Mastercard, etc..)
cardAssets.brandLogo.mediaContents The brand logo (e.g. Visa, Mastercard, etc..) image (Base64)
cardAssets.brandLogo.height The brand logo (e.g. Visa, Mastercard, etc..) height
cardAssets.brandLogo.width The brand logo (e.g. Visa, Mastercard, etc..) width

POST payment/detail

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/payment/detail

Production URL:

POST https://ecomms2s.sella.it/api/v1/payment/detail

Example request:

{
  "shopLogin" : "",
  "bankTransactionID": "",
  "shopTransactionID" : "",
  "paymentID":"",
  "terminalID": ""
}

Retrieves the details of a payment.

Request

To authenticate, use one of the following headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.
paymentToken {paymentToken} A payment token received during the payment process

Input Body:

(Fields in bold are mandatory)

Field Max Length Description Example
shopLogin 30 Your shop login GESPAY12345
shopTransactionID 50 the shop transaction ID MyShop_001
bankTransactionID 18 The bank transaction ID 1111
paymentID The payment ID 1638523579
terminalID 20 The terminal ID 12340005

Note: you must provide at least one of shopTransactionID, bankTransactionID, paymentID.

Response

Success Response
200 OK

{
  "error":{  
    "code": "0",
    "description": "request correctly processed"
  },
  "payload":{  
    "transactionType": "detail",
    "transactionResult": "OK",
    "transactionState": "MOV",
    "bankTransactionID": "11111",
    "shopTransactionID": "myShopTransactionID",
    "authorizationCode": "0010202",
    "paymentID": "00000000001",
    "currency": "EUR",
    "country": "ITALIA",
    "company": "MASTERCARD SECURECODE",
    "tdLevel": "FULL",
    "events":[{  
      "eventtype": "AUT",
      "eventamount": "0.10",
      "eventdate": "19/08/16 16:13:14",
      "eventARN": "",
      "eventID": ""
    }, {  
      "eventtype": "MOV",
      "eventamount": "0.10",
      "eventdate": "20/08/16 00:13:57",
      "eventARN": "",
      "eventID": ""
    }],
    "buyer":{  
      "name": "",
      "email": ""
    },
    "risk":{  
      "riskResponseCode": "approved",
      "riskResponseDescription": ""
    },
    "customInfo":{
      "{myCustomInfo1}": "{myCustomInfoValue1}",
      "{myCustomInfo2}": "{myCustomInfoValue2}"
    },
    "alertCode": "",
    "alertDescription": "",
    "cvvPresent": "{TRUE/FALSE}",
    "dcc":{
      "eligible": "{TRUE/FALSE}",
      "currency": ""
    },
    "maskedPAN": "",
    "paymentMethod": "",
    "productType": "",
    "token": "",
    "tokenExpiryMonth": "",
    "tokenExpiryYear": "",
    "vbv":{
      "flag": "",
      "buyer": ""
    },
    "tokenDetails": {
      "tokenValue": "42V8ZN2BA0144011",
      "tokenExpiryMonth": "02",
      "tokenExpiryYear": "23",
      "tokenProvider": {
        "-self-closing": "true"
      },
      "cardDetails": {
        "cardExpiryMonth": {
          "-self-closing": "true"
        },
        "cardExpiryYear": {
          "-self-closing": "true"
        },
        "cardHolderName": {
          "-self-closing": "true"
        },
        "cardSuffix": {
          "-self-closing": "true"
        }
      },
      "cardAssets": {
        "cardArt": {
          "height": {
            "-self-closing": "true"
          },
          "mediaContents": {
            "-self-closing": "true"
          },
          "type": {
            "-self-closing": "true"
          },
          "width": {
            "-self-closing": "true"
          }
        },
        "brandLogo": {
          "height": {
            "-self-closing": "true"
          },
          "mediaContents": {
            "-self-closing": "true"
          },
          "type": {
            "-self-closing": "true"
          },
          "width": {
            "-self-closing": "true"
          }
        }
      }
    },
    "payPalFee": "",
    "fraudPrevention":{
      "check": "{TRUE/FALSE}",
      "state": "",
      "description": "",
      "order": ""
    },
    "automaticOperation":{
      "type": "",
      "date": "",
      "amount": ""
    }
  },
  "threeDS":{
    "authenticationResult":{
      ...
    },
    "InAppChallenge": {
      ...
    }
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

error details:

Field Description
error.code 0 means no error, otherwise check the error codes and error.description to debug the problem.
error.description If error.code != 0 will contain a description of the error.

payload details:

Field Description
transactionType detail
TransactionResult UNSUBMITTED, WAITING, PENDING (or XX), APPROVED (or OK), DECLINED (or KO)
transactionState The last state of the transaction, as one of the states contained in event types.
bankTransactionID A transaction ID assigned by the bank.
shopTransactionID An ID assigned by the shop.
authorizationCode A code released by the payment circuit.
paymentID Assigned by Axerve Ecommerce Solutions, identifies the payment
currency The original ISO currency code of the transaction. See ISO currencies for a list.
country The country originating the transaction
company The credit card / payment circuit
tdLevel FULL if the transaction is fully 3D-Secure protected, HALF.
alertCode Alert code. See Better Risk Management for an accurate description.
AlertDescription Alert description in chosen language. See Better Risk Management for an accurate description.
buyer Contains informations about the buyer name, if available. See the able below.
risk Contains informations about the risk score, assigned by Axerve Guaranteed Payment. See below.
customInfo An object containing optional customised parameters. set your parameters as key-value pairs.
events Contains informations about this payment history. See below.
cvvPresent TRUE if the payment has been executed by using a CVV security code.
dcc Stands for Dynamic Currency Conversion. See the table below.
maskedPAN Masked PAN string
paymentMethod the payment method used to perform the payment.
productType string containing Card Type.
transactionErrorCode The error code for the transaction. See error codes page for details.
transactionErrorDescription The error code description in common language.
token String containing the token value
tokenExpiryMonth String containing the token expiry month
TokenExpiryYear String containing the token expiry year
vbv Informations about the 3DSecure status.
payPalFee The fee owed to paypal.
fraudPrevention informations about fraud prevention. Responses by Axerve Guaranteed Payment will show here.
automaticOperation it refers to an automatic operation that has been programmed.
threeDS sandbox Object with information about 3ds authentication (described below)

events details:

Field Description
eventtype One of the event types
eventamount the amount involved in this event
eventdate The date of the event
eventARN The acquirer reference number
eventID Unique identifier of the event
environment The environment that has generated the event: ONL (Online), BOF (Back Office), BAT (Batch)
operator The user code that has performed the operation

buyerdetails:

Field Description
name The buyer’s name
email The buyer’s email

riks details:

Field Description
RiskResponseCode Risk Fraud Score of the transaction, given by Axerve Guaranteed Payment. See here for a list of possible values.
RiskResponseDescription Risk Description for the RiskResponseCode value

dcc details:

Field Description
eligible TRUE if the payment is DCC eligible and is therefore converted at payment time; FALSE otherwise.
currency The exchange rate.

fraudPrevention details:

Field Description
check The kind of check applied.
state The status of the transaction.
description The status description
order the order reference

The threeDS sandbox object contains three object:

Name max length description
authenticationLevel 2 Transaction is successfully athenticated by 3DS:
  • 1H: 3DS 1.0 half
  • 1F: 3DS 1.0 full
  • 2F: 3DS 2.0 frictionless
  • 2C: 3DS 2.0 challenge
  • 2E: 3DS 2.0 exemption
  • OL: One Leg - Authentication not required
  • NA: No Authentication
authenticationStatus 1 Status of authentication
authStatusReason 2 Provides information on why the Transaction Status field has the specified value
XID 36 Transaction unique id assigned by Directory Server
AV 28 Cardholder Authentication Verification Value, proof of authentication done
ECI 2 Electronic Commerce Indicator
AVAlgorithm 2 Cardholder Authentication Verification Algoritm, valorized only with 3DS 1.0
threeDsVersion 8 EMVco protocol version identifier
Name max length description
authData string Transaction Authentication Data
authMethod 2 Transaction Authentication Method Possible values:
  • 01: Frictionless authentication occurred by ACS
  • 02: Cardholder challenge occurred by ACS
  • 03: AVS verified
  • 04: Other issuer methods
authTimestamp 12 Transaction Authentication Timestamp
acsID 36 ACS Transaction ID
Name Description
threeDSServerTransID Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.
acsSignedContent Contains the JWS object (represented as a string) created by the ACS for the ARes message.
acsTransID Universally Unique transaction identifier assigned by the ACS to identify a single transaction.
acsURL Fully qualified URL of the ACS to be used for the challenge.
cardholderInfo Text provided by the ACS/Issuer to Cardholder during a Frictionless or Decoupled transaction. The Issuer can provide information to Cardholder. For example, “Additional authentication is needed for this transaction, please contact (Issuer Name) at xxx-xxx-xxxx.”
messageExtension Data necessary to support requirements not otherwise defined in the 3- D Secure message are carried in a Message Extension.
sdkTransID Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction

tokenDetails details:

Name Description
tokenValue String containing the token value returned by Axerve Ecommerce Solutions.
tokenExpiryMonth The token expiration month.
tokenExpiryYear The token expiration year.
tokenProvider The entity providing the token. It can be: AXERVE, VISA, MASTERCARD, PAYPAL, AMAZON, APPLE, SEPADD.
cardDetails.cardSuffix The last 4 digit of the card PAN.
cardDetails.cardExpiryMonth The card expiry month.
cardDetails.cardExpiryYear The card expiry Year.
cardDetails.cardHolderName The cardholder name.
cardAssets.cardArt.type The file format of the card art (card image)
cardAssets.cardArt.mediaContents The card image (Base64)
cardAssets.cardArt.height The card art (card image) height
cardAssets.cardArt.width The card art (card image) width
cardAssets.brandLogo.type The file format of the brand logo (e.g. Visa, Mastercard, etc..)
cardAssets.brandLogo.mediaContents The brand logo (e.g. Visa, Mastercard, etc..) image (Base64)
cardAssets.brandLogo.height The brand logo (e.g. Visa, Mastercard, etc..) height
cardAssets.brandLogo.width The brand logo (e.g. Visa, Mastercard, etc..) width

POST payment/capture

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/payment/capture/

Production URL:

POST https://ecomms2s.sella.it/api/v1/payment/capture/

Example request:

{
  "shopLogin":"",
  "amount":"",
  "currency":"",
  "bankTransactionID":"",
  "shopTransactionID":"",
  "paymentID":"",
  "settlementID":"",
  "fullFillment":{
    "fullFillmentlst":[{
      "status":"",
      "trackingCompany":"",
      "trackingNumbers":"",
      "trackingUrls":"",
      "message":"",
      "receipt":"",
      "productDetails":[{
        "productCode":"",
        "SKU":"",
        "name":"",
        "description":"",
        "quantity":"",
        "price":"",
        "unitPrice":"",
        "type":"",
        "vat":"",
        "discount":"",
        "requiresShipping":"",
        "condition":"",
        "seller":"",
        "category":"",
        "subCategory":"",
        "brand":"",
        "deliveryAt":""
        }
      ]
    }]
  }
}

Settle fully or partially an authorized transaction.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

Input Body:

(Fields in bold are mandatory)

Field Max Length Description
shopLogin 30 Your shop login
amount 9 The amount to capture
currency 3 ISO currency code
bankTransactionID 18 The bank transaction ID
shopTransactionID 50 the shop transaction ID
paymentID The payment ID
settlementID 20 Optional identifier of the settlement (max 20 characters)
FullFillment describes the items related to this capture.

Note: you must provide at least one of shopTransactionID, bankTransactionID, paymentID.

FillFillment contains a FullFillmentlst whose fields are:

parameter name description
status
  • success: the fulfillment was successful.
  • cancelled: the fulfillment was cancelled.
  • error: there was an error with the fulfillment request.
  • failure: the fulfillment request failed.
trackingCompany the name of the shipping company
trackingNumbers A list of shipping numbers, provided by the shipping company.
trackingUrls The URLs to track the fulfillment.
message Additional textual description regarding the fulfillment status.
receipt  Information about the Receipt
productDetails container object that contains info about the fulfilled item.

Here is a description of the children of productDetails:

parameter name description
productCode Article’s product Code
SKU Article’s Stock Keeping Unit
name Article’s name
description Article’s description
quantity The number of products
price Article’s price
unitPrice Article’s Unit price
type The type of article: digital , downloadable, physical,composite, event, travel
vat Value-Added Tax (the value of the tax)
discount
requiresShipping boolean, States whether or not the fulfillment requires shipping. This field is important for merchants dealing with digital goods.
condition Description of the physical condition of the item, mostly relevant for used items.
seller Details about the seller of the item, relevant for marketplace orders.
category The category of the item. For event tickets: the category of the event.
subCategory The sub-category of the item. For event tickets: the sub-category of the event.
brand The brand name of the item.
deliveryAt The planned delivery date of the product or item.

Response

Success Response:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{
    "transactionType":"capture",
    "transactionResult":"OK",
    "bankTransactionID":"{bankTransactionID}",
    "shopTransactionID":"{shopTransactionID}",
    "paymentID":"{paymentID}"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

payload details:

Field Description
transactionType Identifies the type of the transaction. For this method it will always be capture.
transactionResult OK for success, KO otherwise.
bankTransactionID A transaction ID assigned by the bank.
shopTransactionID An ID assigned by the shop.
paymentID Assigned by Axerve Ecommerce Solutions, identifies the payment.

POST payment/cancel

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/payment/cancel/

Production URL:

POST https://ecomms2s.sella.it/api/v1/payment/cancel/

Example request:

{
  "shopLogin" : "",
  "bankTransactionID":"",
  "shopTransactionID":"",
  "paymentID":"",
  "cancelReason": ""  
}

Deletes an authorized transaction.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

Request Body:

(Fields in bold are mandatory)

Field Max Length Description
shopLogin 30 Your shop login
bankTransactionID 18 The bank transaction ID
shopTransactionID 50 the shop transaction ID
paymentID The payment ID
cancelReason A description of the cancel reason

Note: you must provide at least one of shopTransactionID, bankTransactionID, paymentID.

Response

Success Response:
200 OK

{
  "error":{  
    "code":"0",
    "description":"request correctly processed"
  },
  "payload":{ 
    "transactionType" : "cancel", 
    "transactionResult" :"OK", 
    "bankTransactionID" : "{bankTransactionID}", 
    "shopTransactionID": "{shopTransactionID}", 
    "paymentID" : "{paymentID}" 
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
transactionType It will always be cancel
transactionResult OK or KO
bankTransactionID The bank transaction ID
shopTransactionID the shop transaction ID
paymentID The payment ID

POST payment/refund

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/payment/refund/

Production URL:

POST https://ecomms2s.sella.it/api/v1/payment/refund/

Request Body:

{
  "shopLogin":"",
  "bankTransactionID":"",
  "shopTransactionID":"",
  "paymentID":"",
  "settlementID":"",
  "amount":"",
  "currency":"",
  "chargeBackFraud":"",
  "refundReason":"",
  "orderDetails":{
    "ProductDetails": [
      {
        "productCode":"",
        "SKU":"",
        "name":"",
        "description":"",
        "quantity":"",
        "price":"",
        "unitPrice":"",
        "type":"",
        "vat":"",
        "discount":"",
        "requiresShipping":"",
        "condition":"",
        "seller":"",
        "category":"",
        "subCategory":"",
        "brand":"",
        "deliveryAt":""
      }
    ]
  }
}

Deletes, fully or partially, a settled transaction.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

Request Body:

(Fields in bold are mandatory)

Field Max Length Description
shopLogin 30 the merchant’s code
amount 9 the amount to refund
currency 3 currency ISO code
bankTransactionID 18 ID of the transaction assigned by Axerve Ecommerce Solutions
shopTransactionID 50 shop transaction ID value
paymentID The payment ID
settlementID 20 Optional identifier of the settlement (max 20 characters)
refundReason a free-text reason for the refund. Used with fraud protection.
chargeBackFraud Flag for risk:
  • TRUE - chargeback for fraud
  • FALSE - chargeback not for a fraud
orderDetail.productDetails in case you are using Klarna, fill this fields with info about the products that are refunded. A description of this field is in OrderDetails.

Note: you must provide at least one of shopTransactionID, bankTransactionID, paymentID.

Response

Success Response:
200 OK

{
  "error":{  
    "code":"0",
    "description":"request correctly processed"
  },
  "payload":{
    "transactionType":"refund",
    "transactionResult":"OK",
    "bankTransactionID":"{bankTransactionID}",
    "shopTransactionID":"{shopTransactionID}",
    "paymentID":"{paymentID}"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
transactionType always refund for this operation
transactionResult OK ok KO
bankTransactionID ID of the transaction assigned by Axerve Ecommerce Solutions
shopTransactionID shop transaction ID value
paymentID The payment ID

Shop API

With this endpoint the merchant is able to modify many settings regarding his account.

GET shop/environment

Sandbox URL:

GET https://sandbox.gestpay.net/api/v1/shop/environment/{shopLogin}

Production URL:

GET https://ecomms2s.sella.it/api/v1/shop/environment/{shopLogin}

Retrieves the current enviroment (SANDBOX / LIVE).

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

URL parameter:

Parameter Description
shopLogin The shop identifier.

Response

Success response example:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{    
     "environment":"SANDBOX" 
    }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
environment LIVE or SANDBOX

GET shop/language

Sandbox URL:

GET https://sandbox.gestpay.net/api/v1/shop/language/{shopLogin}

Production URL:

GET https://ecomms2s.sella.it/api/v1/shop/language/{shopLogin}

Retrieves the current language.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

URL parameter:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.

Response

Success response example:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{
     "language": "Italian"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

The response contains the language set for Axerve Ecommerce Solutions.

Response payload details:

Field Description
language One of Italian, English

POST shop/language

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/shop/language

Production URL:

POST https://ecomms2s.sella.it/api/v1/shop/language

Request body:

{
  "shopLogin":"",
  "language":"{Italian/English}"
}

Sets the language used by Axerve Ecommerce Solutions.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

request body details:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.
language The language to set. Currently accepted values are Italian and English.

Response

Success response example:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{
     "result": "OK"
     "language": "Italian"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

The response contains the language set for Axerve Ecommerce Solutions.

Response payload details:

Field Description
result The outcome of the operation: OK of KO
language the language just set

GET shop/moto

Sandbox URL:

GET https://sandbox.gestpay.net/api/v1/shop/moto/{shopLogin}

Production URL:

GET https://ecomms2s.sella.it/api/v1/shop/moto/{shopLogin}

Returns the MOTO setting for the shopLogin.

Read more about MOTO settings in Axerve Ecommerce Solutions.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

URL parameter:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.

Response

Success Response:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{
    "moto":[
      {
        "paymentType":"CREDITCARD",
        "capture":"separated",
        "automaticBehaviour":{
          "type":"capture",
          "days":"25"
        }
      },
      {
        "paymentType":"PAYPAL",
        "capture":"unified",
        "automaticBehaviour":{
          "type":"",
          "days":""
        }
      }
    ]
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

The response can contain zero or more items in the moto array.

Response payload.moto details:

Field Description
paymentType the payment type for wich a MOTO property is set
capture separated or unified
automaticBehaviour.type capture or delete.
automaticBehaviour.days the number of days set.

POST shop/moto

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/shop/moto

Production URL:

POST https://ecomms2s.sella.it/api/v1/shop/moto

Request Body:

{
  "shopLogin":"",
  "paymentType":"",
  "capture":"{separated/unified}",
  "automaticBehaviour":{
    "type":"{capture/delete}",
    "days":""
  }
}

Modifies the MOTO setting.

Read more about MOTO settings in Axerve Ecommerce Solutions.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

Request Body:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop login code.
paymentType One of the enabled payment types for your shop. A list of all payment types is available here.
capture separated if you want to only authorize a transaction and later capture; unified if you want to authorize and capture at the same time.
automaticBehaviour.type If the capture is set to separated, this field defines what happens after X days: capture the amount or delete the transaction.
automaticBehaviour.days the days after whom the transaction will be captured or deleted, based on the previous setting.

Response

Success Response:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{
    "result":"OK",
    {
      "paymentType":"CREDITCARD",
      "capture":"unified",
      "automaticBehaviour":{
        "type":"",
        "days":""
      }
    }
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
result OK ok KO
paymentType the payment type updated
capture separated or unified

if capture is set to separated:

Field Description
automaticBehaviour.type capture or delete.
automaticBehaviour.days the number of days set.

GET shop/paymentMethods

Sandbox URL:

GET https://sandbox.gestpay.net/api/v1/shop/methods/{shopLogin}

Production URL:

GET https://ecomms2s.sella.it/api/v1/shop/methods/{shopLogin}

Retrieves a list of payment methods enabled indicating name, payment type, related logo (URL), related mobile logo (URL), if the method is visible/hidden in the payment page.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

URL parameter:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.

Response

Success response example:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{  
    "paymentMethod":[  
      {  
        "name":"VISA VBV",
        "logo":{  
          "large":"https://{domain}/logos/VisaVBV_Large.png",
          "mobile":"https://{domain}/logos/VisaVBV_mobile.png",
          "vector":"https://{domain}/logos/VisaVBV.svg"
        },
        "paymentType":"CREDITCARD",
        "paymentPage":"visible"
      },
      {  
        "name":"MASTERCARD SECURECODE",
        "logo":{  
          "large":"https://{domain}/logos/MastercardSecurecode_Large.png",
          "mobile":"https://{domain}/logos/MastercardSecurecode_mobile.png",
          "vector":"https://{domain}/logos/MastercardSecurecode.svg"
        },
        "paymentType":"CREDITCARD",
        "paymentPage":"visible"
      },
      {  
        "name":"PayPal",
        "logo":{  
          "large":"https://{domain}/logos/PayPal_Large.png",
          "mobile":"https://{domain}/logos/PayPal_mobile.png",
          "vector":"https://{domain}/logos/PayPal.svg"
        },
        "paymentType":"PAYPAL",
        "paymentPage":"visible"
      }
    ]
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

The response contains the language set for Axerve Ecommerce Solutions.

Response payload details:

Field Description
paymentMethod An array of payment methods
paymentMethod.name The name of the payment method
paymentMethod.logo Contains URLs for the payment method’s logo in three formats: large, mobile, vector
paymentMethod.paymentType The payment method code.
paymentMethod.paymentPage returns visibile if the paymentType is shown on the payment page; hidden otherwise.

POST shop/paymentMethods

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/shop/methods/

Production URL:

POST https://ecomms2s.sella.it/api/v1/shop/methods/

Request body:

{  
  "shopLogin":"",
  "paymentType":"{paymentType}",
  "paymentPage":"{visible/hidden}"
}

Allows to show/hide the payment method on payment page.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

request body details:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.
paymentType One of the payment types supported by Axerve Ecommerce Solutions.
paymentPage set to visible to show the payment type on the payment page; hidden to hide.

Response

Success response example:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{  
    "result":"OK",
    "paymentType":"CREDITCARD",
    "paymentPage":"visible"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

The response contains the language set for Axerve Ecommerce Solutions.

Response payload details:

Field Description
result The outcome of the operation: OK of KO
paymentType The payment type selected
paymentPage The value set for the payment page: visible or hidden

GET shop/paymentPage

Sandbox URL:

GET https://sandbox.gestpay.net/api/v1/shop/paymentPage/{shopLogin}

Production URL:

GET https://ecomms2s.sella.it/api/v1/shop/paymentPage/{shopLogin}

Retrieves the current text or URL for the Logo, the default language, and the URL that will display the preview of the payment page.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

URL parameter:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.

Response

Success response example:
200 OK

{
  "error": {
    "code": "0",
    "description": "request correctly processed"
  },
  "payload": {
    "logo": [{
      "language": "ITALIAN",
      "imageURL": {
        "href": "http://yourdomain/img/yourlogo.png"
      },
      "altText": ""
    },{
      "language": "ENGLISH",
      "imageURL": {
        "href": "http://yourdomain/img/yourlogo.png"
      },
      "altText": ""
    },{
      "language": "SPANISH",
      "imageURL": {
        "href": "http://yourdomain/img/yourlogo.png"
      },
      "altText": ""
    },{
      "language": "GERMAN",
      "imageURL": {
        "href": "http://yourdomain/img/yourlogo.png"
      },
      "altText": "YOUR TEXT"
    },{
      "language": "FRENCH",
      "imageURL": {
        "href": "http://yourdomain/img/yourlogo.png"
      },
      "altText": "YOUR TEXT"
    }],
    "defaultLang": "ENGLISH" 
  } 
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

The response contains the language set for Axerve Ecommerce Solutions.

Response payload details:

Field Description
logo an array of logo objects, one per language.
logo.language The language for this particular logo
logo.imageURL.href A URL for the logo
logo.altText The text to show for alternative readers, textual browsers, etc.
defaultLang the default language for the payment page

POST shop/paymentPage

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/shop/paymentPage/

Production URL:

POST https://ecomms2s.sella.it/api/v1/shop/paymentPage/

Request body:

{
  "shoplogin":"",
  "logo":[
    {
      "language":"",
      "imageURL":{
        "href":""
      },
      "altText":""
    }
  ],
  "defaultLang":""
}

Sets a new Logo URL or Text and a default language.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

request body details:

(Fields in bold are mandatory)

Field Description
shopLogin The shop login code.
logo an array of logo objects, one per language.
logo.language The language for this particular logo
logo.imageURL.href A URL for the logo
logo.altText The text to show for alternative readers, textual browsers, etc.
defaultLang the default language for the payment page

Response

Success response example:
200 OK

{
  "error":{
    "code":"0",
    "description":"request correctly processed"
  },
  "payload":{
    "result":"OK",
    "logo":[
      {
        "language":"ITALIAN",
        "imageURL":{
          "href":"http://yourdomain/img/yourlogo.png"
        },
        "altText":""
      },
      {
        "language":"ENGLISH",
        "imageURL":{
          "href":"http://yourdomain/img/yourlogo.png"
        },
        "altText":""
      },
      {
        "language":"SPANISH",
        "imageURL":{
          "href":"http://yourdomain/img/yourlogo.png"
        },
        "altText":""
      },
      {
        "language":"GERMAN",
        "imageURL":{
          "href":""
        },
        "altText":"your NEW TEXT"
      },
      {
        "language":"FRENCH",
        "imageURL":{
          "href":""
        },
        "altText":"YOUR New TEXT"
      }
    ],
    "defaultLang":"ENGLISH"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

The response contains the language set for Axerve Ecommerce Solutions.

Response payload details:

Field Description
result OK for success, KO for error.
logo an array of logo objects, one per language.
logo.language The language for this particular logo
logo.imageURL.href A URL for the logo
logo.altText The text to show for alternative readers, textual browsers, etc.
defaultLang the default language for the payment page

POST shop/token

Sandbox URL:

POST https://sandbox.gestpay.net/api/v1/shop/token/

Production URL:

POST https://ecomms2s.sella.it/api/v1/shop/token/

Request Body:

{  
  "shopLogin":"",
  "requestToken": "{MASKEDPAN/Customtoken}",
  "creditCard": {
    "number": "",
    "token": "",
    "expMonth": "", 
    "expYear": "", 
    "CVV": ""
  },
  "withAuth": "{True/False}"
}

Requests a Credit Card Token or update an existing Credit Card Token.

Request

Use one of the following headers to authenticate:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.
paymentToken {paymentToken} A payment token received during the payment process

Request Body:

(Fields in bold are mandatory)

Parameter Description
shopLogin the merchant’s code
requestToken MASKEDPAN for a Standard Token; any other value for Custom Token
creditCard.number The credit card number
creditCard.token A token representation of the card. Set a value to modify an existing token. Mandatory to update an existing token.
creditCard.expMonth The expiry month
creditCard.expYear The exipry year
creditCard.CVV The CVV code
withAuth tries to verify the authenticity of the card with the circuit; does NOT authorize the token. Only working in production environment.
True or False (default)

Response

Success response example:
200 OK

{
  "error":{  
    "code":"0",
    "description":"request correctly processed"
  },
  "payload": {
    "transactionType":"{REQUESTTOKEN/UPDATETOKEN}",
    "transactionResult":"OK",
    "authorizationResult":"OK",
    "authorizationErrorCode":"0",
    "authorizationCodeDescription":"Transaction correctly processed",
    "country":"ITALIA",
    "countryCode":"380",
    "cvv":"OK",
    "cvvDescription":"CVV VALID",
    "issuerCountry":"ITALIA",
    "issuerCountryCode:":"380",
    "company":"MASTERCARD",
    "companyCode":"3",
    "commercial":"N",
    "productDescription":"Standard MasterCard® Card",
    "productType":"Credit",
    "checkDigit":"OK",
    "checkDigitDescription":"CheckDigit VALID",
    "expiryDate":"OK",
    "expiryDateDescription":"DATE VALID",
    "3DS":"Y",
    "3DSdDescription":"ENROLLED",
    "prepaid":"N",
    "cardBIN": "541238",
    "token":"541238AFAGHA1118",
    "tokenExpiryMonth":"01",
    "tokenExpiryYear":"21"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
transactionType REQUESTTOKEN if creating, UPDATETOKEN on updating
transactionResult OK or KO
authorizationErrorCode authorisation error code if an error occurred
authorizationResult Authorization result. It can be OK or KO
authorizationCodeDescription code description
country nationality of the card
countryCode nationality code of the card
cvv result of the check CVV. It can be OK or KO or NULL
cvvDescription description of CVV check results
issuerCountry nationality of the card issuer
issuerCountryCode nationality code of the card issuer
company Description of the Card company
companyCode Code of the Company
commercial Flag that indicates if the Card is commercial or not. Y or N
productDescription Description of the product linked to the card
productType type of the product: Credit or Debit
checkDigit OK or KO, acording to the check digit of the card
checkDigitDescription description of the check digit response
expiryDate OK if it’s valid; KO otherwise
expiryDateDescription A textual description of the expiryDate field
3DS 3D Secure enabled:
  • Y enabled
  • N not enabled
  • U could not verify
  • E error: could not contact the credit card company
3DSdDescription enrolment description
prepaid indicates if the card is prepaid of not (Y, N, or empty)
cardBIN first 6 numbers of the credit card, that identify the credit card issuer bank.
token the token value
tokenExpiryMonth the token expiry month
tokenExpiryYear the token expiry year

GET shop/version

Sandbox URL:

GET https://sandbox.gestpay.net/api/v1/shop/version/{shopLogin}

Production URL:

GET https://ecomms2s.sella.it/api/v1/shop/version/{shopLogin}

Retrieves the current merchant version: Starter, Professional, Unlimited.

Request

Headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

URL parameter:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.

Response

Success response example:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{
     "version": "Unlimited"
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

The response contains the Axerve Ecommerce Solutions version for this shop.

Response payload details:

Field Description
version One of Starter, Professional, Unlimited.

GET shop/token

Sandbox URL:

GET https://sandbox.gestpay.net/api/v1/shop/token/{shopLogin}

Production URL:

GET https://ecomms2s.sella.it/api/v1/shop/token/{shopLogin}

Retrieves the token list

Request

To authorize, use one of the followng headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

URL parameter:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.

Response

Success response example:
200 OK

{
   "error":{  
      "code":"0",
      "description":"request correctly processed"
   },
   "payload":{    
      "tokens":["444445GFDRBH4448","444425GFSRBH4448"] 
    }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
tokens An array containing all the tokens created for this shop.

DELETE shop/token

Sandbox URL:

DELETE https://sandbox.gestpay.net/api/v1/shop/token/{shopLogin}/{token}

Production URL:

DELETE https://ecomms2s.sella.it/api/v1/shop/token/{shopLogin}/{token}

Deletes a Token for this shop.

Request

To authorize, use one of the followng headers:

Header Value Description
Authorization apikey {merchant Api Key} The merchant API key can be found in Axerve Merchant Back-Office.

URL parameter:

(Fields in bold are mandatory)

Parameter Description
shopLogin The shop identifier.
token the token you want to delete.

Response

Success response example:
200 OK

{
  "error":{  
    "code":"0",
    "description":"request correctly processed"
  },
  "payload":{
    "result":"OK",
    "token":"444445DHGSJA1111" 
  }
}

See the section Handling responses & errors to learn how Axerve Ecommerce Solutions reports errors.

Response payload details:

Field Description
result OK or KO
token The just deleted token

Alternative Payments Examples

Example: Alipay

Alipay example - POST payment/create:

{  
  "shopLogin":"{{shopLogin}}",
  "amount":"1",
  "currency":"EUR",
  "shopTransactionID":"TEST",
  "languageId":"",
  "paymentType":["S2PALI"],
  "orderDetails":{  
      "customerDetail":{  
        "primaryEmail":""
      },
    "ProductDetails": [{
        "ProductCode": "135798642",
        "SKU": "AB-333222-WFG-4",
        "Name": "Porche Carrera scale model",
        "Description": "Porche Carrera scale model",
        "Quantity": "1",
        "Price": "50.5",
        "UnitPrice": "50.5",
        "Type": "1",
        "Vat": "22",
        "Category": "Scale Models",
        "Subcategory": "cars",
        "Brand": "LittleCars",
        "RequiresShipping": "true",
        "DeliveryAt": "2017-12-29",
        "Condition": "new"
      },
      {
        "ProductCode": "135798642",
        "SKU": "AB-333222-WFG-5",
        "Name": "Ferrari scale model",
        "Description": "Ferrari scale model",
        "Quantity": "1",
        "Price": "50.5",
        "UnitPrice": "50.5",
        "Type": "1",
        "Vat": "22",
        "Category": "Scale Models",
        "Subcategory": "cars",
        "Brand": "LittleCars",
        "RequiresShipping": "true",
        "DeliveryAt": "2017-12-29",
        "Condition": "new"
      }
    ]
  }
}

Alipay does not need any mandatory parameters. Just specify the PaymentType S2PALI and the payment page will show to your user.

If you specify the PrimaryEmail in the OrderDetails tag, you will redirect your user to Alipay payment page where some fields are already filled.

January 2019 breaking changes

If you are using Alipay via Ecommerce you need to update your integration because from 21/01/2019 more mandatory fields will be required from Alipay.

The new mandatory fields are ProductDetail: you need to add one field for each item in the cart with the product name and the quantity. All these fields must me wrapped inside a ProductDetails tag.

Other product information like the product code and its price are optional. Keep in mind that the total must be exactly the sum of all items’ prices.

Example: Amazon Pay

Amazon Pay example - POST payment/submit:

{
  "shopLogin": "{{shopLogin}}",
  "paymentType": "AMAZONPAY",
  "buyer": {
    "name": "test",
    "email": "+test@test.com"
  }
}

Recurring payments with Amazon Pay

Amazon Pay Recurring Payments example - POST payment/create:

{
  "shopLogin": "{{shopLogin}}",
  "amount": "0.01",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "languageId": "1",
  "paymentType": ["AMAZONPAY"],
  "amazonDescription":"paynowandrecurring"
}

If you want to perform recurring payments, by filling this field in payment/create you obtain a token that you can use with payment/submit.

Accepted values for amazonDescription:

Value Description
Empty or missing no token is returned.
paynowandrecurring a payment is performed instantly and a token is generated for subsequent payments.
onlyrecurring only a token is returned.

Amazon Pay Submit example - POST payment/submit:

{
  "shopLogin": "{{shopLogin}}",
  "paymentType": "AMAZONPAY",
  "buyer": {
    "name": "test",
    "email": "+test@test.com"
  },
  "paymentTypeDetails": {
    "amazonPay":{  
      "token":"AZRPHAIL0YEFTDQ7"
    }
  }
}

If you implement AmazonPay in your shop by using Amazon widgets for address and cards, you can finalize the call by calling payment/submit

Use AMAZONPAY for the paymentType and send the Amazon Order Reference ID in the amazonReferenceOrderId field.

Amazon Pay Submit example - POST payment/submit:

{
  "shopLogin": "{{shopLogin}}",
  "paymentType": "AMAZONPAY",
  "buyer": {
    "name": "test",
    "email": "+test@test.com"
  },
  "paymentTypeDetails": {
    "amazonPay":{  
      "amazonReferenceOrderId":"S02-6393286-1135021"
    }
  }
}

The shopTransactionId in payment/create must be unique.

Example: Apple Pay

Apple Pay example - POST payment/submit:

{
  "shopLogin": "{{shopLogin}}",
  "paymentType": "APPLEPAY",
  "paymentTypeDetails": {
    "applePay": {
      "PKPaymentToken": {
        "paymentData": {
          "data": "Q0tfx6QzXdxMndMiDSJWxs...",
          "signature": "MIAGCSqGSIb3DQEHAqCAMIACA...",
          "header": {
            "publicKeyHash": "b9OHKov...",
            "ephemeralPublicKey": "MFkwE...",
            "transactionId": "840cefb..."
          },
          "version": "EC_v1"
        },
        "transactionIdentifier": "3220840CFB...",
        "paymentMethod": {
          "network": "Visa",
          "type": "debit",
          "displayName": "Visa 0492"
        }
      }
    }
  }
}

Please read the detailed setup process for Apple Pay in the docs. Once you have received a Payment Token Package, you can call callPagamS2S with the relevant data. Note that, if using Apple Pay, no Credit Card or Token data are needed. For a real example of Payment Token Package, contained in PKPaymentToken, click here.

The most important field in this process is PKPaymentToken. Here is a description:

Name Type Description
PKPaymentToken string Contains a UTF-8 serialization of a plain-text JSON dictionary..

Once you have submitted payment/submit, Axerve Ecommerce Solutions will behave exactly as usual and your payment will be processed.

Example: BancomatPay

BancomatPay example - POST payment/create:

{  
  "shopLogin": "{{shopLogin}}",
  "amount": "1",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "languageId": "",
  "paymentType": ["BANCOMATPAY"],
  "paymentTypeDetail": {
    "BancomatPay":{  
      "phoneNumber":"+3935......"
    }
  }
}

You must use BANCOMATPAY as paymentType.

Example: Consel

Consel example - POST payment/create:

{
  "shopLogin": "{{shopLogin}}",
  "amount": "2500",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "languageId": "1",
  "paymentType": [
    "CONSEL"
  ],
  "ConselMerchantPro": "WIN",
  "ConselCustomerInfo": {
    "Surname": "Rossi",
    "Name": "Mario",
    "TaxationCode": "RSSMRA70D23H501H",
    "Address": "Via Torino",
    "City": "Roma",
    "StateCode": "RM",
    "DateAddress": "",
    "Phone": "06321111",
    "MobilePhone": "3313333333"
  }
}

More information about Consel (Sella Personal Credit) can be found in the documentation.

Name Max Length Description
ConselMerchantPro 3 Merchant Promotional Code, mandatory to display Consel in the Payment Method list.
ConselCustomerInfo Wrapper for Consel tags.
Surname 30 Customer Surname.
Name 30 Customer Name.
TaxationCode 30 Customer Taxation Code.
Address 30 Customer Address.
City 30 Customer City.
StateCode 30 Customer State Code.
DateAddress 30 Date since the customer has lived in the declared address (dd/mm/yyyy).
Phone 30 Customer Phone.
MobilePhone 30 Customer Mobile phone.

Example: EPS

EPS example - POST payment/create:

{  
  "shopLogin": "{{shopLogin}}",
  "amount": "1",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "languageId": "1",
  "paymentType": ["S2PEPS"]
}

EPS does not need mandatory parameters. You must use S2PEPS as paymentType.
More information about EPS can be found in the documentation.

Example: Giropay

Giropay example - POST payment/create:

{  
  "shopLogin": "{{shopLogin}}",
  "amount": "1",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "languageId": "1",
  "paymentType": ["S2PGIR"]
}

Giropay does not need mandatory parameters. You must use S2PGIR as paymentType. More information about Giropay can be found in the documentation.

Example: Klarna

Klarna example - POST payment/create:

{
  "shopLogin": "{{shopLogin}}",
  "amount": "10",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "paymentType": [
    "KLARNA"
  ],
  "OrderDetails": {
    "CustomerDetail": {
      "ProfileID": "",
      "MerchantCustomerID": "",
      "FirstName": "Joel",
      "MiddleName": "",
      "Lastname": "Kinnaman",
      "PrimaryEmail": "jkinnaman@axerve.com",
      "SecondaryEmail": "",
      "HomePhone": "+443333333333",
      "SecondaryPhone": "",
      "DateOfBirth": "",
      "Gender": "",
      "SocialSecurityNumber": "410321-9202",
      "Company": ""
    },
    "BillingAddress": {
      "ProfileID": "",
      "FirstName": "",
      "MiddleName": "",
      "Lastname": "",
      "StreetNumber": "1",
      "StreetName": "Stargatan",
      "Streetname2": "",
      "HouseNumber": "1",
      "HouseExtention": "A",
      "City": "Regensburg",
      "ZipCode": "93053",
      "State": "",
      "CountryCode": "DE",
      "Email": "",
      "PrimaryPhone": "",
      "SecondaryPhone": ""
    },
    "ProductDetails": [
      {
        "ProductCode": "5",
        "Name": "Phone",
        "Quantity": "1",
        "Price": "5",
        "Type": "5",
        "Vat": "0",
        "Discount": "0"
      },
      {
        "ProductCode": "8",
        "Name": "Shirt",
        "Quantity": "1",
        "Price": "5",
        "Type": "5",
        "Vat": "0",
        "Discount": "0"
      }
    ]
  }
}

Klarna requires these parameters as mandatory, children of OrderDetails:

Name Max Length Description
BillingAddress.StreetName 100 Shipping street name. Accepts only alpha-numeric characters.
BillingAddress.City 50 Shipping city name.
BillingAddress.ZipCode 50 Shipping zip code.
BillingAddress.CountryCode 2 One of: AT, BE, CH, DK, FI, DE, IT, ES, NL, NO, SE.
ProductDetails.ProductDetail The list of ordered products.

We strongly suggest you read these notes on BillingAddress and ShippingAddress.
StreetName and StreetNumber, either in BillingAddress or ShippingAddress, must contain only alphanumeric characters.

If you send the following fields, your customer will find them already filled:

Name Max Length Description
CustomerDetail.FirstName 65 Customer First Name.
CustomerDetail.Lastname 65 The list of ordered products.
CustomerDetail.PrimaryEmail 100 Customer primary email.
CustomerDetail.PrimaryPhone 100 Customer’s phone including prefix. See below on how to use it.
CustomerDetail.SocialSecurityNumber 20 Customer’s social or fiscal identifier (for Klarna Use)
BillingAddress.StreetNumber 5 Shipping Street Number. Accepts only numbers.

PrimaryPhone must follow these rules:

ProductDetails can have one or more ProductDetail. Here is a description of its fields:

Name Max Length Description
ProductCode 12 The article’s product Code.
SKU 50 The article’s Stock Keeping Unit.
Name 100 The article’s name.
Description 255 The article’s description.
Quantity 3 The number of products.
Price 12 The article’s price.
UnitPrice 12 The article’s Unit Price.
Type 2 The type of article: visit the klarna page in the docs to set the right value.
Vat 2 Value-Added Tax (the value of the tax).
Discount 2 The amount offered by you as discount, in percentage. For example, 10 means 10% and it is subtracted to the price.

Please note:

More details about Klarna are in the documentation.

Example: Konbini

Konbini example - POST payment/create:

{  
  "shopLogin": "{{shopLogin}}",
  "amount": "1",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "languageId": "1",
  "paymentType": ["S2PKON"]
}

Konbini does not need mandatory parameters.
You must use S2PKON as paymentType.
If you pass the PrimaryEmail tag, the customer will be redirected directly to the payment page.

More information about Konbini can be found in the documentation.

Example: MercadoPago

MercadoPago example - POST payment/create:

{
  "shopLogin": "{{shopLogin}}",
  "amount": "1",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "languageId": "1",
  "paymentType": [
    "S2PMER"
  ],
  "orderDetails": {
    "customerDetail": {
      "primaryEmail": ""
    },
    "billingAddress": {
      "profileID": "",
      "firstName": "Vercinge",
      "lastname": "Torige",
      "streetName": "via",
      "streetname2": "",
      "houseNumber": "",
      "houseExtention": "",
      "city": "mexico city",
      "zipCode": "11111",
      "state": "MX",
      "countryCode": "MX",
      "email": "torige@email.com",
      "primaryPhone": "01111111111",
      "secondaryPhone": "",
      "company": "",
      "stateCode": ""
    },
    "ProductDetails": [
      {
        "ProductCode": "135798642",
        "SKU": "AB-333222-WFG-4",
        "Name": "Porche Carrera scale model",
        "Description": "Porche Carrera scale model",
        "Quantity": "1",
        "Price": "50.5",
        "UnitPrice": "50.5",
        "Type": "1",
        "Vat": "22",
        "Category": "Scale Models",
        "Subcategory": "cars",
        "Brand": "LittleCars",
        "RequiresShipping": "true",
        "DeliveryAt": "2017-12-29",
        "Condition": "new"
      },
      {
        "ProductCode": "135798642",
        "SKU": "AB-333222-WFG-5",
        "Name": "Ferrari scale model",
        "Description": "Ferrari scale model",
        "Quantity": "1",
        "Price": "50.5",
        "UnitPrice": "50.5",
        "Type": "1",
        "Vat": "22",
        "Category": "Scale Models",
        "Subcategory": "cars",
        "Brand": "LittleCars",
        "RequiresShipping": "true",
        "DeliveryAt": "2017-12-29",
        "Condition": "new"
      }
    ]
  }
}

MercadoPago requires the parameter BillingAddress.CountryCode, children of OrderDetails:

Name Max Length Description
BillingAddress.CountryCode 2 One of: BR, MX, CO.

You must use S2PMER as paymentType.

More information about MercadoPago can be found in the documentation.

Example: Multibanco

Multibanco example - POST payment/create:

{  
  "shopLogin": "{{shopLogin}}",
  "amount": "1",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "languageId": "1",
  "paymentType": ["S2PMUL"]
}

Multibanco does not need mandatory parameters. You must use S2PMUL as paymentType. More information about Giropay can be found in the documentation.

Example: MyBank

MyBank example - POST payment/submit:

{  
  "shopLogin": "{{shopLogin}}",
  "paymentType": "MYBANK",
  "buyer": {
    "name": "test",
    "email": "test@test.com"
  },
  "paymentTypeDetails": {
    "myBank":{  
      "bankCode": "CT000026"
    }
  }
}

If you choose to let your users pay with MyBank, you have to compile two other fields.
More details can be found in the MyBank page.

Name Max Length Description
paymentTypeDetail container of myBank section
bankCode 25 Tag to set the Bank to show on payment page (the bank List is retrieved from WsS2S.CallMyBankListS2S)

Example: Paypal

Paypal example - POST payment/submit:

{
  "shopLogin": "{{shopLogin}}",
  "paymentType": "PAYPAL"
}

Enabling Paypal

If you only specify PAYPAL payment type, Axerve Ecommerce Solutions won’t show the payment page but will redirect directly to Paypal’s payment page. A detailed description of Axerve Ecommerce Solutions’ integration with Paypal can be found in the documentation.

Paypal Seller Protection

Paypal Seller Protection example - POST payment/create:

{
  "shopLogin": "{{shopLogin}}",
  "amount": "0.01",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "buyerName": "Test",
  "buyerEmail": "test@test.com",
  "languageId": "1",
  "ppSellerProtection": "1",
  "paymentType": [
    ""
  ],
  "shippingDetails": {
    "shipToName": "leo",
    "shipToStreet": "via milano 1",
    "shipToState": "BI",
    "shipToCountryCode": "IT",
    "shipToZip": "19199",
    "shipToCity": "TORINO",
    "shipToStreet2": ""
  }
}

For more information, check out the “PayPal Seller Protection” section of the Paypal Docs.

If you want to activate Paypal Seller Protection you must:

Name Max Length Description
ppSellerProtection 1 Parameter to set the use of a confirmed addresses.

Paypal recurring payments

In this way you can activate recurring payments on Paypal. Note that no paymentType is needed.

Paypal Recurring Payments example - POST payment/create:

{
  "shopLogin": "{{shopLogin}}",
  "amount": "0.01",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "buyerName": "Test",
  "buyerEmail": "test@test.com",
  "languageId": "1",
  "payPalDescription": "testppfulvio",
  "paymentType": [""],
  "shippingDetails": {  
    "shipToName": "marco",
    "shipToStreet": "via milano 1",
    "shipToState": "BI",
    "shipToCountryCode": "IT",
    "shipToZip": "19199",
    "shipToCity": "TORINO",
    "shipToStreet2": ""
  }
}

A Buyer will be able to subscribe a Billing Agreement on PayPal0s website so authorizing the Merchant to debit his/her PayPal account in future transactions.

To use PayPal Reference Transaction it’s necessary to fill the PayPalBillingAgreementDescription tag that can be present or not (in case of a normal PayPal payment it will be left empty or not passed at all).

Name Max Length Description
payPalDescription 127 Description of the goods, terms and conditions of the billing agreement.

The Encryption service, if the payPalDescription field is present and not empty, assumes that the payment method is PayPal (so the paymentType field in this case is not mandatory: if present it must be valued PAYPAL).

This tag has to be filled with description of the goods, terms and conditions of the billing agreement.

When using PayPal Billing Agreement, you will get a Token to use later with the payment/submit service.

Using a Paypal token

Paypal Using a Token example - POST payment/submit:

{
  "shopLogin": "{{shopLogin}}",
  "paymentType": "PAYPAL",
  "paymentTypeDetails": {
    "payPal": {
      "token": "PPT2PDODGBPO4H3U"
    }
  }
}

See the “Using a Token” example on the right side of this page.

Example: Paysafecard

Paysafecard example - POST payment/create:

{  
  "shopLogin": "{{shopLogin}}",
  "amount": "1",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "languageId": "1",
  "paymentType": ["S2PPSC"]
}

Paysafecard does not need mandatory parameters.
You must use S2PPSC as paymentType.

More information about Paysafecard can be found in the documentation.

Example: Przelewy24

Przelewy24 example - POST payment/create:

{
  "shopLogin": "{{shopLogin}}",
  "amount": "1",
  "currency": "EUR",
  "shopTransactionID": "TEST_OK",
  "languageId": "",
  "paymentType": [
    "PRZELEWY24"
  ],
  "orderDetails": {
    "customerDetail": {
      "primaryEmail": ""
    },
    "billingAddress": {
      "profileID": "",
      "firstName": "Vercinge",
      "lastname": "Torige",
      "streetName": "via",
      "streetname2": "",
      "houseNumber": "",
      "houseExtention": "",
      "city": "Cracovia",
      "zipCode": "11111",
      "state": "PL",
      "countryCode": "PL",
      "email": "torige@email.com",
      "primaryPhone": "01111111111",
      "secondaryPhone": "",
      "company": "",
      "stateCode": ""
    },
    "ProductDetails": [
      {
        "ProductCode": "135798642",
        "SKU": "AB-333222-WFG-4",
        "Name": "Porche Carrera scale model",
        "Description": "Porche Carrera scale model",
        "Quantity": "1",
        "Price": "50.5",
        "UnitPrice": "50.5",
        "Type": "1",
        "Vat": "22",
        "Category": "Scale Models",
        "Subcategory": "cars",
        "Brand": "LittleCars",
        "RequiresShipping": "true",
        "DeliveryAt": "2017-12-29",
        "Condition": "new"
      },
      {
        "ProductCode": "135798642",
        "SKU": "AB-333222-WFG-5",
        "Name": "Ferrari scale model",
        "Description": "Ferrari scale model",
        "Quantity": "1",
        "Price": "50.5",
        "UnitPrice": "50.5",
        "Type": "1",
        "Vat": "22",
        "Category": "Scale Models",
        "Subcategory": "cars",
        "Brand": "LittleCars",
        "RequiresShipping": "true",
        "DeliveryAt": "2017-12-29",
        "Condition": "new"
      }
    ]
  }
}

Przelewy24 does not need mandatory parameters.
You must use PRZELEWY24 as paymentType.

More information about Przelewy24 can be found in the documentation.

Example: Satispay

Satispay example - POST payment/create:

{  
  "shopLogin": "{{shopLogin}}",
  "amount": "1",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "languageId": "1",
  "paymentType": ["SATISPAY"]
}

Satispay does not need mandatory parameters.
You must use SATISPAY as paymentType.

More information about Satispay can be found in the documentation.

Example: Sofort

Sofort example - POST payment/create:

{  
  "shopLogin": "{{shopLogin}}",
  "amount": "1",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "languageId": "1",
  "paymentType": ["S2PSOF"]
}

You must use S2PSOF as paymentType.
Sofort does not need mandatory parameters, but if you send the following parameters, you will jump straight to the Sofort payment page without authenticating. All these fields are children of OrderDetails.

Name Max Length Description
CustomerDetail.FirstName 65 Customer First Name.
CustomerDetail.Lastname 65 Customer Last name.
CustomerDetail.PrimaryEmail 100 Customer primary email.
BillingAddress.CountryCode 2 Alpha-2 code. For example, use US for USA.

Example: UnionPay

UnionPay example - POST payment/create:

{
  "shopLogin": "{{shopLogin}}",
  "amount": "1",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "languageId": "",
  "paymentType": [
    "S2PUNI"
  ],
  "orderDetails": {
    "customerDetail": {
      "primaryEmail": "test@test.com"
    }
  }
}

You must use S2PUNI as paymentType.
UnionPay does not need mandatory parameters. However, if you send the PrimaryEmail and PrimaryPhone fields in the OrderDetails tag, you will jump straight to the UnionPay payment page; otherwise, an intermediary page asking for the email address is shown.

Example: WebMoney

WebMoney example - POST payment/create:

{  
  "shopLogin": "{{shopLogin}}",
  "amount": "1",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "languageId": "1",
  "paymentType": ["S2PWMO"]
}

WebMoney does not need mandatory parameters.
You must use S2PWMO as paymentType.

More information about WebMoney can be found in the documentation.

Example: WeChat

WeChat example - POST payment/create:

{  
  "shopLogin": "{{shopLogin}}",
  "amount": "1",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "languageId": "1",
  "paymentType": ["WECHAT"]
}

WeChat does not need mandatory parameters.
You must use WECHAT as paymentType.

More information about WeChat can be found in the documentation.

Example: Yandex

Yandex example - POST payment/create:

{
  "shopLogin": "{{shopLogin}}",
  "amount": "1",
  "currency": "EUR",
  "shopTransactionID": "TEST",
  "languageId": "",
  "paymentType": [
    "S2PYAN"
  ],
  "orderDetails": {
    "customerDetail": {
      "primaryEmail": "test@test.com"
    }
  }
}

Yandex does not need mandatory parameters; but if you send CustomerDetail.PrimaryEmail in the OrderDetails tag you can have a frictionless call directly to the first screen of Yandex where authentication data are asked.

Name Max Length Description
CustomerDetail.PrimaryEmail 100 Customer primary email.

This mean that no others values are asked to the buyer; if this field is not sent with the payment, a page will ask the necessary fields.

Axerve Guaranteed Payment

Axerve Guaranteed Payment is a fraud detection service, offered in partnership with Riskified. To get more info, visit Axerve Guaranteed Payment documentation.

Axerve Guaranteed Payment can be used both in Encrypt and in S2S webservices (like callPagamS2S and others).

All Axerve Guaranteed Payment data goes inside the tag <OrderDetails>. There you will find a detailed description of every field.

Risk response codes

Code Description
created transaction has been received by Axerve Guaranteed Payment
submitted transaction is under review
approved transaction approved by Axerve Guaranteed Payment
declined transaction not approved by Axerve Guaranteed Payment
captured For Select&Submit plan, captured is returned for transactions that are not marked for review.
any other value error returned by Axerve Guaranteed Payment

Models

In this section we’ll discuss shared objects used in the API.

OrderDetails

OrderDetails tag example:

<OrderDetails>
  <FraudPrevention>
    <SubmitForReview>1</SubmitForReview>
    <OrderDateTime>2017-12-26</OrderDateTime>
    <OrderNote>Please send me the blue version</OrderNote>
    <Source>website</Source>
    <SubmissionReason>rule_decision</SubmissionReason>
    <BeaconSessionID>ff1db05b-81db-4ca0-a728-4797bfe796ff</BeaconSessionID>
    <VendorID>9000002</VendorID>
    <VendorName>www.yourdomain.it</VendorName>
  </FraudPrevention>
  <CustomerDetail>
    <ProfileID />
    <MerchantCustomerID/>
    <FirstName>Michael</FirstName>
    <MiddleName>J.</MiddleName>
    <Lastname>Fox</Lastname>
    <PrimaryEmail>martymcfly@backtothefuture.com</PrimaryEmail>
    <SecondaryEmail />
    <PrimaryPhone>+390298987643</PrimaryPhone>
    <SecondaryPhone>+393351029384</SecondaryPhone>
    <DateOfBirth>29/09/1932</DateOfBirth>
    <SocialSecurityNumber>BRLSLV36P29F205W</SocialSecurityNumber>
    <Company />
    <CreatedAtDate>2017-05-16 15:28</CreatedAtDate>
    <VerifiedEmail>true</VerifiedEmail>
    <AccountType>premium</AccountType>
  </CustomerDetail>
  <CustomerSocial>
    <Network>Facebook</Network>
    <PublicUserName>Marty McFly</PublicUserName>
    <CommunityScore>100</CommunityScore>
    <ProfilePicture>https://external-mxp1-1.xx.fbcdn.net/safe_image.php?d=AQCSnRebJp1o3AR9&w=264&h=264&url=http%3A%2F%2Fupload.wikimedia.org%2Fwikipedia%2Fit%2Fthumb%2F1%2F1d%2FMartyMcFly.JPG%2F720px-MartyMcFly.JPG&colorbox&f</ProfilePicture>
    <Email>martymcfly@backtothefuture.com</Email>
    <Bio>Martin Seamus "Marty" McFly is a fictional character in the Back to the Future trilogy. He is portrayed by actor Michael J. Fox.</Bio>
    <AccountUrl>https://www.facebook.com/pages/Marty-McFly/103151259725141?fref=ts&rf=105623692803833</AccountUrl>
    <Following>0</Following>
    <Followed>1157</Followed>
    <Id>103151259725141</Id>
    <AuthToken>eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...</AuthToken>
    <SocialData />
  </CustomerSocial>
  <ShippingAddress>
    <ProfileID />
    <FirstName>Michael</FirstName>
    <MiddleName>J.</MiddleName>
    <Lastname>Fox</Lastname>
    <Company>Universal Studios</Company>
    <StreetName>Hollywood Boulevard</StreetName>
    <StreetName2 />
    <HouseNumber>1432</HouseNumber>
    <HouseExtention />
    <City>Los Angeles</City>
    <ZipCode>90213</ZipCode>
    <State>California</State>
    <CountryCode>US</CountryCode>
    <Email>martymcfly@backtothefuture.com</Email>
    <PrimaryPhone>+0199332285321</PrimaryPhone>
    <SecondaryPhone />
  </ShippingAddress>
    <BillingAddress>
    <ProfileID />
    <FirstName>Michael</FirstName>
    <MiddleName>J.</MiddleName>
    <Lastname>Fox</Lastname>
    <Company>Universal Studios</Company>
    <StreetName>Hollywood Boulevard</StreetName>
    <StreetName2 />
    <HouseNumber>1432</HouseNumber>
    <HouseExtention />
    <City>Los Angeles</City>
    <ZipCode>90213</ZipCode>
    <State>California</State>
    <CountryCode>US</CountryCode>
    <Email>martymcfly@backtothefuture.com</Email>
    <PrimaryPhone>+0199332285321</PrimaryPhone>
    <SecondaryPhone />
  </BillingAddress>
  <ProductDetails>
    <ProductDetail><!-- first of 1...N products -->
      <ProductCode>135798642</ProductCode>
      <SKU>AB-333222-WFG-4</SKU>
      <Name>Porche Carrera scale model</Name>
      <Description>Porche Carrera scale model</Description>
      <Quantity>1</Quantity>
      <Price>50.5</Price>
      <UnitPrice>50.5</UnitPrice>
      <Type>1</Type><!-- 1: product -->
      <Vat>22</Vat>
      <Discount />
      <Category>Scale Models</Category>
      <Subcategory>cars</Subcategory>
      <Brand>LittleCars</Brand>
      <RequiresShipping>true</RequiresShipping>
      <DeliveryAt>2017-12-29</DeliveryAt>
      <Condition>new</Condition>
      <Seller /><!-- relevant for marketplace orders --> 
    </ProductDetail>
    <ProductDetail>
      <ProductCode>135798642</ProductCode>
      <SKU>AB-333222-WFG-5</SKU>
      <Name>Ferrari scale model</Name>
      <Description>Ferrari scale model</Description>
      <Quantity>1</Quantity>
      <Price>50.5</Price>
      <UnitPrice>50.5</UnitPrice>
      <Type>1</Type><!-- 1: product -->
      <Vat>22</Vat>
      <Discount />
      <Category>Scale Models</Category>
      <Subcategory>cars</Subcategory>
      <Brand>LittleCars</Brand>
      <RequiresShipping>true</RequiresShipping>
      <DeliveryAt>2017-12-29</DeliveryAt>
      <Condition>new</Condition>
      <Seller /><!-- relevant for marketplace orders -->
    </ProductDetail><!-- last of 1...N products -->
  </ProductDetails>
  <DiscountCodes>
    <DiscountCode><!-- one or more -->
      <Amount>10</Amount>
      <Code>53232</Code>
    </DiscountCode>
  </DiscountCodes>
  <ShippingLines>
    <ShippingLine>
      <Price>20</Price>
      <Title>FedEx</Title>
      <Code>72-B03</Code>
    </ShippingLine>
  </ShippingLines>
  <AccommodationDetails>
    <!-- First accomodation -->
    <AccommodationDetail>
      <City>Eindhoven</City>
      <CountryCode>NL</CountryCode>
      <Title>Tulip Inn Eindhoven Airport</Title>
      <CheckInDate>2018-01-20T00:00+0000</CheckInDate>
      <CheckOutDate>2018-01-22T00:00+0000</CheckOutDate>
      <ProductId>NL2133</ProductId>
      <Rating>3</Rating>
      <NumberOfGuests>3</NumberOfGuests>
      <AccommodationType>Hotel</AccommodationType>
      <RoomType>Deluxe Triple</RoomType>
      <Price>370</Price>
      <Quantity>1</Quantity>
      <CancellationPolicy>Non-Refundable</CancellationPolicy>
    </AccommodationDetail>
    <!-- Second accomodation -->
    <AccommodationDetail>
    ...
    </AccommodationDetail>
  </AccommodationDetails>
  <PassengerDetails>
    <!-- First passenger -->
    <PassengerDetail>
      <FirstName>Antonio</FirstName>
      <LastName>Esposito</LastName>
      <DateOfBirth>1970-05-03</DateOfBirth>
      <NationalityCode>IT</NationalityCode>
      <InsuranceType>ERV</InsuranceType>
      <InsurancePrice>17</InsurancePrice>
      <DocumentNumber>AO1234567</DocumentNumber>
      <DocumentType>Identity Card</DocumentType>
      <DocumentIssueDate>Comune di Salerno</DocumentIssueDate>
      <DocumentExpirationDate>2020-10-02</DocumentExpirationDate>
      <PassengerType>adult</PassengerType>
    </PassengerDetail>
    <!-- Second passenger -->
    <PassengerDetail>
    ...
    </PassengerDetail>
  </PassengerDetails>
</OrderDetails>

JSON version of the same data structure

{
  "OrderDetails": {
    "FraudPrevention": {
      "SubmitForReview": "1",
      "OrderDateTime": "2017-12-26",
      "OrderNote": "Please send me the blue version",
      "Source": "website",
      "SubmissionReason": "rule_decision",
      "BeaconSessionID": "ff1db05b-81db-4ca0-a728-4797bfe796ff",
      "VendorID": "9000002",
      "VendorName": "www.yourdomain.it"
    },
    "CustomerDetail": {
      "FirstName": "Michael",
      "MiddleName": "J.",
      "Lastname": "Fox",
      "PrimaryEmail": "martymcfly@backtothefuture.com",
      "PrimaryPhone": "+390298987643",
      "SecondaryPhone": "+393351029384",
      "DateOfBirth": "29/09/1932",
      "SocialSecurityNumber": "BRLSLV36P29F205W",
      "CreatedAtDate": "2017-05-16 15:28",
      "VerifiedEmail": "true",
      "AccountType": "premium"
    },
    "CustomerSocial": {
      "Network": "Facebook",
      "PublicUserName": "Marty McFly",
      "CommunityScore": "100",
      "ProfilePicture": "https://martymcfly.com/image.jpg",
      "Email": "martymcfly@backtothefuture.com",
      "Bio": "Martin Seamus \"Marty\" McFly is a fictional character in the Back to the Future trilogy. He is portrayed by actor Michael J. Fox.",
      "AccountUrl": "https://www.facebook.com/pages/Marty-McFly/103151259725141",
      "Following": "0",
      "Followed": "1157",
      "Id": "103151259725141",
      "AuthToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    },
    "ShippingAddress": {
      "FirstName": "Michael",
      "MiddleName": "J.",
      "Lastname": "Fox",
      "Company": "Universal Studios",
      "StreetName": "Hollywood Boulevard",
      "HouseNumber": "1432",
      "City": "Los Angeles",
      "ZipCode": "90213",
      "State": "California",
      "CountryCode": "US",
      "Email": "martymcfly@backtothefuture.com",
      "PrimaryPhone": "+0199332285321"
    },
    "BillingAddress": {
      "FirstName": "Michael",
      "MiddleName": "J.",
      "Lastname": "Fox",
      "Company": "Universal Studios",
      "StreetName": "Hollywood Boulevard",
      "HouseNumber": "1432",
      "City": "Los Angeles",
      "ZipCode": "90213",
      "State": "California",
      "CountryCode": "US",
      "Email": "martymcfly@backtothefuture.com",
      "PrimaryPhone": "+0199332285321"
    },
    "ProductDetails": [{
        "ProductCode": "135798642",
        "SKU": "AB-333222-WFG-4",
        "Name": "Porche Carrera scale model",
        "Description": "Porche Carrera scale model",
        "Quantity": "1",
        "Price": "50.5",
        "UnitPrice": "50.5",
        "Type": "1",
        "Vat": "22",
        "Category": "Scale Models",
        "Subcategory": "cars",
        "Brand": "LittleCars",
        "RequiresShipping": "true",
        "DeliveryAt": "2017-12-29",
        "Condition": "new"
      },
      {
        "ProductCode": "135798642",
        "SKU": "AB-333222-WFG-5",
        "Name": "Ferrari scale model",
        "Description": "Ferrari scale model",
        "Quantity": "1",
        "Price": "50.5",
        "UnitPrice": "50.5",
        "Type": "1",
        "Vat": "22",
        "Category": "Scale Models",
        "Subcategory": "cars",
        "Brand": "LittleCars",
        "RequiresShipping": "true",
        "DeliveryAt": "2017-12-29",
        "Condition": "new"
      }
    ],
    "DiscountCodes": {
      "DiscountCode": {
        "Amount": "10",
        "Code": "53232"
      }
    },
    "ShippingLines": {
      "ShippingLine": {
        "Price": "20",
        "Title": "FedEx",
        "Code": "72-B03"
      }
    },
    "AccommodationDetails": {
      "AccommodationDetail": [
        {
          "City": "Eindhoven",
          "CountryCode": "NL",
          "Title": "Tulip Inn Eindhoven Airport",
          "CheckInDate": "2018-01-20T00:00+0000",
          "CheckOutDate": "2018-01-22T00:00+0000",
          "ProductId": "NL2133",
          "Rating": "3",
          "NumberOfGuests": "3",
          "AccommodationType": "Hotel",
          "RoomType": "Deluxe Triple",
          "Price": "370",
          "Quantity": "1",
          "CancellationPolicy": "Non-Refundable"
        },
        "
    ...
    "
      ]
    },
    "PassengerDetails": {
      "PassengerDetail": [
        {
          "FirstName": "Antonio",
          "LastName": "Esposito",
          "DateOfBirth": "1970-05-03",
          "NationalityCode": "IT",
          "InsuranceType": "ERV",
          "InsurancePrice": "17",
          "DocumentNumber": "AO1234567",
          "DocumentType": "Identity Card",
          "DocumentIssueDate": "Comune di Salerno",
          "DocumentExpirationDate": "2020-10-02",
          "PassengerType": "adult"
        },
        "
    ...
    "
      ]
    }
  }
}

The OrderDetails tag contains all the info that can be sent together with a transaction. The more data is sent, the easier it is for Axerve Ecommerce Solutions to analyze your request.

Many external systems, like the one presented in the next sections, use OrderDetails fields to work. Axerve Guaranteed Payment (an antifraud system) massively uses OrderDetails to get the job done.

In this section we will analyze indipendently all the fields.

After the XML example there’s the corresponding JSON version. Click to directly jump to the JSON example.

Field Max Size Type Description
FraudPrevention container Contains fields related to fraud prevention.
CustomerDetail
Required
container Contains customer data. Mandatory for Banca Sella customers (see Risk Based Authentication (RBA))
CustomerSocial container if you have access to a customer’ social profile, you can also send this data .
ShippingAddress
Required
container Contains shipping address. Mandatory for Banca Sella customers (see Risk Based Authentication (RBA))
BillingAddress
Required
container contains the billing address. Mandatory for Banca Sella customers (see Risk Based Authentication (RBA))
ProductDetails container contains one or more ProductDetails items buyed.
DiscountCodes container contains one or more DiscountCodes, if discounts are applicable.
ShippingLines container contains one or more ShippingLines, that contain the price and the shipping courier.

Children of FraudPrevention

Field Type Max Size Description
SubmitForReview
Required
string 1 Flag to activate review over Axerve Guaranteed Payment.
  • 0 no submit
  • 1 submit
If your active plan is Select&Submit you can decide which transaction must be submitted to Axerve Guaranteed Payment setting the flag to 1. With Shop Protection all transactions are submitted for review by default.
OrderDateTime
Optional
string 10 Order date time. Format: YYYY-MM-DD.
OrderNote
Optional
string 50 Buyer’s order note .
Source
Required
string 50
  • desktop_web: Order was placed on the website, using a desktop device
  • mobile_web: Order was placed on the mobile website, using a mobile device
  • mobile_app: Order was placed on the mobile app, using a mobile device
  • web: Order was placed on the website, with no available info about the type of device used
  • chat: Order was placed using a chat service
  • third_party: Order was placed on a third party domain
  • phone: Order was placed over the phone by a call center support or sales agent
  • in_store: Order was placed on an in store online device
  • unknown: Order’s origin is unknown
SubmissionReason
Recommended
string 20 the underlying reason for submitting the order to review. It must be one of the following values:
  • failed_verification: order failed (phone, email) verification.
  • rule_decision: Order was flagged by an automatic rule.
  • third_party: Order was flagged by a third-party service.
  • manual_decision: Order was flagged after manual review.
  • policy_decision: order was flagged by a non-fraud related rule.
 This field must be sent either if the shop adheres to Shop Protection or Select & Submit plan; if the plan is Shop Protection, the default is rule_decision.
BeaconSessionID
Required
string 100 Session ID of the Beacon for this transaction. This value must be collected when the user first connects to your website and be sent to Axerve Guaranteed Payment to analyze it. With this field, Axerve Guaranteed Payment knows what actions the user did on your website.
VendorID
Recommended
string 10 A unique ID representing the selling vendor; commonly the Axerve Ecommerce Solutions shopLogin. Mandatory in case of different domain use.
VendorName
Recommended
string 100 In case of multiple selling domains, this is the name of the selling vendor. Mandatory in case of different domain use.

Children of CustomerDetail

Field Type Max Size Description
MerchantCustomerID
Required
Required
string 50 The customer’s ID in the merchant’s system.
FirstName
Required
Required
string 65 Customer First Name .
Lastname
Required
Required
string 65 Customer Last name.
PrimaryEmail
Required
Required
string 100 Customer primary email.
PrimaryPhone
Required
string 20 Customer’s phone including prefix.
DateOfBirth
Required
string 10 Customer Date of Birth (dd/mm/yyyy).
Gender
Required
string 1 Customer Gender (0=Male 1=Female).
SocialSecurityNumber
Required
string 20 Customer’s social or fiscal identifier (KlarnaUse).
Company
Required
string 255 Customer Company.
CreatedAtDate
Required
string 10 Date of Customer creation on merchant site. Example: 2017-05-16 15:28 (year-month-day hour:minute).
VerifiedEmail
Required
string 5 Email is verified? true/false.
AccountType
Optional
string 20 free/premium etc.

Children of CustomerSocial

If you have access to social data of your customers, you can send them along with the other data.

Field Type Max Size Description
Network
Optional
string 12 The name of the social network.
PublicUserName
Optional
string 50 The customer’s public username.
CommunityScore
Optional
string 65 holds the score for networks where it’s relevant.
ProfilePicture
Optional
string 65 URL of the customer’s profile picture.
Email
Optional
string 65 Customer’s email address registered on the social network.
Bio
Optional
string 100 Short biography of the customer on the social network.
AccountUrl
Optional
string 100 Direct URL to the customer’s profile page on the social network.
Following
Optional
string 20 Direct URL to the customer’s profile page on the social network.
Followed
Optional
string 20 Number of users followed by the customer on the social network.
Id
Optional
string 10 The customer’s profile id.
AuthToken
Optional
string 10 The authentication token of the user.
SocialData
Optional
string 20 Open field for additional data from the social network.

ShippingAddress and BillingAddress field

Field Type Max Size Description
FirstName
Required
string 65 First Name.
Lastname
Required
string 65 Last name.
StreetName
Required
Required
string 100 The street address of the shipping address.
Streetname2
Optional
string 100 The street address of the shipping address, second line.
HouseNumber
Required
string 5 House Number.
HouseExtention
Required
string 5 House Extension.
City
Required
Required
string 50 Shipping City.
ZipCode
Required
Required
string 50 The zip or postal code of the shipping address.
State
Required
Required
string 50 The name of the state or province of the shipping address.
CountryCode
Required
Required
string 2 Alpha-2 code; for example, United States is “US”.
PrimaryPhone
Required
string 20 Shipping Primary Phone.
Company
Optional
string 255 Company Name.
StateCode
Required
string 2 Two-letter abbreviation of the state or province of the address.

 ProductDetails and ProductDetail field

ProductDetails will contain one or more ProductDetail.

ProductDetail describes a bought item.

Field Type Max Size Description
ProductCode
Required
Required
string 12 Article’s product Code.
SKU
Recommended
string 50 Article’s Stock Keeping Unit.
Name
Required
Required
string 100 Article’s name.
Quantity
Required
Required
string 3 The number of products.
Price
Required
Required
string 12 Article’s price (dot as decimal separator).
Type*
Required
Required
string 8 The type of article:
  • 1: product
  • 2: shipping
  • 3: handling
If the riskified integration is active, the product type should contain one of the following values:
  • physical: This is a tangible/physical product.
  • digital: This is a digital product (e.g. gift card).
  • travel: This is a travel industry product (e.g. flight ticket)
  • event: This is an event industry product (e.g. concert ticket)
If instead the active integration is klarna, the value are:
  • 4: discount
  • 5: phisical article
  • 6: shipping fee
  • 7: sales tax
  • 8: digital article
  • 9: gift card
  • 10: store credit
  • 11: surcharge
You can find more information about Klarna type codes here.
Vat
Required
string 2 Value-Added Tax (the value of the tax as an integer).
Discount
Required
string 2 The percentage on the original price offered by you as discount, e.g. 10 -> 10% of the amount in “Price”.
RequiresShipping
Required
string 5 true/false States whether or not the fulfillment requires shipping. This field is important for merchants dealing with digital goods.
Condition
Optional
string 100 Description of the physical condition of the item, mostly relevant for used items.
Category
Recommended
string 255 Product Category.
Subcategory
Recommended
string 255 Product Sub Category.
Brand
Recommended
string 255 Product Brand.
DigitalGiftCardDetails
Required
object An object containing the details about digital goods. The structure of this object is outlined in the next section. Object required only if the product is a digital good / giftcard — In any other case, it is optional.

*Type has a different meaning based on the type of active integration (for example klarna /riskified)

Children of ProductDetail.DigitalGiftCardDetails

Field Type Max Size Description
SenderName
Required
string 65 The sender name (Required only for Digital goods).
DisplayName
Optional
string 65 The display name.
GreetingMessage
Optional
string 255 The greeting message.
Recipient
Optional
object An object containing information about the recipient of digital goods. The structure of this object is outlined in the next section.

Children of ProductDetail.DigitalGiftCardDetails.Recipient

Field Type Max Size Description
Email
Optional
string 100 The recipient’s email address.
Phone
Optional
string 20 The recipient’s phone number.

DiscountCodes and DiscountCode fields

If you apply discounts for your products you should add discount info.

in DiscountCodes you may have one or more DiscountCode, that contain these fields:

Field Type Max Size Description
Amount
Required
string 12 The amount of the discount (dot as decimal separator).
Code
Required
string 50 The code of the discount.

 ShippingLines and ShippingLine fields

With this fields you can define the price and the kind of shipping that you use for your products, if applicable.

Field Type Max Size Description
Price
Required
string 12 The price of the shipping method (dot as decimal separator).
Title
Required
string 100 The title of the shipping method.
Code
Recommended
string 50 Code of the shipping method.

AccomodationDetails and AccomodationDetail fields

These tags are useful for Hotel and Accomodation companies. You can put as many AccomodationDetail you need inside one AccomodationDetails group tag.

Field Type Max Size Description
City
Required
string 50 Accomodation City.
CountryCode
Required
string 2 The 2 letter country code (ISO 3166-1 alpha-2) of the country where the accommodation is located.
Title
Required
string 255 Accomodation name.
CheckInDate
Required
string 50 Date-Time of arrival in ISO standard.
CheckOutDate
Optional
string 50 Date-Time of departure in ISO standard.
ProductId
Required
string 255 Booking.com unique identifier of the offer, skip if irrelevant.
Rating
Optional
string 5 Star rating of the accomodation.
NumberOfGuests
Optional
string 3 Number of guests.
AccommodationType
Optional
string 255 Accomodation type: Hotel, Room, B&B, etc.
RoomType
Optional
string 255 The room type, such as single, double, suite, etc.
Price
Required
string 12 Price of one room of this kind for the period (dot as decimal separator).
Quantity
Required
string 5 How many rooms of this kind are in the order.
CancellationPolicy
Optional
string 255 Write here your cancellation policy, e.g. Non-Refundable.

TravelTicketDetails and TravelTicketDetail fields

These tags are useful for Traveling companies. You can put as many PassengerDetail you need inside one PassengerDetails group tag.

Field Type Max Size Description
ArrivalCity
Required
string 50 The name of the city of arrival for the current leg.
ArrivalCountryCode
Required
string 2 The 2 letter country code (ISO 3166-1 alpha-2) for the arrival country of the current leg.
ArrivalDate
Optional
string 50 Date and time of arrival for the current leg. Add corresponding timezone indication or ensure correct UTC standardization (ISO8601) e.g. 2019-07-24T22:30:00-3:00
ArrivalPortCode
Optional
string 3 Arrival port code for the current leg. For flights: the 3 letter IATA airport code.
CarrierCode
Required
string 2 A publicly agreed code describing the carrier/company conducting the current leg. For Flights: The IATA 2 letter carrier code.
CarrierName
Optional
string 255 The name of the carrier/company conducting the current leg.
DepartureCity
Required
string 50 The name of the city of departure for the current leg.
DepartureCountryCode
Required
string 2 The 2 letter country code (ISO 3166-1 alpha-2) for the departure country of the current leg.
DepartureDate
Required
string 50 Date and time of departure for the current leg. Add corresponding timezone indication or ensure correct UTC standardization (ISO8601) e.g. 2019-07-24T20:55:00+2:00
DeparturePortCode
Optional
string 3 Departure port code for the current leg. For flights: the 3 letter IATA airport code.
LegId
Required
string 255 The current leg id. For flight tickets, the flight number (e.g. ‘101’). For bus tickets, the bus number (e.g: 'A7’).
LegIndex
Required
string 5 A running index (starts with 1), describing the order of legs in the same route. For more details, see route_index field.
RouteIndex
Required
string 5 A running index (starts with 1), describing the order of routes by time. E.g: If an order contains the 2 following Routes:
  • New-York->London->Paris (connection in London)
    • New-York->London should have route_index=1, leg_index=1
    • London->Paris should have route_index=1, leg_index=2
  • Paris->London->New-York
    • Paris->London should have route_index=2, leg_index=1
    • London->New-York should have route_index=2, leg_index=2
TicketClass
Optional
string 255 The class for this leg’s ticket (e.g. business, economy, first)
Price
Required
string 12 The price of the item (dot as decimal separator).
Quantity
Required
string 12 The number of items that were ordered.
Title
Required
string 255 The title of the item.

PassengerDetails and PassengerDetail fields

These tags are useful for travel agencies - flights, ships, etc. You can put as many PassengerDetail you need inside one PassengerDetails group tag.

Field Type Max Size Description
FirstName
Required
string 255 Name of the passenger.
LastName
Required
string 255 Last name of the passenger.
DateOfBirth
Required
string 10 Date of birth of the passenger. Date part only (ISO8601).
NationalityCode
Required
string 2 The 2 letter country code (ISO 3166-1 alpha-2) matching the passenger’s nationality country.
InsuranceType
Optional
string 255 Insurance title if was chosen by the end customer.
InsurancePrice
Optional
string 12 Insurance price if was chosen by the end customer (dot as decimal separator).
DocumentNumber
Optional
string 255 A valid identification document number.
DocumentType
Optional
string 255 The type of the identification document.
DocumentIssueDate
Optional
string 50 The identification document issue date.
DocumentExpirationDate
Optional
string 50 The identification document expiration date.
PassengerType
Recommended
string 255 adult or child.

ShippingDetails

shippingDetails tag example:

<shippingDetails>
  <shipToName>Marco Bianchi</shipToName>
  <shipToStreet>Via Milano 1</shipToStreet>
  <shipToCity>Torino</shipToCity>
  <shipToState>TO</shipToState>
  <shipToCountryCode>IT</shipToCountryCode>
  <shipToZip>10100</shipToZip>
  <shipToStreet2/>
</shippingDetails>

shippingDetails used for example in Paypal seller protection, contains the shipping address.

Name max length description
shipToName 32 String containing the shipping name
shipToStreet 100 String containing the shipping address
shipToCity 40 String containing the shipping city
shipToState 40 String containing the shipping state (see Paypal State Codes table)
shipToCountryCode 2 String containing the shipping country code (see Paypal Country Codes table)
shipToZip 20 String containing the shipping zip
shipToStreet2 100 String containing an additional shipping address field

3ds 2.0 fields sandbox

threeDsContainer xml example:

<threeDsContainer>
        <transTypeReq></transTypeReq>
        <acquirerBIN></acquirerBIN>
        <acquirerMerchantID></acquirerMerchantID>
        <exemption></exemption>
        <buyerDetails>
            <profileDetails>
                <cardholderID></cardholderID>
                <authData></authData>
                <authMethod></authMethod>
                <authTimeStamp></authTimeStamp>             
            </profileDetails>           
            <billingAddress>
                <city></city>
                <country></country>
                <line1></line1>
                <line2></line2>
                <line3></line3>
                <postCode></postCode>
                <state></state>
            </billingAddress>
            <shippingAddress>
                <city></city>
                <country></country>
                <line1></line1>
                <line2></line2>
                <line3></line3>
                <postCode></postCode>
                <state></state>
            </shippingAddress>
            <addrMatch></addrMatch>
            <cardHolder>
                <name></name>
                <email></email>
                <homePhone_cc></homePhone_cc>
                <homePhone_num></homePhone_num>
                <mobilePhone_cc></mobilePhone_cc>
                <mobilePhone_num></mobilePhone_num>
                <workPhone_cc></workPhone_cc>
                <workPhone_num></workPhone_num>
            </cardHolder>
            <accInfo>
                <chAccAgeInd></chAccAgeInd>
                <chAccChange></chAccChange>
                <chAccChangeInd></chAccChangeInd>
                <chAccDate></chAccDate>
                <chAccPwChange></chAccPwChange>
                <chAccPwChangeInd></chAccPwChangeInd>
                <nbPurchaseAccount></nbPurchaseAccount>
                <provisionAttemptsDay></provisionAttemptsDay>
                <txnActivityDay></txnActivityDay>
                <txnActivityYear></txnActivityYear>
                <paymentAccAge></paymentAccAge>
                <paymentAccInd></paymentAccInd>
                <shipAddressUsage></shipAddressUsage>
                <shipAddressUsageInd></shipAddressUsageInd>
                <shipNameIndicator></shipNameIndicator>
                <suspiciousAccActivity></suspiciousAccActivity>
            </accInfo>
        </buyerDetails>
        <merchantRiskIndicator>
            <deliveryEmailAddress></deliveryEmailAddress>
            <deliveryTimeframe></deliveryTimeframe>
            <giftCardAmount></giftCardAmount>
            <giftCardCount></giftCardCount>
            <giftCardCurr></giftCardCurr>
            <preOrderDate></preOrderDate>
            <preOrderPurchaseInd></preOrderPurchaseInd>
            <reorderItemsInd></reorderItemsInd>
            <shipIndicator></shipIndicator>
        </merchantRiskIndicator>
    <SDKDetails></SDKDetails>
    </threeDsContainer>

threeDsContainer’s fields are used from 3ds server to establish if the transaction could be a fraud and require or not the SCA.

Name max length description
transTypeReq 1 Type of transaction required to Axerve Ecommerce Solutions: complete payment process or only authentication (in case of third party Acquirer).
  • P for Payment (default)
  • A for authentication only
acquirerBIN 11 This field are required if transTypeReq value is A. Acquiring institution identification code as assigned by the DS receiving the AReq message.
Reserved field for future developments.
acquirerMerchantID 35 This field are required if transTypeReq value is A. Acquirer-assigned Merchant identifier. This may be the same value that is used in authorisation requests sent on behalf of the 3DS Requestor and is represented in ISO 8583 formatting requirements.
Reserved field for future developments.
exemption string Challenge management exemption. Possible values:
  • SKIP: to ask exclude the possibility of exemption and require challange mandatory
  • FORCE: exemption requested by the merchant
If not evaluated, the Axerve Ecommerce Solutions rule is applied
buyerDetails object
profileDetails
object Contains option information about the merchant authenticated the cardholder before or during the transaction.
cardholderID
64 Additional information about the account optionally provided by the 3DS Requestor.
authData
string Transaction authenticated data
authMethod
2 Transaction authenticated method
  • 01: No merchant authentication occurred (i.e. cardholder “logged in” as guest)
  • 02: Login to the cardholder account at the merchant system using merchant’s own credentials
  • 03: Login to the cardholder account at the merchant system using federated ID
  • 04: Login to the cardholder account at the merchant system using issuer credentials
  • 05: Login to the cardholder account at the merchant system using third-party authentication
  • 06: Login to the cardholder account at the merchant system using FIDO Authenticator
  • 07: Login to the cardholder account at the merchant system using FIDO Authenticator (FIDO assurance data signed)
  • 08: SRC Assurance Data
authTimestamp
12 Transaction authenticated timestamp.
Format: YYYYMMDDHHMM
billingAddress
object Cardholder billing address associated with the card used for this purchase.
city
50 The city of the Cardholder billing address associated with the card used for this purchase.
country
2 The country of the Cardholder billing address associated with the card used for this purchase. See Paypal Country Codes table
line1
50 First line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.
line2
50 Second line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.
line3
50 Third line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase.
postCode
16 ZIP or other postal code of the Cardholder billing address associated with the card used for this purchase.
state
32 The state or province of the Cardholder billing address associated with the card used for this purchase. Should be the state, province or regional code (country subdivision code, see Paypal State and province codes table)
shippingAddress
object Shipping address
city
50 City portion of the shipping address requested by the Cardholder.
country
2 Country of the shipping address requested by the Cardholder. See Paypal Country Codes table
line1
50 First line of the street address or equivalent local portion of the shipping address requested by the Cardholder.
line2
50 Second line of the street address or equivalent local portion of the shipping address requested by the Cardholder.
line3
50 Thrid line of the street address or equivalent local portion of the shipping address requested by the Cardholder.
postCode
16 The ZIP or other postal code of the shipping address requested by the Cardholder.
state
32 The state or province of the shipping address associated with the card being used for this purchase. Should be the state, province or regional code (country subdivision code, see Paypal State and province codes table)
addrMatch
1 Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same. Y for yes and N for no
cardholder
object Cardholder information.
name
45 Name of the Cardholder.
Email
254 The email address associated with the account that is either entered by the Cardholder, or is on file with the 3DS Requestor. The value should meet requirements of Section 3.4 of IETF RFC 5322
homePhone_cc
3 The countryCode of the home phone number provided by the Cardholder. Refer to ITU-E.164
homePhone_num
15 The home phone number provided by the Cardholder (without the countryCode).
mobilePhone_cc
3 The countryCode of the mobile phone number provided by the Cardholder. Refer to ITU-E.164.
mobilePhone_num
15 The mobile phone number provided by the Cardholder (without the countryCode).
workPhone_cc
3 The countryCode of the work phone number provided by the Cardholder. Refer to ITU-E.164
workPhone_num
15 The work phone number provided by the Cardholder (without the countryCode).
accInfo
object Additional information about the Cardholder’s account provided by the 3DS Requestor.
chAccAgeInd
2 Length of time that the cardholder has had the account with the 3DS Requestor.
  • 01 No account (guest check-out)
  • 02 Created during this transaction
  • 03 Less than 30 days
  • 04 30−60 days
  • 05 More than 60 days
chAccChange
8 Date that the cardholder’s account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added. Date format = YYYYMMDD
chAccChangeInd
2 Length of time since the cardholder’s account information with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added.
  • 01 Changed during this transaction
  • 02 Less than 30 days
  • 03 30−60 days
  • 04 More than 60 days
chAccDate
8 Date that the cardholder opened the account with the 3DS Requestor. Date format = YYYYMMDD
chAccPwChange
8 Date that cardholder’s account with the 3DS Requestor had a password change or account reset. Date format = YYYYMMDD
chAccPwChangeInd
2 Indicates the length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset.
  • 01 No change
  • 02 Changed during this transaction
  • 03 Less than 30 days
  • 04 30−60 days
  • 05 More than 60 days
nbPurchaseAccount
4 Number of purchases with this cardholder account during the previous six months.
provisionAttemptsDay
3 Number of Add Card attempts in the last 24 hours. Example values:
  • 2
  • 02
  • 002
txnActivityDay
3 Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours. Example values:
  • 2
  • 02
  • 002
txnActivityYear
3 Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year. Example values:
  • 2
  • 02
  • 002
paymentAccAge
8 Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor. Date format = YYYYMMDD
paymentAccInd
2 Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor.
  • 01 No account (guest check-out)
  • 02 During this transaction
  • 03 Less than 30 days
  • 04 30−60 days
  • 05 More than 60 days
shipAddressUsage
8 Date when the shipping address used for this transaction was first used with the 3DS Requestor. Date format = YYYYMMDD
shipAddressUsageInd
2 Indicates when the shipping address used for this transaction was first used with the 3DS Requestor.
  • 01 This transaction
  • 02 Less than 30 days
  • 03 30−60 days
  • 04 More than 60 days
shipNameIndicator
2 Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.
  • 01 Account Name identical to shipping Name
  • 02 Account Name different than shipping Name
suspiciousAccActivity
2 Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account.
  • 01 No suspicious activity has been observed
  • 02 Suspicious activity has been observed
merchantRiskIndicator object Merchant’s assessment of the level of fraud risk for the specific authentication for both the cardholder and the authentication being conducted.
deliveryEmailAddress
254 For Electronic delivery, the email address to which the merchandise was delivered.
deliveryTimeframe
2 Indicates the merchandise delivery timeframe.
  • 01 Electronic Delivery
  • 02 Same day shipping
  • 03 Overnight shipping
  • 04 Two-day or more shipping
giftCardAmount
15 For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123). Example: gift card amount is USD 123.45: Values accepted:
  • 123
  • 0123
  • 00123
giftCardCount
2 For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased. Field is defined as being exactly 2 characters long
giftCardCurr
3 For prepaid or gift card purchase, uicCode currency code.
preOrderDate
8 For a pre-ordered purchase, the expected date that the merchandise will be available. Date format = YYYYMMDD
preOrderPurchaseInd
2 Indicates whether Cardholder is placing an order for merchandise with a future availability or release date.
  • 01 Merchandise available
  • 02 Future availability
reorderItemsInd
2 Indicates whether the cardholder is reordering previously purchased merchandise.
  • 01 First time ordered
  • 02 Reordered
shipIndicator
2 Indicates shipping method chosen for the transaction. Merchants must choose the Shipping Indicator code that most accurately describes the cardholder’s specific transaction, not their general business. If one or more items are included in the sale, use the Shipping Indicator code for the physical goods, or if all digital goods, use the Shipping Indicator code that describes the most expensive item.
  • 01 Ship to cardholder’s billing address
  • 02 Ship to another verified address on file with merchant
  • 03 Ship to address that is different than the cardholder’s billing address
  • 04 “Ship to Store” / Pick-up at local store (Store address shall be populated in shipping address fields)
  • 05 Digital goods (includes online services, electronic gift cards and redemption codes)
  • 06 Travel and Event tickets, not shipped
  • 07 Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.)
SDKDetails string Contains SDK data to be sent to ACS as base64-encoded string.
Include:
  • DeviceData
  • SDKAppID
  • SDKReferenceNumber
  • SDKEphemeralPublicKey
  • MessageVersion
This field doesn’t exist in Encrypt call request.

Errors

Code Description
0 Transaction correctly processed
10 Payment page correctly loaded
57 Blocked credit card
58 Confirmed amount exceeds authorized amount
63 Demand for settlement of one nonexistent transaction
64 Expired preauthorization
65 Wrong currency
66 Preauthorization already notified
74 Authorization denied
97 Authorization denied
100 Transaction interrupted by bank authorizative system
150 Wrong merchant configuration in bank authorizative system
208 Wrong expiry date
212 Bank authorizative system not available
251 Insufficient credit
401 Call credit card company
402 Call credit card company
403 Technical error
404 Collect card
405 Authorization refused by credit card companies
406 Technical error
409 Technical error
412 Technical error
413 Technical error
414 Card not recognized
415 Technical error in connection with Credit Card Company network
416 Pin errato
417 Authorization denied
418 Network not available
419 Wrong transaction date
420 Wrong card date
430 Technical error
431 Technical error in connection with Credit Card Company network
433 Card expired
434 Authorization refused by credit card companies
435 Authorization refused by credit card companies
436 Card not qualified
437 Operation not allowed
438 Operation not allowed
439 Card not recognized
441 Blocked credit card
443 Blocked credit card
451 Amount not available
454 Card expired
455 Operation not performed
456 Card not recognized
457 Authorization refused by credit card companies
458 Wrong merchant configuration in bank authorizative system
461 Amount not available
462 Blocked credit card
468 Bank authorizative system not available
475 Operation not allowed
490 Technical error
491 Technical error in connection with Credit Card Company network
492 Technical error in connection with Credit Card Company network
494 Technical error
552 MyBank payment not completed
553 MyBank payment abbandoned by buyer
600 Technical error
613 Technical error
614 Technical error
615 Technical error
651 Invalid card number
652 Invalid expiry year
653 Invalid expiry month
810 Bank authorizative system not available
811 Wrong merchant configuration in bank authorizative system
901 Authorization denied
902 Authorization denied
903 Authorization denied
904 Authorization denied
905 Authorization denied
906 Authorization denied
907 Authorization denied
908 Authorization denied
910 Authorization denied
911 Authorization denied
913 Authorization denied
914 Authorization denied
915 Authorization denied
916 Authorization denied
917 Authorization denied
918 Authorization denied
919 Authorization denied
920 Authorization denied
950 Not qualified credit card
951 Wrong merchant configuration in bank authorizative system
998 Credit card with wrong check-digit
999 Operation not performed
1100 Empty parameter string
1101 Invalid format of parameter string
1102 No parameter name precedes = symbol
1103 Parameter string ending with a separator
1104 Invalid parameter name
1105 Invalid parameter value
1106 Repeated parameter name
1107 Unexpected parameter name. Please double check Fields and Parameters configuration in Back Office.
1108 Compulsory parameter not set
1109 Missing parameter
1110 Missing PAY1_UICCODE parameter
1111 Invalid currency code
1112 Missing PAY1_AMOUNT parameter
1113 Not numeric amount
1114 Amount with a wrong number of decimal digits
1115 Missing P A Y1_SHOPTRANSACTIONID parameter
1116 Too long P A Y1_SHOPTRANSACTIONID parameter
1117 Invalid language identifier
1118 Not numeric characters in credit card number
1119 Credit card number with wrong length
1120 Credit card with wrong check-digit
1121 Credit card belongs to a Company not enabled
1122 Expiry year without expiry month
1123 Expiry month without expiry year
1124 Invalid expiry month
1125 Invalid expiry year
1126 Expired expiry date
1127 Invalid cardholder email address
1128 Too long parameter string
1129 Too long parameter value
1130 Not accepted call: missing parameter A
1131 Not accepted call: Shop not recognized
1132 Not accepted call: shop is not in active state
1133 Not accepted call: missing parameter B
1134 Not accepted call: empty parameter B
1135 Not accepted call: other parameters beside A and B are present
1136 Not accepted call: transaction did not begin with a call to server-server cryptography system
1137 Not accepted call: transaction already processed before
1138 Not accepted call: card number or expiry date are missing
1139 Not accepted call: missing published payment page
1140 Transaction cancelled by buyer
1141 Not accepted call: input parameter string not acceptable
1142 Not accepted call: invalid IP Address
1143 Transaction abandoned by buyer
1144 Compulsory field not set
1145 Invalid OTP
1146 Too small amount
1147 Too big amount
1148 Invalid cardholder name
1149 Missing or wrong CVV2
1150 IPIN must be set
1151 Parameters error
1153 Axerve Ecommerce Solutions failed to verify if the card is enrolled to VBV service
1154 Not accepterd call: missing parameter TransKey
1160 Wrong CustomToken length
1161 Wrong CustomToken digits number
1162 CustomToken with illegal characters
1163 CustomToken used for another card
1164 Expired Token
1165 Token not found
1169 Not accepted call: invalid Merchant APIKEY
1170 invalid paymentToken
1171 missing authentication header
1172 Invalid call: check/DCC call missing
1173 Input data is not in the correct format, Please check your input
1187 The “previousTransDetails” parameter is mandatory for “01N” or “02N” or “03N” transactions
1200 No match between ABI code and BankPass Banks
1201 BankPass Transaction abandoned by buyer
1202 BankPass - Buyer login failed
1203 BankPass - no payment methods available
1204 BankPass - technical error
1205 BankPass Server-Server: URL Return must be set
1206 BankPass Server-Server: too long URL Return (max 250 char)
1207 BankPass Server-Server: invalid URL Return (it must begin with http:// or https://)
1208 BankPass Server-Server: URL Return parameter missing
1209 BankPass Server-Server: IDBankPass must be set
1210 BankPass Server-Server: invalid IDBankPass
1300 Shipping Address Country Error
1301 Shipping Address1 Empty
1302 Shipping Address City Empty
1303 Shipping Address State Empty
1304 Shipping Address Postal Code Empty
1305 Shipping Address Country Empty
1306 Shipping Address Invalid City State Postal Code
1307 Event type is missing
1400 Element not found
1401 No data found
1402 Ambiguous search name
1403 Wrong paymentType
1404 Authentication method not allowed
1405 SearchID not found
1406 Column not found
1407 Not accepted call: invalid Master APIKEY
1408 Missing or wrong UserID
1409 Wrong searchID: it must be a numeric value
1410 Wrong date format: it must be DD/MM/YYYY
1411 Wrong lastNDays value: it must be a numeric value
1412 Wrong transaction error code value
1413 Wrong paymentID
1414 Wrong authorization result value
1415 Wrong tdLevel value
1416 Wrong eventType value
1417 Wrong includeToday value: true/false
1418 Wrong transaction state value
1419 Wrong chargeback.type value
1420 Event type is missing
1421 Chargeback type is missing
1422 Wrong paymentMethod.name
1423 Wrong riskAlert value: true/false
1424 Wrong value in customFields/Info parameter
1425 Wrong rangeResult value: it must be a numeric value with n/n format
1426 Batch name is missing
1427 Existing batch with the same name
1428 Missing or wrong batchID
1429 Missing or wrong searchID
1430 Missing or wrong fyleType
1431 Wrong templateID
1432 Invalid email address
1433 Wrong ‘email.enabled’ value: true/false
1434 Email value is missing
1435 Wrong ftp value
1436 Ftp value is missing
1437 Email or ftp: at least one of the two valued must be filled
1438 Wrong or missing frequencyID
1439 Wrong template
1440 Wrong default value: true/false
1441 Missing CURRENCY parameter
1442 Wrong channelType: EMAIL/QRCODE
1443 Existing filter with the same name
1444 Missing filter name (save.name)
1445 The amount cannot be updated
1446 Wrong or missing 'withAuth’: true/false
1447 Wrong language: ITALIAN/ENGLISH
1448 Wrong 'capture’ value: SEPARATED/UNIFIED
1449 Wrong 'automaticBehaviour.type’ value: CAPTURE/DELETE
1450 AuthomaticBehaviour days: not numeric parameter value
1451 Creditcard: number of days higher than the max allowed
1452 PAYPAL: 'automaticBehaviour.days’ can be max 25
1453 KLARNA: 'automaticBehaviour.days’ can be max 14
1454 AMAZONPAY: 'automaticBehaviour.days’ can be max 25
1455 InvoiceID not found
1456 Amount with wrong deciman separator
1457 Expired paymentToken
1458 Wrong paymentPage value: VISIBLE/HIDDEN
1459 Wrong language: ITALIANO/ENGLISH/ESPANOL/FRANCAIS/GERMAN
1460 Wrong DCC value: true/false
1461 Creditcard data missing
1462 Ideal bankCode missing
1463 MyBank bankCode missing
1464 Wrong 'level’ value
1999 Technical error in connection with Credit Card Company network
2000 Transaction exceeds maximum operations number in time period
2001 Transaction exceeds maximum number of operations performed by the same buyer in time period
2002 Transaction exceeds maximum amount in time period
2003 Transaction exceeds maximum amount payable by same buyer in time period
2004 Transaction contains a field value that had been declared not acceptable
2005 Buyer abandoned the transaction because it was double
2006 Wrong line length
2007 Wrong value in SHOPTRANSACTIONID field
2008 Wrong value in CURRENCY field
2009 Wrong value in AMOUNT field
2010 Wrong value in AUTHORIZATION DATE field
2011 Transaction not found
2012 Transaction ambiguous
2013 Text file contains more rows related to the same transaction
2014 You requested a refund operation with an amount exceeding transaction balance
2015 Wrong value in BANKTRANSACTIONID field
2016 Fields BANKTRANSACTIONID and SHOPTRANSACTIONID are empty
2017 Transaction can not be deleted
2018 Transaction can not be refunded
2019 Transaction can not be settled
2020 Transaction can not be renounced
2030 Due to RED configuration, transaction is sent to credit card companies, even if 3d-Secure authentication is failed
2500 payment abbandoned by buyer
2501 payment not completed
2502 Smart2Pay: data wrong or missing
2521 SEPADD Error - AC01 - Account Identifier incorrect (i.e. invalid IBAN of the Debtor)
2522 SEPADD Error - AC04 - Account closed.
2523 SEPADD Error - AC06 - Account blocked.
2524 SEPADD Error - AC13 - Debtor account is a consumer account.
2525 SEPADD Error - AG01 - Direct Debit forbidden on this account for regulatory reasons.
2526 SEPADD Error - AG02 - Operation code/transaction code/sequence type incorrect., invalid file format.
2527 SEPADD Error - AM04 - Insufficient funds.
2528 SEPADD Error - AM05 - Duplicate collection.
2529 SEPADD Error - BE05 - Identifier of the Creditor Incorrect.
2530 SEPADD Error - CNOR - Creditor Bank is not registered under this BIC in the CSM.
2531 SEPADD Error - DNOR - Debtor Bank is not registered under this BIC in the CSM.
2532 SEPADD Error - FF01 - File Format incomplete or invalid.
2533 SEPADD Error - MD01 - No mandate.
2534 SEPADD Error - MD02 - Mandate data missing or incorrect.
2535 SEPADD Error - MD06 - Disputed authorized transaction.
2536 SEPADD Error - MD07 - Debtor Deceased.
2537 SEPADD Error - MS02 - Refusal by the Debtor.
2538 SEPADD Error - MS03 - Reason not specified.
2539 SEPADD Error - RC01 - Bank Identifier (BIC) Incorrect.
2540 SEPADD Error - RR01 - Regulatory Reason.
2544 SEPADD Error - SL01 - Specific Service offered by the Debtor Bank.
2546 SEPADD Mandate Error - Preapproval cancelled by consumer
2547 SEPADD Mandate Error - Session timeout
2548 SEPADD Mandate Error - Invalid creditor
2549 SEPADD Mandate Error - Duplicate mandate reference
2550 SEPADD Mandate Error - No documents to sign
2551 SEPADD Mandate Error - Forbidden IBAN
2552 SEPADD Mandate Error - Invalid account owner
2553 SEPADD Mandate Error - Mandate signature failed
2554 SEPADD Mandate Error - Invalid user approval (OTP) code
2555 SEPADD Mandate Error - Inconsistent client data during signature.
2556 SEPADD Mandate Error - Card operation refused by operator
2557 SEPADD Mandate Error - Card operation bank refusal
2558 SEPADD Mandate Error - Card operation access failure
2559 SEPADD Mandate Error - Card operation invalid transaction reference
2560 SEPADD Mandate Error - Card lost
2561 SEPADD Mandate Error - Card stolen
2562 SEPADD Mandate Error - Card suspect
2563 SEPADD Mandate Error - Duplicate order
2564 SEPADD Mandate Error - Resource not found
2565 SEPADD Mandate Error - Incomplete request data
2566 SEPADD Mandate Error - Invalid BIC
2567 SEPADD Mandate Error - Invalid IBAN
2568 SEPADD Mandate Error - Multiple requests to provider with the same mandate
2569 SEPADD Mandate Error - Subscriber reached the monthly mandates limit with the same IBAN
2570 SEPADD Mandate Error - Subscriber reached the limit of mandates created with the same phone number
4001 Unexpected parameter value
4002 Not numeric parameter value
4100 Operation not allowed
4101 Credit card number with wrong length
4102 Amount not available
4103 Technical error
4104 Technical error
4105 Technical
4106 Technical
4108 Technical error in connection with Credit Card Company network error
4109 Technical error
4200 Technical error
4201 Technical error
4202 Technical error
4203 Call credit card company
4204 Operation not allowed
4205 Operation not allowed
4206 Credit card with wrong check-digit. Please double-check the credit card number typed in.
4207 Technical error
4208 Operation not allowed
4209 Technical error
4300 Technical error
4301 Too big amount
4302 Technical error
4303 Operation not allowed
4304 Technical error
4305 Authorization refused by credit card companies
4306 Operation not allowed
4307 Technical error
4308 Operation not allowed
4309 Too big amount
4400 Wrong transaction date
4401 Wrong expiry date
4402 Technical error in connection with Credit Card Company network
4403 Technical error
4404 Technical error
4405 Operation not allowed
4406 Operation not allowed
4407 Amount not available
4408 Operation not allowed
4409 Operation not allowed
4500 Technical error
4501 Technical error
4502 Technical error
4503 Operation not allowed
4504 Operation not allowed
4505 Operation not allowed
4506 Technical error
4507 Technical error
4508 Operation not allowed
4604 Technical error
4701 Operation not allowed
4702 Wrong expiry date
4703 Card not qualified
4704 Amount not available
4705 Technical error in connection with Credit Card Company network
4706 Technical error in connection with Credit Card Company network
4707 Transaction already processed
4708 MyBank: communication with the buyer’s Bank failed
4709 Ideal: communication with the buyer’s Bank failed
4710 PayPal Error
4711 MyBank error: payment type or bank code missing
4720 Rate in Rete: communication with Consel failed
4730 C-pay: communication with Compass failed
4731 Not authorized transaction by Compass
4732 Transazione non autorizzata da Consel
4733 Apple Pay: unable to decrypt the PKPaymentToken - please check the Payment Processing Certificate
4734 Apple Pay: PKPaymentToken expired
4735 GooglePay error: unable to decrypt token
4800 Expired session
4801 Invalid ShopTransactionID value
4802 Currency or Amount don’t match the original transaction
5001 AmazonPay error: Payment Method not allowed. Let the buyer choose a different payment method.
5002 AmazonPay error: Payment Plan not set. Let the buyer choose a payment plan.
5003 AmazonPay error: Shipping address not set. Let the buyer set a shipping address.
7400 Authorization denied
7401 Authorization refused by credit card companies
7402 Card not qualified
7403 Card not recognized
7404 Card expired
7405 Call credit card company
7406 Wrong card date
7407 Wrong transaction date
7408 System error
7409 Merchant not recognized
7410 Invalid format
7411 Amount not available
7412 Not settled
7413 Operation not allowed
7414 Network not available
7415 Collect card
7416 PIN attempts exhausted
7417 Blocked terminal
7418 Forcedly Closed terminal
7419 Not permitted transaction
7420 Not authorized transaction
7421 Service interrupted at 01/01/2002
7500 Authorization denied
7600 Authorization denied
8000 File correctly processed
8001 Header/bottom record not found
8002 Merchant code not set
8003 Incorrect row number
8004 Incorrect file format
8005 Merchant not enabled
8006 Verify By Visa
8007 Feature disabled for VISA credit card
8008 Feature disabled
8009 Payment interrupted
8010 Wrong credit card number for this transaction
8011 Transaction correctly received
8012 Authorization not found
8013 Settlement not found
8014 Settlement amount > Authorization amount
8015 Refund amount > balance
8016 Transaction without settlement
8017 File waiting to be processed
8018 File correctly processed
8021 Feature disable for MASTERCARD credit card
8022 Feature disable for JCB credit card
8023 Feature disabled for MAESTRO cards
8026 Soft decline - Cardholder authentication required
8027 Failed authentication
8028 Failed authentication - Issuer is rejecting authentication
8029 Failed authentication - ACS Technical or other problem
8030 Not Authenticated - Card authentication failed
8031 Not Authenticated - Invalid card number
8032 Not Authenticated - No Card record
8033 Not Authenticated - Suspected fraud
8034 Not Authenticated - Transaction not permitted to cardholder
8035 Not Authenticated - Exceeds ACS maximum challenges
8036 Not Authenticated - Reserved for DS use
8037 Not Authenticated - Invalid transaction
8038 Not Authenticated - Transaction timed out at the ACS
8888 UP Mobile Payment
9991 Browser not supported
9992 Error creating iFrame
9997 Phase with error
9998 Phase correctly ended
9999 System Error

Payment Type Codes

Description PaymentType
ALIPAY S2PALI
APPLEPAY APPLEPAY
BANCOMAT PAY BANCOMATPAY
BANCONTACT BANCONTACT
COMPASS C-PAY COMPASS
CONSEL RATE IN RETE CONSEL
CREDIT CARDS CREDITCARD
EPS S2PEPS
GIROPAY S2PGIR
HYPE HYPE
IDEAL S2PIDE
IDEAL (Direct) IDEAL
KLARNA KLARNA
KONBINI S2PKON
MERCADOPAGO S2PMER
MULTIBANCO S2PMUL
MYBANK MYBANK
ONECARD ONECARD
PAYPAL PAYPAL
PAYSAFECARD S2PPSC
SATISPAY SATISPAY
SOFORT S2PSOF
SOFORT (Direct) SOFORT
TRUSTPAY TRUSTPAY
UNIONPAY S2PUNI
WEBMONEY S2PWMO
YANDEX S2PYAN

For more informations about payment types, read the docs.

Currency Codes

Currency codes are handled by Axerve Ecommerce Solutions using the currency attribute.

UIC code ISO code ISO number Description
187 AED 784 United Arab Emirates dirham
216 ARS 32 Peso Argentina
109 AUD 36 Australian dollar
262 BGN 975 Bulgarian lev
74 BOB 068 Boliviano
234 BRL 986 Brazilian real
12 CAD 124 Canadian dollar
3 CHF 756 Swiss franc
29 CLP 152 Chilean Peso
144 CNY 156 Chinese yuan
40 COP 170 Peso Colombia
77 CRC 188 Costa Rican Colon
223 CZK 203 Czech koruna
7 DKK 208 Danish krone
116 DOP 214 Dominican Peso
2 GBP 826 Pound sterling
78 GTQ 320 Quetzal
103 HKD 344 Hong Kong dollar
118 HNL 340 Lempira
153 HUF 348 Hungarian forint
203 ILS 376 Israeli new shekel
31 INR 356 Indian rupee
62 ISK 352 Icelandic króna
71 JPY 392 Japanese yen
119 KRW 410 South Korean won
55 MYR 458 Malaysian ringgit
222 MXN 484 Mexican Peso
120 NIO 558 Cordoba
8 NOK 578 Norwegian krone
113 NZD 554 New Zealand dollar
201 PEN 604 Nuevo Sol
237 PLN 985 Polish złoty
101 PYG 600 Paraguayan Guarani
189 QAR 634 Qatar Riyal
270 RON 946 Romanian leu
244 RUB 643 Russian ruble
75 SAR 682 Saudi riyal
9 SEK 752 Swedish krona/kronor
124 SGD 702 Singapore dollar
267 TRY 949 Turkish lira
143 TWD 901 New Taiwan dollar
241 UAH 980 Ukrainian hryvnia
1 USD 840 United States dollar

Paypal Country Codes

You can find all the Country Codes that are supported by Paypal at this link and are also reported here for simplicity.

Country or Region Supported Country or Region Code
ALBANIA AL
ALGERIA DZ
ANDORRA AD
ANGOLA AO
ANGUILLA AI
ANTIGUA & BARBUDA AG
ARGENTINA AR
ARMENIA AM
ARUBA AW
AUSTRALIA AU
AUSTRIA AT
AZERBAIJAN AZ
BAHAMAS BS
BAHRAIN BH
BARBADOS BB
BELARUS BY
BELGIUM BE
BELIZE BZ
BENIN BJ
BERMUDA BM
BHUTAN BT
BOLIVIA BO
BOSNIA & HERZEGOVINA BA
BOTSWANA BW
BRAZIL BR
BRITISH VIRGIN ISLANDS VG
BRUNEI BN
BULGARIA BG
BURKINA FASO BF
BURUNDI BI
CAMBODIA KH
CAMEROON CM
CANADA CA
CAPE VERDE CV
CAYMAN ISLANDS KY
CHAD TD
CHILE CL
CHINA CN (For domestic Chinese bank transactions only)
CHINA WORLDWIDE C2 (For CUP, bank card and cross-border transactions)
COLOMBIA CO
COMOROS KM
CONGO - BRAZZAVILLE CG
CONGO - KINSHASA CD
COOK ISLANDS CK
COSTA RICA CR
CÔTE D’IVOIRE CI
CROATIA HR
CYPRUS CY
CZECH REPUBLIC CZ
DENMARK DK
DJIBOUTI DJ
DOMINICA DM
DOMINICAN REPUBLIC DO
ECUADOR EC
EGYPT EG
EL SALVADOR SV
ERITREA ER
ESTONIA EE
ETHIOPIA ET
FALKLAND ISLANDS FK
FAROE ISLANDS FO
FIJI FJ
FINLAND FI
FRANCE FR
FRENCH GUIANA GF
FRENCH POLYNESIA PF
GABON GA
GAMBIA GM
GEORGIA GE
GERMANY DE
GIBRALTAR GI
GREECE GR
GREENLAND GL
GRENADA GD
GUADELOUPE GP
GUATEMALA GT
GUINEA GN
GUINEA-BISSAU GW
GUYANA GY
HONDURAS HN
HONG KONG SAR CHINA HK
HUNGARY HU
ICELAND IS
INDIA IN
INDONESIA ID
IRELAND IE
ISRAEL IL
ITALY IT
JAMAICA JM
JAPAN JP
JORDAN JO
KAZAKHSTAN KZ
KENYA KE
KIRIBATI KI
KUWAIT KW
KYRGYZSTAN KG
LAOS LA
LATVIA LV
LESOTHO LS
LIECHTENSTEIN LI
LITHUANIA LT
LUXEMBOURG LU
MACEDONIA MK
MADAGASCAR MG
MALAWI MW
MALAYSIA MY
MALDIVES MV
MALI ML
MALTA MT
MARSHALL ISLANDS MH
MARTINIQUE MQ
MAURITANIA MR
MAURITIUS MU
MAYOTTE YT
MEXICO MX
MICRONESIA FM
MOLDOVA MD
MONACO MC
MONGOLIA MN
MONTENEGRO ME
MONTSERRAT MS
MOROCCO MA
MOZAMBIQUE MZ
NAMIBIA NA
NAURU NR
NEPAL NP
NETHERLANDS NL
NEW CALEDONIA NC
NEW ZEALAND NZ
NICARAGUA NI
NIGER NE
NIGERIA NG
NIUE NU
NORFOLK ISLAND NF
NORWAY NO
OMAN OM
PALAU PW
PANAMA PA
PAPUA NEW GUINEA PG
PARAGUAY PY
PERU PE
PHILIPPINES PH
PITCAIRN ISLANDS PN
POLAND PL
PORTUGAL PT
QATAR QA
RÉUNION RE
ROMANIA RO
RUSSIA RU
RWANDA RW
SAMOA WS
SAN MARINO SM
SÃO TOMÉ & PRÍNCIPE ST
SAUDI ARABIA SA
SENEGAL SN
SERBIA RS
SEYCHELLES SC
SIERRA LEONE SL
SINGAPORE SG
SLOVAKIA SK
SLOVENIA SI
SOLOMON ISLANDS SB
SOMALIA SO
SOUTH AFRICA ZA
SOUTH KOREA KR
SPAIN ES
SRI LANKA LK
ST. HELENA SH
ST. KITTS & NEVIS KN
ST. LUCIA LC
ST. PIERRE & MIQUELON PM
ST. VINCENT & GRENADINES VC
SURINAME SR
SVALBARD & JAN MAYEN SJ
SWAZILAND SZ
SWEDEN SE
SWITZERLAND CH
TAIWAN TW
TAJIKISTAN TJ
TANZANIA TZ
THAILAND TH
TOGO TG
TONGA TO
TRINIDAD & TOBAGO TT
TUNISIA TN
TURKMENISTAN TM
TURKS & CAICOS ISLANDS TC
TUVALU TV
UGANDA UG
UKRAINE UA
UNITED ARAB EMIRATES AE
UNITED KINGDOM GB
UNITED STATES US
URUGUAY UY
VANUATU VU
VATICAN CITY VA
VENEZUELA VE
VIETNAM VN
WALLIS & FUTUNA WF
YEMEN YE
ZAMBIA ZM
ZIMBABWE ZW

Paypal State & Province Codes

Paypal state codes can be found at this link.

Here are reported for simplicity.

Note: Some of the following tables list only the State or Province name and do not include a State or Province code. For these countries, use the spelling of the State or Province name exactly as it is written in the table.

Countries that use State Codes:

Argentina

Province Name Province Code
Buenos Aires (Ciudad) CIUDAD AUTÓNOMA DE BUENOS AIRES
Buenos Aires (Provincia) BUENOS AIRES
Catamarca CATAMARCA
Chaco CHACO
Chubut CHUBUT
Corrientes CORRIENTES
Córdoba CÓRDOBA
Entre Ríos ENTRE RÍOS
Formosa FORMOSA
Jujuy JUJUY
La Pampa LA PAMPA
La Rioja LA RIOJA
Mendoza MENDOZA
Misiones MISIONES
Neuquén NEUQUÉN
Río Negro RÍO NEGRO
Salta SALTA
San Juan SAN JUAN
San Luis SAN LUIS
Santa Cruz SANTA CRUZ
Santa Fe SANTA FE
Santiago del Estero SANTIAGO DEL ESTERO
Tierra del Fuego TIERRA DEL FUEGO
Tucumán TUCUMÁN

Brazil

State Name State Code
Acre AC
Alagoas AL
Amapá AP
Amazonas AM
Bahia BA
Ceará CE
Distrito Federal DF
Espírito Santo ES
Goiás GO
Maranhão MA
Mato Grosso MT
Mato Grosso do Sul MS
Minas Gerais MG
Paraná PR
Paraíba PB
Pará PA
Pernambuco PE
Piauí PI
Rio Grande do Norte RN
Rio Grande do Sul RS
Rio de Janeiro RJ
Rondônia RO
Roraima RR
Santa Catarina SC
Sergipe SE
São Paulo SP
Tocantins TO

Canada

Province Name Province Code
Alberta AB
British Columbia BC
Manitoba MB
New Brunswick NB
Newfoundland and Labrador NL
Northwest Territories NT
Nova Scotia NS
Nunavut NU
Ontario ON
Prince Edward Island PE
Quebec QC
Saskatchewan SK
Yukon YT

India

State Name State Code
Andaman and Nicobar Islands Andaman and Nicobar Islands
Andhra Pradesh Andhra Pradesh
Army Post Office APO
Arunachal Pradesh Arunachal Pradesh
Assam Assam
Bihar Bihar
Chandigarh Chandigarh
Chhattisgarh Chhattisgarh
Dadra and Nagar Haveli Dadra and Nagar Haveli
Daman and Diu Daman and Diu
Goa Goa
Gujarat Gujarat
Haryana Haryana
Himachal Pradesh Himachal Pradesh
Jammu and Kashmir Jammu and Kashmir
Jharkhand Jharkhand
Karnataka Karnataka
Kerala Kerala
Lakshadweep Lakshadweep
Madhya Pradesh Madhya Pradesh
Maharashtra Maharashtra
Manipur Manipur
Meghalaya Meghalaya
Mizoram Mizoram
Nagaland Nagaland
National Capital Territory of Delhi Delhi (NCT)
Odisha Odisha
Puducherry Puducherry
Punjab Punjab
Rajasthan Rajasthan
Sikkim Sikkim
Tamil Nadu Tamil Nadu
Telangana Telangana
Tripura Tripura
Uttar Pradesh Uttar Pradesh
Uttarakhand Uttarakhand
West Bengal West Bengal

Italy

Province Name Province Code
Agrigento AG
Alessandria AL
Ancona AN
Aosta AO
Arezzo AR
Ascoli Piceno AP
Asti AT
Avellino AV
Bari BA
Barletta-Andria-Trani BT
Belluno BL
Benevento BN
Bergamo BG
Biella BI
Bologna BO
Bolzano BZ
Brescia BS
Brindisi BR
Cagliari CA
Caltanissetta CL
Campobasso CB
Carbonia-Iglesias CI
Caserta CE
Catania CT
Catanzaro CZ
Chieti CH
Como CO
Cosenza CS
Cremona CR
Crotone KR
Cuneo CN
Enna EN
Fermo FM
Ferrara FE
Firenze FI
Foggia FG
Forlì-Cesena FC
Frosinone FR
Genova GE
Gorizia GO
Grosseto GR
Imperia IM
Isernia IS
L'Aquila AQ
La Spezia SP
Latina LT
Lecce LE
Lecco LC
Livorno LI
Lodi LO
Lucca LU
Macerata MC
Mantova MN
Massa-Carrara MS
Matera MT
Medio Campidano VS
Messina ME
Milano MI
Modena MO
Monza e della Brianza MB
Napoli NA
Novara NO
Nuoro NU
Ogliastra OG
Olbia-Tempio OT
Oristano OR
Padova PD
Palermo PA
Parma PR
Pavia PV
Perugia PG
Pesaro e Urbino PU
Pescara PE
Piacenza PC
Pisa PI
Pistoia PT
Pordenone PN
Potenza PZ
Prato PO
Ragusa RG
Ravenna RA
Reggio Calabria RC
Reggio Emilia RE
Rieti RI
Rimini RN
Roma RM
Rovigo RO
Salerno SA
Sassari SS
Savona SV
Siena SI
Siracusa SR
Sondrio SO
Taranto TA
Teramo TE
Terni TR
Torino TO
Trapani TP
Trento TN
Treviso TV
Trieste TS
Udine UD
Varese VA
Venezia VE
Verbano-Cusio-Ossola VB
Vercelli VC
Verona VR
Vibo Valentia VV
Vicenza VI
Viterbo VT

Japan

Prefecture Name Prefecture Code
Aichi AICHI-KEN
Akita AKITA-KEN
Aomori AOMORI-KEN
Chiba CHIBA-KEN
Ehime EHIME-KEN
Fukui FUKUI-KEN
Fukuoka FUKUOKA-KEN
Fukushima FUKUSHIMA-KEN
Gifu GIFU-KEN
Gunma GUNMA-KEN
Hiroshima HIROSHIMA-KEN
Hokkaido HOKKAIDO
Hyogo HYOGO-KEN
Ibaraki IBARAKI-KEN
Ishikawa ISHIKAWA-KEN
Iwate IWATE-KEN
Kagawa KAGAWA-KEN
Kagoshima KAGOSHIMA-KEN
Kanagawa KANAGAWA-KEN
Kochi KOCHI-KEN
Kumamoto KUMAMOTO-KEN
Kyoto KYOTO-FU
Mie MIE-KEN
Miyagi MIYAGI-KEN
Miyazaki MIYAZAKI-KEN
Nagano NAGANO-KEN
Nagasaki NAGASAKI-KEN
Nara NARA-KEN
Niigata NIIGATA-KEN
Oita OITA-KEN
Okayama OKAYAMA-KEN
Okinawa OKINAWA-KEN
Osaka OSAKA-FU
Saga SAGA-KEN
Saitama SAITAMA-KEN
Shiga SHIGA-KEN
Shimane SHIMANE-KEN
Shizuoka SHIZUOKA-KEN
Tochigi TOCHIGI-KEN
Tokushima TOKUSHIMA-KEN
Tokyo TOKYO-TO
Tottori TOTTORI-KEN
Toyama TOYAMA-KEN
Wakayama WAKAYAMA-KEN
Yamagata YAMAGATA-KEN
Yamaguchi YAMAGUCHI-KEN
Yamanashi YAMANASHI-KEN

Mexico

State Name State Code
Aguascalientes AGS
Baja California BC
Baja California Sur BCS
Campeche CAMP
Chiapas CHIS
Chihuahua CHIH
Coahuila COAH
Colima COL
Distrito Federal DF
Durango DGO
Estado de México MEX
Guanajuato GTO
Guerrero GRO
Hidalgo HGO
Jalisco JAL
Michoacán MICH
Morelos MOR
Nayarit NAY
Nuevo León NL
Oaxaca OAX
Puebla PUE
Querétaro QRO
Quintana Roo Q ROO
San Luis Potosí SLP
Sinaloa SIN
Sonora SON
Tabasco TAB
Tamaulipas TAMPS
Tlaxcala TLAX
Veracruz VER
Yucatán YUC
Zacatecas ZAC

Thailand

Province Name
Amnat Charoen
Ang Thong
Bangkok
Bueng Kan
Buri Ram
Chachoengsao
Chai Nat
Chaiyaphum
Chanthaburi
Chiang Mai
Chiang Rai
Chon Buri
Chumphon
Kalasin
Kamphaeng Phet
Kanchanaburi
Khon Kaen
Krabi
Lampang
Lamphun
Loei
Lop Buri
Mae Hong Son
Maha Sarakham
Mukdahan
Nakhon Nayok
Nakhon Pathom
Nakhon Phanom
Nakhon Ratchasima
Nakhon Sawan
Nakhon Si Thammarat
Nan
Narathiwat
Nong Bua Lamphu
Nong Khai
Nonthaburi
Pathum Thani
Pattani
Phang Nga
Phatthalung
Phatthaya
Phayao
Phetchabun
Phetchaburi
Phichit
Phitsanulok
Phra Nakhon Si Ayutthaya
Phrae
Phuket
Prachin Buri
Prachuap Khiri Khan
Ranong
Ratchaburi
Rayong
Roi Et
Sa Kaeo
Sakon Nakhon
Samut Prakan
Samut Sakhon
Samut Songkhram
Saraburi
Satun
Si Sa Ket
Sing Buri
Songkhla
Sukhothai
Suphan Buri
Surat Thani
Surin
Tak
Trang
Trat
Ubon Ratchathani
Udon Thani
Uthai Thani
Uttaradit
Yala
Yasothon

United States

State Name State Code
Alabama AL
Alaska AK
Arizona AZ
Arkansas AR
California CA
Colorado CO
Connecticut CT
Delaware DE
District of Columbia DC
Florida FL
Georgia GA
Hawaii HI
Idaho ID
Illinois IL
Indiana IN
Iowa IA
Kansas KS
Kentucky KY
Louisiana LA
Maine ME
Maryland MD
Massachusetts MA
Michigan MI
Minnesota MN
Mississippi MS
Missouri MO
Montana MT
Nebraska NE
Nevada NV
New Hampshire NH
New Jersey NJ
New Mexico NM
New York NY
North Carolina NC
North Dakota ND
Ohio OH
Oklahoma OK
Oregon OR
Pennsylvania PA
Puerto Rico PR
Rhode Island RI
South Carolina SC
South Dakota SD
Tennessee TN
Texas TX
Utah UT
Vermont VT
Virginia VA
Washington WA
West Virginia WV
Wisconsin WI
Wyoming WY

Armed Forces APO

State Name State Code
Armed Forces Americas AA
Armed Forces Europe AE
Armed Forces Pacific AP

Outlying Areas

State Name State Code
American Samoa AS
Federated States of Micronesia FM
Guam GU
Marshall Islands MH
Northern Mariana Islands MP
Palau PW
Virgin Islands VI

Language Codes

The language code is handled by Axerve Ecommerce Solutions using the Language attribute.

Code Description
1 Italian
2 English
3 Spanish
4 French
5 German

Alert Codes

Alert Codes are described at Better Risk Management: reacting to suspicious activity.

Code Description
2000 Transaction exceeds maximum operations number in time period
2001 Transaction exceeds maximum number of operations performed by the same buyer in time period
2002 Transaction exceeds maximum amount in time period
2003 Transaction exceeds maximum amount payable by same buyer in time period
2004 Transaction contains a field value that had been declared not acceptable

AlertDescrptions is also available in other languages.

Event Types

When something happens to a transaction (e.g. authorization, settling, cancel, etc.) Axerve Ecommerce Solutions registers the event. Here is the list of the codes for every event.

Event code Description
AUT Authorized
CAN Cancelled
MOV Amount transferred
PRE Amount reserved for transfer
REQ Refund request
STO Refund event

For more informations about these states refer to the documentation.

Risk Based Authentication (RBA)

RBA (Risk Based Authentication) by Banca Sella

For operations that do not qualify for a high-risk operation, the European PSD2 legislation provides the possibility of activating exemptions in order to ensure a simplified shopping experience and a better conversion rate for shopping carts.

The RBA solution to simplify purchasing

RBA (Risk Based Authentication) is a solution that analyses in real time the risk of fraud behind transactions, and if the risk is determined as low, the exemption for TRA (Transaction Risk Analysis) is activated.

The service applies to Ecommerce transactions and will soon also be available for Magento, WooCommerce, Prestashop and Salesforce plugins.

How to take advantage of the exemptions

Complete transactions data (such as transaction details, delivery address, etc.) and the customer data (e.g. transaction’s beneficiary, location of the buyer, billing address, etc.) must be transmitted to the payment gateway. For this purpose, the enhancement of some fields, previously optional and now fundamental for the activation of the exemption is required.

Information on the shipping and billing address must always be completed. If the shipping address is not available, this field must be the same as the billing address (for example when products are services).

Detail of the necessary fields

The integration of the required fields differs by connection method (between SOAP API with PAGAM page and Server-to-Server and REST API).

SOAP - Pagam

Name Description
buyerName Buyer’s name and surname.
buyerEmail Buyer’s e-mail address.
OrderDetails:
  • CustomerDetail
    • FirstName
    • Lastname
    • PrimaryEmail
  • Shipping address
    • FirstName
    • Lastname
    • StreetName
    • City
    • ZipCode
    • State
    • CountryCode
  • Billing address
    • FirstName
    • Lastname
    • StreetName
    • City
    • ZipCode
    • State
    • CountryCode
A container object of other data.
transDetails.threeDsContainer.buyerDetails:
  • shippingAddress
    • City
    • Country
    • Postcode
    • State
  • billingAddress
    • City
    • Country
    • Postcode
    • State
  • cardHolder
    • Name
    • Email
Container of additional data defined in 3DS2 protocol, that better define the transaction. The data here included will be used for assessing the risk level of the transaction with the purpose of ensuring security without affecting the buyer’s experience.

SOAP – Server to server

Name Description
buyerName Buyer’s name and surname.
buyerEmail Buyer’s e-mail address.
clientIP IP of the client.
OrderDetails:
  • CustomerDetail
    • FirstName
    • Lastname
    • PrimaryEmail
  • Shipping address
    • FirstName
    • Lastname
    • StreetName
    • City
    • ZipCode
    • State
    • CountryCode
  • Billing address
    • FirstName
    • Lastname
    • StreetName
    • City
    • ZipCode
    • State
    • CountryCode
A container object of other data.
transDetails.threeDsContainer.buyerDetails:
  • shippingAddress
    • City
    • Country
    • Postcode
    • State
  • billingAddress
    • City
    • Country
    • Postcode
    • State
  • cardHolder
    • Name
    • Email
Container of additional data defined in 3DS2 protocol, that better define the transaction. The data here included will be used for assessing the risk level of the transaction with the purpose of ensuring security without affecting the buyer’s experience.

REST

Name Description
buyerName Buyer’s name and surname.
buyerEmail Buyer’s e-mail address.
clientIP IP of the client.
OrderDetails:
  • CustomerDetail
    • FirstName
    • Lastname
    • PrimaryEmail
  • Shipping address
    • FirstName
    • Lastname
    • StreetName
    • City
    • ZipCode
    • State
    • CountryCode
  • Billing address
    • FirstName
    • Lastname
    • StreetName
    • City
    • ZipCode
    • State
    • CountryCode
A container object of other data.
transDetails.threeDsContainer.buyerDetails:
  • shippingAddress
    • City
    • Country
    • Postcode
    • State
  • billingAddress
    • City
    • Country
    • Postcode
    • State
  • cardHolder
    • Name
    • Email
Container of additional data defined in 3DS2 protocol, that better define the transaction. The data here included will be used for assessing the risk level of the transaction with the purpose of ensuring security without affecting the buyer’s experience.

Frequency Codes

Used for batch jobs.

Description Code
Every day G
Sunday 1S
Monday 2S
Tuesday 3S
Wednesday 4S
Thursday 5S
Friday 6S
Saturday 7S
1 month day 1M
2 month day 2M
3 month day 3M
4 month day 4M
5 month day 5M
6 month day 6M
7 month day 7M
8 month day 8M
9 month day 9M
10 month day 10M
11 month day 11M
12 month day 12M
13 month day 13M
14 month day 14M
15 month day 15M
16 month day 16M
17 month day 17M
18 month day 18M
19 month day 19M
20 month day 20M
21 month day 21M
22 month day 22M
23 month day 23M
24 month day 24M
25 month day 25M
26 month day 26M
27 month day 27M
28 month day 28M
29 month day 29M
30 month day 30M
31 month day 31M

Company values

The following table lists all possible values of the company field returned by many calls mentioned in this documentation.

Description Code
SlimPay 1
WECHAT 2
BITCOIN 3
CardsRussia 4
CASHU 5
TRUSTPAY 6
BIZUM 7
KLARNAPAYNOW 8
BancomatPay 9
GIROPAY 10
EPS 11
MERCADOPAGO 12
KONBINI 13
Tenpay 14
PayPal 15
ALIPAY 16
PayPal_BNPL 17
WEBMONEY 18
Paysafecard 19
QIWI 20
YANDEX 21
Ideal 22
ONECARD 23
BANCONTACT 24
SOFORT 25
FABRICKPASS 26
APPPAGO 27
Klarna 28
UNIONPAY 29
PRZELEWY24 30
KLARNAPAY 31
MULTIBANCO 32
PAYWITHMYBANK 33
KLARNA 34

PaymentMethod values

The following table lists all possible values of the paymentMethod field returned by many calls mentioned in this documentation.

Code
AMAZONPAY
AMEX
AMEX SAFE KEY
APPLEPAY - MAESTRO
APPLEPAY - MAESTRO SECURECODE
APPLEPAY - MASTERCARD
APPLEPAY - MASTERCARD SECURECODE
APPLEPAY - VISA
APPLEPAY - VISA VBV
AURA
BANKPASS Amex
BANKPASS Diners
BANKPASS Jcb
BANKPASS Maestro
BANKPASS Mastercard
BANKPASS PagoBancomat
BANKPASS Visa
Bonifico OnLine
COMPASS C-PAY
Carta I.DE.A.
Consel Rate in Rete
DINERS
FIDELITY CARD
GOOGLEPAY - MAESTRO
GOOGLEPAY - MAESTRO SECURECODE
GOOGLEPAY - MASTERCARD
GOOGLEPAY - MASTERCARD SECURECODE
GOOGLEPAY - VISA
GOOGLEPAY - VISA VBV
HYPE - AMEX
HYPE - AMEX SAFE KEY
HYPE - DINERS
HYPE - JCB
HYPE - MAESTRO
HYPE - MAESTRO SECURECODE
HYPE - MASTERCARD
HYPE - MASTERCARD SECURECODE
HYPE - VISA
HYPE - VISA VBV
IDEAL
JCB
MAESTRO
MAESTRO SECURECODE
MASTERCARD
MASTERCARD SECURECODE
MASTERPASS - AMEX
MASTERPASS - AMEX SAFE KEY
MASTERPASS - DINERS
MASTERPASS - JCB
MASTERPASS - MAESTRO
MASTERPASS - MAESTRO SECURECODE
MASTERPASS - MASTERCARD
MASTERPASS - MASTERCARD SECURECODE
MASTERPASS - VISA
MASTERPASS - VISA VBV
MOBILMAT
MOBILMAT AMEX
MOBILMAT AURA
MOBILMAT DINERS
MOBILMAT JCB
MOBILMAT MASTERCARD
MOBILMAT VISA
MyBank - ePayment
PayPal
SATISPAY
SOFORT
TIM Personal - AMEX
TIM Personal - DINERS
TIM Personal - JCB
TIM Personal - MASTERCARD
TIM Personal - VISA
UP - AMEX
UP - AMEX SAFE KEY
UP - DINERS
UP - JCB
UP - MAESTRO
UP - MAESTRO SECURECODE
UP - MASTERCARD
UP - MASTERCARD SECURECODE
UP - VISA
UP - VISA VBV
VISA
VISA VBV

Useful links, Privacy and Cookie Policy

Can’t find what you’re looking for? Contact us by phone +39 015 24 34 640 or e-mail ecommerce@sella.it.

© 2007-2024 Axerve S.p.A. – Company with Single Shareholder belonging to the Maurizio Sella S.a.a. VAT Group with VAT no. 02675650028 – Tax Code 02686620028 – Biella Court registration no. 71524 – Piazza Gaudenzio Sella 1, 13900 Biella – Share Capital € 4.000.000,00 fully paid-in – Registered in the Reg. Impr. C.C.I.A.A. Monte Rosa Laghi Alto Piemonte – Registered in the Register of Payment Institutions.