Professional Integration

This document is designed to provide you details on how to integrate your business to the HiPay Professional payment gateway. This document provides step-by-step instructions on how to simply and quickly get up and running with our services as well as detailed reference material.

Security Considerations

HiPay Professional SOAP API service is protected to:
      • ensure that only authorized Merchants use it,
      • prevent payment information from being compromised

Integration Guidelines

This chapter outlines the basic integration requirements that you app must meet.

Submitting a Request

Endpoints
There are two endpoints (base URLs) that you can make your API calls to.
Environment Endpoint
Stage https://test-ws.hipay.com/
Production https://ws.hipay.com/
Authentication
Overview Authentication
All requests to HiPay SOAP REST API require the Merchant to authenticate himself at each request. Your API credentials can be found in the Merchant Interface under Sell with Hipay -> Hipay integration -> Merchant Tool Kit / API -> Webservice Access.
Character Encoding
All parameters accept UTF-8 encoded text via the API. All other encodings must be converted to UTF-8 before sending them to the HiPay API in order to guarantee that the data is not corrupted.

Response Handling

Whether a request succeeded or not, it is indicated by the HTTP status code. A 2xx status code indicates a success, whereas a 5xx status code indicates a failure.
Status Codes
The HiPay API attempts to return appropriate HTTP status codes for every request. These are the HTTP status codes you may receive and their meaning.
HTTP Status Description
200 OK The request was understood and is processing.
404 Not Found The resource requested does not exist.
500 Server Error The request has an error, mandatory parameters are missing or you are trying to send unknown parameters to the resource.
503 Service Unavailable HiPay API is temporarily unable to process the request. Try again later.
Format
The HiPay API will respond to your request in SOAP XML format. By default, HiPay SOAP API returns XML in a SOAP Envelope. For example, here is the default XML representation of a “generate” result.
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ns1="https://ws.hipay.com/soap/payment-v2">
    <SOAP-ENV:Body>
        <ns1:generateResponse>
            <generateResult>
                <redirectUrl>https://payment.hipay.com/index/pay/payid/716…7106fc</redirectUrl>
                <code>0</code>
                <description>N/A</description>
            </generateResult>
        </ns1:generateResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Error Handling

HiPay API returns one level of error information: a response body with additional details that can help you determine how to handle the exception.

Exception properties An exception has up to three properties.

PropertyDescription
code0 = OK / >0 = Error.
descriptionA descriptive message regarding the exception.

i.g. if you receive an exception with status code 400 (Bad Request), the and properties are useful for debugging what went wrong.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP- ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://ws.hipay.com/soap/payment-v2">
    <SOAP-ENV:Body>
        <ns1:generateResponse>
            <generateResult>
                <redirectUrl/>
                <code>1</code>
                <description>Bad password for login '4f8x3x80fd4x476f1e227c68xefdx0x5'</description>
            </generateResult>
        </ns1:generateResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

SOAP API Resources

The following table lists the REST API resources used.

Resource Description
POST /soap/payment-v2/generate Allows you to request an order and initialize a hosted payment page.
POST /soap/transaction-v2/confirm A request instructing the payment gateway to capture a previously- authorized transaction, i.e. transfer the funds from the customer’s bank account to the merchant’s bank account. This transaction is always preceded by an authorization.
POST /soap/transaction-v2/cancel A request instructing the payment gateway to cancel a previously- authorized transaction. Only authorized transactions can be canceled, captured transactions must be refunded.
POST /soap/refund-v2/card A request instructing the payment gateway to fully refund a credit card previously captured transaction.

Request a New Order

