Skip to main content
Français Italiano Português

HiPay Enterprise – Integration of alternative payment methods

If you want your customers to be redirected from your website directly to the alternative payment method page without going through the HiPay hosted payment page, you are in the right place.

Access a wide range of alternative payment methods (e.g.: PayPal, SOFORT, Mooney...) so that your customers can make purchases in their preferred currency with the payment method of their choice.

 

 

Service endpoints

There are two endpoints (base URLs) to which you can make your API calls:

  • Stage, if you are testing your integration, and Production, when you have finished testing and want your application to go live.
Environment Endpoint

Stage

 https://stage-secure-gateway.hipay-tpp.com/rest/v1/order

Production

 https://secure-gateway.hipay-tpp.com/rest/v1/order

 

Request parameters

(For further details, please refer to the technical documentation.)

Format abbreviation Description
AN Alphanumeric characters (a-z, A-Z, 0-9)
A Alphabetic characters only (a-z, A-Z)
N Numeric characters only
R Decimal number with explicit decimal point, signed
JSON JavaScript Object Notation

 

 Field name  Format  Length  Description
language  AN  5  Set the language of the alternative payment page. 
 Locale code, default to en_GB – English – Great Britain
 E.g.: fr_FR, es_ES, etc.
 Field name  Format  Length  Description
 orderid AN 32 ID of the order
 operation A - Set the value:
Sale = debits the customer immediately
 eci N [string] 1 Set the value:
7 
 description AN 128 Short description of the order
 long_description AN -  Additional description of the order
 payment_product AN 255

Please check the list below:
dexia-directnet
ideal
ing-homepay
kbc-online
paysafecard
payulatam, przelewy24
qiwi-wallet
mooney
sofort-uberweisung
yandex
oxxo
itau
payshop
webmoney-transfer
elo-card
safetypay
skrill
discover

aura
boleto-bancariobanco-do-brasil
bradesco
caixa
hipercard
santander-home-banking
santander-cash
banamexdivido
bacs
wechatpay
cup
postfinance-efinance
postfinance-card
bancontact
 currency A 3 Base currency for the order (default to EUR)
This three-character currency code complies with ISO 4217.
 amount R - Order total amount
 shipping R - Shipping fees for the order (default to zero)
Can be omitted if the shipping fees value is zero.
 tax R - Tax amount for the order (default to zero)
Can be omitted if the tax amount value is zero.
 tax_rate R - Tax rate for the order
  custom_data JSON - You can use this parameter to submit custom values you wish to show in HiPay's back office transaction details, to receive back in the API response messages and in the notifications or to activate specific anti-fraud rules.

