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.
To set your Notification URL you must:
- login into your HiPay Enterprise back office
- go to “Integration -> Notifications”.
The URL or IP address on which you want to receive server-to-server notifications
The method with which you want to receive requests: XML / HTTP POST
Here you can define which notifications you want to receive based on the transaction status.
Please refer to the Transaction statuses article
The following table lists and describes the response fields received on the notification call.
Transaction state. The value must be from the following list:
For further details, please refer to the Transaction workflow article.
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.
True if the transaction is a test transaction; otherwise false
Your merchant account number (issued to you by HiPay Enterprise)
Attempt ID of the payment
Authorization code (up to 35 characters) generated for each approved or pending transaction by the acquiring provider
Unique identifier of the transaction
Date when the transaction was created
Date when the transaction was last updated
Date when the transaction was authorized
Transaction status. A list of possible statuses can be found in the Transaction statuses article
Decimal precision of the transaction amount
Base currency for the transaction.
This three-character currency code complies with ISO 4217.
IP address of the customer making the purchase
Country code associated to the customer’s IP address
Unique identifier assigned to the device (the customer’s browser) by HiPay
Result of the Address Verification Service (AVS). Possible AVS result codes can be found in the Address Verification Service article.
Result of the CVC (Card Verification Code) check. Possible CVC result codes can be found in the Card Verification Code article.
Electronic Commerce Indicator (ECI) Possible ECIs can be found in the Electronic Commerce Indicator article.
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.
For further details, please refer to the Response fields specific to the payment product section.
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 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.
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
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.
Card brand (e.g., VISA, MASTERCARD, AMERICAN EXPRESS, MAESTRO).
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 expiry month (2 digits)
Card expiry year (4 digits)
Card issuing bank name
Do not rely on this value to remain static over time. Bank names may change due to acquisitions and mergers.
Bank country code where the card was issued.
This two-letter country code complies with ISO 3166-1 (alpha 2).
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:
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.
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.
The transaction request was submitted to the acquirer but the response is not available yet.
The transaction was processed and declined by the gateway.
The transaction was not processed for some reason.
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>22.214.171.124</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 = 126.96.36.199 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]