At the time of payment, cardholders are redirected to a secured payment page hosted by HiPay. This page can be personalized with merchants’ CSS style sheet to fit his website look and feel. To post your CSS please go to “HiPay Professional integration -> Creating a button -> Edit (on your website details)“ Order Parameters
FieldName Format Length Req Description
wsLogin AN 32 M Your API Webservice Login.
wsPassword AN 32 M Your API Webservice Password.
websiteId N 11 M ID of the website created on merchants’ account.
categoryId N 11 M The order or product categories are attached to, and depend upon, the merchant site’s category. Depending on the category that is associated with the site, the categories that are available to the order and products will NOT be the same. You can obtain the list of order and product category ID’s for the merchant site at this URL: Production platform: https://payment.hipay.com/order/list-categories/id/[production websiteID] Stage platform: https://test-payment.hipay.com/order/list-categories/id/[stage websiteID]
currency A 3 M The currency specified in your HiPay Professional account. This three-character currency code complies with ISO 4217.
amount R M The total order amount. It should be calculated as a sum of the items purchased, plus the shipping fee (if present), plus the tax fee (if present).
rating AN 3 M Age category of your order. Accepted values : +12 : For ages 13 and over +16 : For ages 16 and over +18 : For ages 18 and over ALL : For all ages
locale AN 5 M Locale code of your customer (Default to en_GB – English – Great Britain).It may be used for sending confirmation emails to your customer or for displaying payment pages. Examples: en_GB fr_FR es_ES it_IT
customerIpAddress AN 15 M The IP address of your customer making a purchase.
executionDate AN 32 M Date and time of execution of the payment in MySQL DATETIME format (Y-m-dTH:i:s). e.g.: 2014-12-25T10:57:55
manualCapture N 1 M Indicates how you want to process the payment. 0: indicates transaction is sent for authorization, and if approved, is automatically submitted for capture. 1: indicates this transaction is sent for authorization only. The transaction will not be sent for settlement until the transaction is submitted for capture manually by the Merchant.
description AN 255 M The order short description.
customerEmail AN 32 The customer’s e-mail address.
urlCallback AN 255 M The URL will be used by our server to send you information in order to update your database. Please refer to “Server-to-Server notification” chapter.
urlAccept AN 255 The URL to return your customer to once the payment process is completed successfully.
urlDecline AN 255 The URL to return your customer to after the acquirer declines the payment.
urlCancel AN 255 The URL to return your customer to when he or her decides to abort the payment.
urlLogo AN 255 This URL is where the logo you want to appear on your payment page is located. Important: HTTPS protocol is required.
merchantReference AN 255 Merchants’ order refernce.
merchantComment AN 255 Merchants’ comment concerning the order.
emailCallback AN 255 Email used by HiPay Professional to post operation notifications.
freedata AN Custom data. You may use these parameters to submit values you wish to receive back in the API response messages or in the notifications, e.g. you can use these parameters to get back session data, order content or user info.
You must format it like this:
<freeData>
 <item>
  <key>keyOne</key>
  <value>ValueOne</value>
 </item>
 <item>
  <key>keyTwo</key>
  <value>ValueTwo</value>
 </item>
</freeData>

Response Fields The following table lists and describes the response fields.

Field NameDescription
redirectUrlPayment page URL. Merchant must redirect the customer’s browser to this URL.
codeStatus code of the answer.
descriptionReason description (if error).

Refund an order

To perform a refund on an existing transaction, make an HTTP POST request to the following resource.

Operation TypeResourceDescription
refund/soap/refund-v2/cardA request instructing the payment gateway to fully refund a previously credit card captured transaction.

Request Parameters

ParameterFormatLengthReqDescription
wsLoginAN32MYour API Webservice Login.
wsPasswordAN32MYour API Webservice Password.
websiteIdN32MId of merchants’ website were transaction was made.
transactionPublicIdAN32MThe unique identifier of the transaction sent to the merchant on the urlCallback (Notification) called “transid”.

Response Fields

The following table lists and describes the response fields.

Field NameDescription
transactionPublicIdThe unique identifier of the transaction.
codeStatus code of the answer.
descriptionDescription of the answer.
amountRefunded amount.
currencyCurrency of refunded transaction.

Maintenance Operations

To perform maintenance on an existing transaction, make an HTTP POST request to the following resources.

Operation TypeResourceDescription
confirm/soap/transaction-v2/confirmA request instructing the payment gateway to capture a previously-authorized transaction, i.e. transfer the funds from the customer’s bank account to the merchant’s bank account. This transaction is always preceded by an authorization.
cancel/soap/transaction-v2/cancelA request instructing the payment gateway to cancel a previously-authorized transaction. Only authorized transactions can be canceled, captured transactions must be refunded.

Request Parameters

ParameterFormatLengthReqDescription
wsLoginAN32MYour API Webservice Login.
wsPasswordAN32MYour API Webservice Password.
transactionPublicIdAN32MThe unique identifier of the transaction sent to the merchant on the urlCallback (Notification) called “transid”.

Response Fields

The following table lists and describes the response fields.

Field NameDescription
transactionPublicIdThe unique identifier of the transaction.
codeStatus code of the answer.
descriptionDescription of the answer.

Examples