E.g.:
custom_data => {
"shipping_method":"click and collect",
"first_order":"0",
"products_list":"First product, Second
product, Third product"}
Field name Format Length Description
email AN - Customer's email address
phone AN
 - Customer's phone number
birthdate N 8 Customer's birthdate (YYYYMMDD)
For fraud detection purposes
gender A 1

Gender of the customer:

M = male
F = female
firstname AN
 - Customer's first name
lastname AN - Customer's last name
streetaddress AN - Customer's street address
streetaddress2 AN -

Additional address information of the customer

(e.g.: building, floor, flat, etc.)
city AN - Customer's city
state AN - State of the country
zipcode AN - Zip or postal code of the customer
country A 2

Country code of the customer
This two-letter country code complies with ISO 3166-1 (alpha 2).

Mandatory for Bancontact (Only "BE")
shipto_firstname AN - First name of the order's recipient
shipto_lastname AN - Last name of the order's recipient
shipto_streetaddress AN - Street address where the order is to be shipped
shipto_streetaddress2 AN - Additional information about the street address where the order is to be shipped (e.g.: building, floor, flat, etc.)
shipto_city AN - City where the order is to be shipped
shipto_state AN - State where the order is to be shipped
shipto_zipcode AN - Zip or postal code where the order is to be shipped
shipto_country A 2

Country code where the order is to be shipped

This two-letter country code complies with ISO 3166-1 (alpha 2).
ipaddr AN - Customer's IP address
cid AN - Unique customer ID
accept_url AN - URL to redirect your customers to once the payment process is completed successfully
decline_url AN - URL to redirect your customers to after the acquirer has declined the payment
pending_url AN - URL to redirect your customers to when the payment request has been submitted to the acquirer, but the response is not available yet
exception_url AN - URL to redirect your customers to after a system failure
cancel_url AN - URL to redirect your customers to when they decide to abort the payment

 

Full PHP example:


$data = array(

  // Language setting
  "language"=> "en_GB",

  // Order information
  "orderid"=> "HP".rand(microtime(0),100000),
  "operation"=> "sale",
  "eci"=> "7",
  "description"=> "Description of the order",
  "long_description"=> "Long description of the order",
  "payment_product"=> "postfinance-card",
  "currency"=> "CHF",
  "amount"=> 100,
  "shipping"=> 10,
  "tax"=> 15,
  "tax_rate"=> 15,
  "custom_data"=>
  '{
    "shipping_method":"click and collect",
    "first_order":"0",
    "products_list": "First product, Second product",
    "_reporting_data_1":"my custom data 1",
    "_reporting_data_2":"my custom data 2",
    "_reporting_data_3":"my custom data 3",
    "_reporting_data_4":"my custom data 4",
    "_reporting_data_5":"my custom data 5"
		}',

  // Customer information
  "email"=> "jane.doe@test.com",
  "gender"=> "M",
  "firstname"=> "Jane",
  "lastname"=> "Doe",
  "birthdate"=> 19890525,
  "phone"=> "01234567890",
  "streetaddress"=> "Mingerstrasse 6",
  "streetaddress2"=> "Bâtiment 1",
  "city"=> "Berne",
  "zipcode"=> "3014",
  "country"=> "CH",
  "shipto_firstname"=> "Jane",
  "shipto_lastname"=> "Doe",
  "shipto_streetaddress"=> "Mingerstrasse 6",
  "shipto_streetaddress2"=> "Bâtiment 2",
  "shipto_city"=> "Berne",
  "shipto_zipcode"=> "3014",
  "shipto_country"=> "CH",
  "ipaddr"=> "127.0.0.1",
  "cid"=> "123456",
  "accept_url"=> "https://example.com/accept",
  "decline_url"=> "https://example.com/decline",
  "pending_url"=> "https://example.com/pending",
  "exception_url"=> "https://example.com/exception",
  "cancel_url"=> "https://example.com/cancel",
);

 

Response API JSON example:


{
  "state":"forwarding",
  "reason":"",
  "forwardUrl":"https:\/\/stage-secure-gateway.hipay-tpp.com\/gateway\/forward\/537e9f1ccb6a50fcca830fc1343f3298",
  "test":"true",
  "mid":"00001234567",
  "attemptId":"1",
  "authorizationCode":"",
  "transactionReference":"800004137998",
  "dateCreated":"2019-08-29T15:24:27+0000",
  "dateUpdated":"2019-08-29T17:24:28+0200",
  "dateAuthorized":"",
  "status":"142",
  "message":"Authorization Requested",
  "authorizedAmount":"0.00",
  "capturedAmount":"0.00",
  "refundedAmount":"0.00",
  "creditedAmount":"0.00",
  "decimals":"2",
  "currency":"CHF",
  "ipAddress":"0.0.0.0",
  "ipCountry":"",
  "deviceId":"",
  "avsResult":"",
  "cvcResult":"",
  "eci":"7",
  "paymentProduct":"postfinance-card",
  "paymentMethod":"",
  "threeDSecure":"",
  "fraudScreening":
  {
    "scoring":"30",
    "result":"ACCEPTED",
    "review":""
    },
  "order":
  {
    "id":"HP1065",
    "dateCreated":"2019-08-29T15:24:27+0000",
    "attempts":"1",
    "amount":"100.00",
    "shipping":"10.00",
    "tax":"15.00",
    "decimals":"2",
    "currency":"CHF",
    "customerId":"123456",
    "language":"en_EN",
    "email":"jane.doe@test.com"
  },
}

 

To consider a pending payment meaning the customer arrived on the payment page and is filling in the fields now, it is appropriate to rely on the server-to-server notification containing the following values:
status=142
message=Authorization+Requested

