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
acquirer_transaction_reference Unique identifier of the transaction on the acquirer’s side
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:
   
    
      completed
      
      true
      00001326581
      1
      test123
      388997073285
      2016-10-14T12:29:51+0000
      2016-10-14T12:29:55+0000
      2016-10-14T12:29:54+0000
      117
      Capture Requested
      5.00
      5.00
      0.00
      2
      EUR
      83.167.62.196
      FR
      
      
      
      
      
      
      
      9
      visa
      
        xb6axde89e9xxe50fe2xe9ba408xx0011804dx7be05x6x55576c0xb14cx641xx
        VISA
        400000******0000
        John Doe
        07
        2018
        MY BANK
        FR
      
      
        5
        Y
        Authentication Available
        Y
        Authentication Successful
        
        
      
      
        120
        accepted
        
      
      
        1381753783
        2016-10-14T12:29:51+0000
        1
        5.00
        10.00
        0.98
        2
        EUR
        UID1381753791
        fr_FR
        [email protected]
      
    

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]