Server-to-server notifications

In order to inform you of events related to your payment system, such as a new transaction or a 3-D Secure transaction, the HiPay Enterprise platform can send your application a server-to-server notification.

Setup

To set your Notification URL you must:

      • login into your HiPay Enterprise back office 
      • go to “Integration -> Notifications”.

Configuration parameters

Field name

Description

Notification URL

The URL or IP address on which you want to receive server-to-server notifications

Request method

The method with which you want to receive requests: XML / HTTP POST

Desired notifications

Here you can define which notifications you want to receive based on the transaction status.

Please refer to the Transaction statuses article

Response fields

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

Field name

Description

state

Transaction state. The value must be from the following list: 

– completed

– pending

– declined

– error

For further details, please refer to the Transaction workflow article.

reason 

– code 

– message

Optional element. Reason why the transaction was declined.

– code: Decline reason code 

– message: Decline reason description Possible decline reasons can be found in the Decline reasons and error codes article.

test

True if the transaction is a test transaction; otherwise false

mid

Your merchant account number (issued to you by HiPay Enterprise)

attempt_id

Attempt ID of the payment

authorization_code

Authorization code (up to 35 characters) generated for each approved or pending transaction by the acquiring provider

transaction_reference

Unique identifier of the transaction

date_created

Date when the transaction was created

date_updated

Date when the transaction was last updated

date_authorized

Date when the transaction was authorized

status

Transaction status. A list of possible statuses can be found in the Transaction statuses article

message

Transaction message

authorized_amount

Transaction amount

captured_amount

Captured amount

refunded_amount

Refunded amount

decimals

Decimal precision of the transaction amount

currency

Base currency for the transaction.

This three-character currency code complies with ISO 4217.

ip_address

IP address of the customer making the purchase

ip_country

Country code associated to the customer’s IP address

device_id

Unique identifier assigned to the device (the customer’s browser) by HiPay

cdata1 

– cdata2

– … 

– cdata10

Custom data

avs_result

Result of the Address Verification Service (AVS). Possible AVS result codes can be found in the Address Verification Service article.

cvc_result

Result of the CVC (Card Verification Code) check. Possible CVC result codes can be found in the Card Verification Code article.

eci

Electronic Commerce Indicator (ECI) Possible ECIs can be found in the Electronic Commerce Indicator article.

payment_product

Payment product used to complete the transaction. Informs about the payment_method section type. Possible payment products can be found in the Payment means article.

payment_method

For further details, please refer to the Response fields specific to the payment product section.

three_d_secure

– eci

– enrollment_status 

– enrollment_message 

– authentication_status

– authentication_message

– authentication_token

– xid

Optional element. Result of the 3-D Secure Authentication.

– 3-D Secure (3DS) Electronic Commerce Indicator

– Enrollment status

– Enrollment message

– Authentication status

– This field is only included if payment authentication was attempted and a value was received.

– Authentication message. This field is only included if payment authentication was attempted and a value was received.

– This is a value generated by the card issuer as a token to prove that the cardholder was successfully authenticated.

– Unique transaction identifier generated by the payment server on behalf of the merchant to identify the 3-D Secure transaction.

fraud_screening

– scoring

– result

– review

Fraud screening result

Total score assigned to the transaction (main risk indicator)

Overall result of risk assessment returned by the payment gateway

The value must be from the following list:

– pending: rules have not been checked

– accepted: the transaction has been accepted

– blocked: the transaction has been rejected due to reviewing system rules

– challenged: the transaction has been flagged for review.

Decision made when the overall risk result returns challenged.

An empty value means that no review is required.

The value must be from the following list:

– pending: a decision to release or cancel the transaction is pending

– allowed: the transaction has been released for processing

– denied: the transaction has been cancelled.

order

– Id

– dateCreated 

– attempts

– amount

– shipping

– tax

– decimals

– currency

– customer_id

– language

– email

Information about the customer and their order:

– Unique identifier of the order as provided by the merchant

– Time when the order was created

– Indicates how many payment attempts have been made for this order

– Total order amount (e.g.: 150.00). It should be calculated as the sum of purchased items, plus shipping fees (if present) and tax (if present).

– Order shipping fees

– Order tax amount

– Decimal precision of the order amount

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

– Unique identifier of the customer as provided by the merchant

– Language code of the customer

– Email address of the customer

operation

– type

– id

– reference

– amount

– currency

– date

If a maintenance operation was requested and an operation_id value was sent.

– Type of last operation

– Operation ID sent in maintenance operation

– HiPay’s Operation reference

– Operation amount

– Operation currency

– Operation date

Specific Response fields

Credit card payments: The following table lists and describes the response fields returned for transactions by credit/debit card.

Field name

Description

token

Card token

brand

Card brand (e.g., VISA, MASTERCARD, AMERICAN EXPRESS, MAESTRO).

pan

Card number (up to 19 characters)

Please note that, due to the PCI DSS security standards, our system has to mask credit card numbers in any output (e.g., 549619**4769).

card_holder

Cardholder’s name

card_expiry_month

Card expiry month (2 digits)

card_expiry_year

Card expiry year (4 digits)

issuer

Card issuing bank name

Do not rely on this value to remain static over time. Bank names may change due to acquisitions and mergers.

country

Bank country code where the card was issued.

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

 

Transaction workflow

The HiPay Enterprise payment gateway can process transactions through many different acquirers using different payment methods and involving anti-fraud checks. All these aspects change the transaction processing flow significantly for you.

