open menu
axerve docs
Payments/Payment management/Accepting payments/Authorization Request

Authorization Request 


Authorization is the payment operation that consists in sending all of the information required to make a payment transaction to the bank’s server. It also consists in retrieving the transaction result after it has been processed by the bank.

The specific WSs2s method to use for this purpose is CallPagamS2Sapi link.

However, before using this method, it is necessary to assign a value to these required fields:

  • shopLogin (Merchant Code)

  • uicCode (Currency Codeapi link)

  • amount (Amount)

  • shopTransactionId (Transaction ID Code)

In case you are using the credit card as payment method, you must fill the following fields:

  • cardNumber (Credit Card Account Number)

  • expiryMonth (Card Expiration Month)

  • expiryYear (Card Expiration Year)

Otherwise, if you are using tokens, you must fill in the field:

  • TokenValue (Token used for the transaction. In case of PayPal Billing Agreements this is the token provided by PayPal. If a merchant belongs to a group they can use their own tokens or one of the tokens of the group’s components)

It is mandatory to fill in one of the following values: credit card numbers and token.

The following fields may optionally be assigned:

  • buyerName (Buyer’s name)

  • buyerEmail (Buyer’s e-mail address)

  • languageId (Language code)

  • cvv (String containing the Card Verification Value printed on the credit card as specified in the chapter “Managing the CVV field”)

  • transKey (used in Verified by Visa Transactions)

  • PARes (used in Verified by Visa Transactions)

  • customInfo (String containing possible customised fields, declared Parameters in the relevant section of the Back Office environment , BackOffice -> PaymentPage -> Fields&Parameters)

  • requestToken (MASKEDPAN for a Standard Token, any other value for Custom Token)

  • ClientIP (For PayPal Billing Agreements it is required only in the “one click” mode transaction. For AMEX transaction not in Euro, in this field the merchant could provide the ClientIP address to activate the Enhanced Authorization AAV )

  • itemType (Item Category Digital/Physical)

  • shippingDetails (shipToNameshipToStreetshipToCityshipToStateshipToCountryCodeshipToZipshipToStreet2)

The CallPagamS2S method sends all previously assigned data to Axerve Ecommerce Solutions; it checks the correspondence between data received and the configuration set within the Back Office environment, and, if these match, it will operate.

If the M.O.T.O. configuration anticipates a separation between the authorization and the settlement phase, the activity of Axerve Ecommerce Solutions will be limited to the authorization request only. Checkout the Settlements page to understand how it works.

If, conversely, the M.O.T.O. configuration anticipates that the authorization and the settlement phase will occur simultaneously, then Axerve Ecommerce Solutions will carry out the authorization request and, if the response is positive, subsequently perform the settlement operation.

After the CallPagamS2S method is performed, it is possible to know the outcome of the transaction by using the returned XML file:

1<GestPayS2S xmlns="">
2  <TransactionType>PAGAM</TransactionType>
3  <TransactionResult>OK</TransactionResult>
4  <ShopTransactionID>prova2</ShopTransactionID>
5  <BankTransactionID>65</BankTransactionID>
6  <AuthorizationCode>365530</AuthorizationCode>
7  <Currency>242</Currency>
8  <Amount>0.90</Amount>
9  <Country>ITALIA</Country>
10  <Buyer>
11    <BuyerName/>
12    <BuyerEmail/>
13  </Buyer>
14  <CustomInfo/>
15  <TDLevel/>
16  <ErrorCode>0</ErrorCode>
17  <ErrorDescription>Transazione correttamente effettuata</ErrorDescription>
18  <AlertCode/>
19  <AlertDescription/>
20  <TransactionKey>579428899</TransactionKey>
21  <VbV>
22    <VbVFlag>KO</VbVFlag>
23    <VbVBuyer/>
24    <VbVRisp/>
25  </VbV>

First, check TransactionResult which will return a string OK if the transaction was authorised or a string KO if the transaction was not authorised.

If TransactionResult returns KO, by using the ErrorCode value it is then possible to know whether the failure is caused by technical problems or by a denied authorization by the credit card network:

  • If ErrorCode returns a <> 0 value, the authorization of the transaction was negative; the returned value will be different according to the specific reason for the failure.

  • The ErrorDescription value will return a description (in the language set in the Back Office environment) of the reason for the failure.

If TransactionResult returns OK, the transaction was authorised (and, if the M.O.T.O. was simultaneous, settled as well). It will be then possible to obtain further information about the transaction, using the following values:

  • BankTransactionID to obtain the unique code assigned to the transaction by Axerve Ecommerce Solutions

  • AuthorizationCode to obtain the authorization code assigned to the transaction by the international credit card network

  • AlertCode (and the corresponding AlertDescription) in the case which Risk Management criteria were set through BackOffice and the transaction violated one of them; if no Risk Management criteria were violated, AlertCode will be empty.

  • CustomInfo returns the CustomInfo tag passed during the transaction

  • TDLevel Level of authentication for 3D-Secure transactions. The string may have the value FULL or HALF

  • VBV Returns the values for VbV as follows:

    • VBVFlag Returns the flag Verified by Visa (OK or KO)

    • VBVBuyer Returns the flag Full Verified by Visa transaction

    • VBVRisp Returns the encrypted string obtained by Visa directory

All the other returned values can be used as usual.

Settle an authorized paymentnext