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.

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.

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

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.

The 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 Name

Description

transactionPublicId

The unique identifier of the transaction.

code

Status code of the answer.

description

Description of the answer.

amount

Refunded amount.

currency

Currency of refunded transaction.

Maintenance Operations

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

Operation Type

Resource

Description

confirm

/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.

cancel

/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.

Request Parameters

Parameter

Format

Length

Req

Description

wsLogin

AN

32

M

Your API Webservice Login.

wsPassword

AN

32

M

Your API Webservice Password.

transactionPublicId

AN

32

M

The unique identifier of the transaction sent to the merchant on the urlCallback (Notification) called “transid”.

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 Type

Description

authorization

Authorization from the customer’s bank to make the capture.

capture

Notification of the real capture to debit the customer’s account.

cancellation

Previously-authorized transaction was cancelled.

refund

Previously-captured transaction was refunded.

reject

Charge 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 Type

Description

ok

Operation succeeded.

nok

Operation not succeeded.

cancel

Cancelation of the operation.

waiting

Operation waiting for an action.

Response Fields :

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

Field Name

Description

operation

Operation Type. Please report to “Types of possible actions” table.

status

Operation Status. Please report to “Types of possible status” table.

date

Date of the transaction (YYYY-mm-dd).

time

Time of the transaction (e.g., 11:00:58 UTC+0000).

origAmount

The 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).

origCurrency

Base currency for this order. This three-character currency code complies with ISO 4217.

idForMerchant

The transaction ID used by the merchant.

emailClient

Email address of the customer.

merchantDatas

Custom merchant data provided at the moment of generate a new order (please refer to Chapter 3.1 Request a New Order).

transid

The unique identifier of the transaction.

is3ds

Indicates if the used card is 3-D Secure enrolled.

paymentMethod

Payment method used by the customer.

customerCountry

Country code of the customer. This two-letter code complies with ISO-3166.