When you create a transaction, you receive a response describing the transaction state. Depending on the transaction state, there are five possible values:

Transaction state

Description

completed

If the transaction state is “completed”, you are done. This is the most common case for credit card transaction processing. Almost all credit card acquirers work that way. Then, you have to look into the status field of the response to know the exact transaction status.

forwarding

If the transaction state is “forwarding”, you have to redirect your customer to a URL provided in the forward_url field of the response. In that case, transaction processing is not finished yet. You have to wait until the customer returns to your website after doing all redirects.

pending

The transaction request was submitted to the acquirer but the response is not available yet.

declined

The transaction was processed and declined by the gateway.

error

The transaction was not processed for some reason.

Examples

The following are XML and HTTP Post response examples.

XML response example:

   <?xml version="1.0" encoding="UTF-8"?>
    <notification>
      <state>completed</state>
      <reason/>
      <test>true</test>
      <mid>00001326581</mid>
      <attempt_id>1</attempt_id>
      <authorization_code>test123</authorization_code>
      <transaction_reference>388997073285</transaction_reference>
      <date_created>2016-10-14T12:29:51+0000</date_created>
      <date_updated>2016-10-14T12:29:55+0000</date_updated>
      <date_authorized>2016-10-14T12:29:54+0000</date_authorized>
      <status>117</status>
      <message>Capture Requested</message>
      <authorized_amount>5.00</authorized_amount>
      <captured_amount>5.00</captured_amount>
      <refunded_amount>0.00</refunded_amount>
      <decimals>2</decimals>
      <currency>EUR</currency>
      <ip_address>83.167.62.196</ip_address>
      <ip_country>FR</ip_country>
      <device_id/>
      <cdata1><![CDATA[My data 1]]></cdata1>
      <cdata2><![CDATA[My data 2]]></cdata2>
      <cdata3><![CDATA[My data 3]]></cdata3>
      <cdata4><![CDATA[My data 4]]></cdata4>
      <avs_result/>
      <cvc_result/>
      <eci>9</eci>
      <payment_product>visa</payment_product>
      <payment_method>
        <token>xb6axde89e9xxe50fe2xe9ba408xx0011804dx7be05x6x55576c0xb14cx641xx</token>
        <brand>VISA</brand>
        <pan>400000******0000</pan>
        <card_holder>John Doe</card_holder>
        <card_expiry_month>07</card_expiry_month>
        <card_expiry_year>2018</card_expiry_year>
        <issuer>MY BANK</issuer>
        <country>FR</country>
      </payment_method>
      <three_d_secure>
        <eci>5</eci>
        <enrollment_status>Y</enrollment_status>
        <enrollment_message>Authentication Available</enrollment_message>
        <authentication_status>Y</authentication_status>
        <authentication_message>Authentication Successful</authentication_message>
        <authentication_token></authentication_token>
        <xid></xid>
      </three_d_secure>
      <fraud_screening>
        <scoring>120</scoring>
        <result>accepted</result>
        <review/>
      </fraud_screening>
      <order>
        <id>1381753783</id>
        <date_created>2016-10-14T12:29:51+0000</date_created>
        <attempts>1</attempts>
        <amount>5.00</amount>
        <shipping>10.00</shipping>
        <tax>0.98</tax>
        <decimals>2</decimals>
        <currency>EUR</currency>
        <customer_id>UID1381753791</customer_id>
        <language>fr_FR</language>
        <email>[email protected]</email>
      </order>
    </notification>

HTTP POST response example:

      state = completed
       reason =
       test = false
       mid = 00001326581
       attempt_id = 1
       authorization_code = test123
       transaction_reference = 781357613392
       date_created = 2016-10-14T13:10:36+0000
       date_updated = 2016-10-14T13:10:38+0000
       date_authorized = 2016-10-14T13:10:38+0000
       status = 116
       message = Authorized
       authorized_amount = 5.00
       captured_amount = 0.00
       refunded_amount = 0.00
       decimals = 2
       currency = EUR
       ip_address = 83.167.62.196
       ip_country = FR
       device_id =
       cdata1 = My data 1
       cdata2 = My data 2
       cdata3 = My data 3
       cdata4 = My data 4
       avs_result =
       cvc_result =
       eci = 7
       payment_product = visa
       payment_method[token] = xb6axde89e9xxe50fe2xe9ba408xx0011804dx7be05x6x55576c0xb14cx641xx
       payment_method[brand] = VISA
       payment_method[pan] = 400000******0000
       payment_method[card_holder] = John Doe
       payment_method[card_expiry_month] = 07
       payment_method[card_expiry_year] = 2018
       payment_method[issuer] = MYBANK
       payment_method[country] = FR
       three_d_secure[eci] = 5
       three_d_secure[enrollment_status] = Y
       three_d_secure[enrollment_message]=Authentication Available
       three_d_secure[authentication_status]=Y
       three_d_secure[authentication_message]=Authentication Successful
       three_d_secure[authentication_token]=
       three_d_secure[xid]=
       fraud_screening[scoring] = 120
       fraud_screening[result] = accepted
       fraud_screening[review] =
       order[id] = 1381756231
       order[date_created] = 2016-10-14T13:10:36+0000
       order[attempts] = 1
       order[amount] = 5.00
       order[shipping] = 10.00
       order[tax] = 0.98
       order[decimals] = 2
       order[currency] = EUR
       order[customer_id] = UID1381756236
       order[language] = fr_FR
       order[email] = [email protected]