You can receive the server-to-server notification in:
- POST "application/x-www-form-urlencoded" format
- POST XML

POST pending server-to-server notification example:


state=forwarding
&test=true
&mid=00001234567
&attempt_id=1
&authorization_code=
&transaction_reference=800004137998
&date_created=2019-08-29T15%3A24%3A27%2B0000
&date_updated=2019-08-29T15%3A24%3A28%2B0000
&date_authorized=
&status=142
&message=Authorization+Requested
&authorized_amount=100.00
&captured_amount=0.00
&refunded_amount=0.00
&decimals=2
&currency=CHF
&ip_address=0.0.0.0
&ip_country=
&device_id=
&custom_data%5Bfirst_order%5D=0
&custom_data%5Bproducts_list%5D=First+product%2C+Second+product
&custom_data%5B_reporting_data_1%5D=my+custom+data+1
&custom_data%5B_reporting_data_2%5D=my+custom+data+2
&custom_data%5B_reporting_data_3%5D=my+custom+data+3
&custom_data%5B_reporting_data_4%5D=my+custom+data+4
&custom_data%5B_reporting_data_5%5D=my+custom+data+5
&custom_data%5Bshipping_method%5D=click+and+collect
&avs_result=
&cvc_result=
&eci=7
&payment_product=postfinance-card
&payment_method=
&fraud_screening%5Bscoring%5D=30
&fraud_screening%5Bresult%5D=accepted
&fraud_screening%5Breview%5D=
&order%5Bid%5D=HP1065
&order%5Bdate_created%5D=2019-08-29T15%3A24%3A27%2B0000
&order%5Battempts%5D=1
&order%5Bamount%5D=100.00
&order%5Bshipping%5D=10.00
&order%5Btax%5D=15.00
&order%5Bdecimals%5D=2
&order%5Bcurrency%5D=CHF
&order%5Bcustomer_id%5D=123456
&order%5Blanguage%5D=en_EN
&order%5Bemail%5D=jane.doe%40test.com

 

To consider an accepted payment, it is appropriate to rely on the server-to-server notification containing the following values:
status=118
message=Captured

You can receive the server-to-server notification in:
- POST "application/x-www-form-urlencoded" format
- POST XML

POST accepted payment confirmation server-to-server notification example:


 state=completed
&test=true
&mid=00001234567
&attempt_id=1
&authorization_code=TEST
&transaction_reference=800004137998
&date_created=2019-08-29T15%3A24%3A27%2B0000
&date_updated=2019-08-29T15%3A24%3A37%2B0000
&date_authorized=2019-08-29T15%3A24%3A36%2B0000
&status=118
&message=Captured
&authorized_amount=100.00
&captured_amount=100.00
&refunded_amount=0.00
&decimals=2
&currency=CHF
&ip_address=0.0.0.0
&ip_country=
&device_id=
&custom_data%5Bfirst_order%5D=0
&custom_data%5Bproducts_list%5D=First+product%2C+Second+product
&custom_data%5B_reporting_data_1%5D=my+custom+data+1
&custom_data%5B_reporting_data_2%5D=my+custom+data+2
&custom_data%5B_reporting_data_3%5D=my+custom+data+3
&custom_data%5B_reporting_data_4%5D=my+custom+data+4
&custom_data%5B_reporting_data_5%5D=my+custom+data+5
&custom_data%5Bshipping_method%5D=click+and+collect
&avs_result=
&cvc_result=
&eci=7
&payment_product=postfinance-card
&payment_method=
&fraud_screening%5Bscoring%5D=0
&fraud_screening%5Bresult%5D=accepted
&fraud_screening%5Breview%5D=
&order%5Bid%5D=HP1065
&order%5Bdate_created%5D=2019-08-29T15%3A24%3A27%2B0000
&order%5Battempts%5D=1
&order%5Bamount%5D=100.00
&order%5Bshipping%5D=10.00
&order%5Btax%5D=15.00
&order%5Bdecimals%5D=2
&order%5Bcurrency%5D=CHF
&order%5Bcustomer_id%5D=123456
&order%5Blanguage%5D=en_EN
&order%5Bemail%5D=jane.doe%40test.com

Related articles