Request

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://ws.hipay.com/soap/refund-v2">
       <SOAP-ENV:Body>
         <ns1:card>
          <parameters>
             <websiteId>107</websiteId>
           <transactionPublicId>51X6F4C37X253</transactionPublicId>
             <wsLogin>4f8x3e8xfd4ex76f1ex27c6xfefdb3e5</wsLogin>           <wsPassword>2x0c409xc4254x819bfx246d6x02d1x2</wsPassword>
          </parameters>
         </ns1:card>
       </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Response

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="https://ws.hipay.com/soap/refund-v2">
        <SOAP-ENV:Body>
         <ns1:cardResponse>
          <cardResult>
             <code>0</code>
             <description>Refund to credit card request for transaction 51X6F4C37X253 has been sent !</description>
             <currency>EUR</currency>
             <amount>4</amount>
             <transactionPublicId>51X6F4C37X253</transactionPublicId>
          </cardResult>
         </ns1:cardResponse>
        </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Server-to-Server Notifications

In order to notify events related to your payment system, such as a new transaction or a 3-D Secure transaction, our platform can send to your application a Server-to-Server notification.

Setup

To set your Notification URL you must set it on “urlCallback” parameter at the moment of generate a new order (please refer to Chapter 3.1 Request a New Order). After a successful purchase, HiPay calls twice your Notification URL in background with comprehensive information about the payment passed through an HTTP POST parameter in an XML array POST['xml'] the first time for the authorization notification and the second one for the capture notification.

Possible actions

Operation TypeDescription
authorizationAuthorization from the customer’s bank to make the capture.
captureNotification of the real capture to debit the customer’s account.
cancellationPreviously-authorized transaction was cancelled.
refundPreviously-captured transaction was refunded.
rejectCharge Back. The cardholder reversed a capture processed by their bank or credit card company. For instance, the cardholder contacts his credit card company and denies having made the transaction. The credit card company then revokes the already captured payment. Please note the legal difference between shopper who ordered the goods and cardholder who owns the credit card and ends up paying for the order.
In general charge backs only occur incidentally. When they do, contacting the shopper can often solve the situation. Occasionally it is an indication of credit card fraud.

Possible status 

Operation TypeDescription
okOperation succeeded.
nokOperation not succeeded.
cancelCancelation of the operation.
waitingOperation waiting for an action.

Response Fields :

The following table lists and describes the response fields received on the notification call.

Field NameDescription
operationOperation Type. Please report to “Types of possible actions” table.
statusOperation Status. Please report to “Types of possible status” table.
dateDate of the transaction (YYYY-mm-dd).
timeTime of the transaction (e.g., 11:00:58 UTC+0000).
origAmountThe total order amount (e.g., 150.00). It should be calculated as a sum of the items purchased, plus the shipping fee (if present), plus the tax fee (if present).
origCurrencyBase currency for this order. This three-character currency code complies with ISO 4217.
idForMerchantThe transaction ID used by the merchant.
emailClientEmail address of the customer.
merchantDatasCustom merchant data provided at the moment of generate a new order (please refer to Chapter 3.1 Request a New Order).
transidThe unique identifier of the transaction.
is3dsIndicates if the used card is 3-D Secure enrolled.
paymentMethodPayment method used by the customer.
customerCountryCountry code of the customer. This two-letter code complies with ISO-3166.
returnCode
returnDescriptionShort
returnDescriptionLong
<mapi>
        <mapiversion>1.0</mapiversion>
        <md5content>05049866c4538df62c780fdb08b95ee0</md5content>
        <result>
         <operation>authorization</operation>
         <status>nok</status>
         <date>2014-02-11</date>
         <time>11:00:58 UTC+0000</time>
         <origAmount>1.00</origAmount>
         <origCurrency>EUR</origCurrency>
         <idForMerchant>ORDER123456</idForMerchant>
         <emailClient>[email protected]</emailClient>
         <merchantDatas>  
          <_aKey_keyOne>aValueOne</_aKey_keyOne>  
          <_aKey_keyTwo>aValueTwo</_aKey_keyTwo>
         </merchantDatas>
         <transid>52F9FFA68486E</transid>
         <is3ds>Yes</is3ds>
         <paymentMethod>VISA</paymentMethod>
         <customerCountry>FR</customerCountry>
         <returnCode></returnCode>
         <returnDescriptionShort></returnDescriptionShort>
         <returnDescriptionLong></returnDescriptionLong>
        </result>
</mapi>;

Signature verification

It is strongly recommended to use a signature mechanism to verify the contents of a request or redirection made to your servers.

This prevents customers from tampering with the data in the data exchanges between your servers and our payment system. A unique signature is sent each time that HiPay contact a merchant URL.

Verification

For the URL notification, the signature is sent on the “md5content” parameter, to verify it, you just need so concatenate your “wsPassword” with the “result” part of the XML posted to you.

Algorithm:Md5 Signature = md5('...' + wsPassword)