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 nameDescription
Notification URLThe URL or IP address on which you want to receive server-to-server notifications
Request methodThe method with which you want to receive requests: XML / HTTP POST
Desired notificationsHere 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 nameDescription
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.

testTrue if the transaction is a test transaction; otherwise false
midYour merchant account number (issued to you by HiPay Enterprise)
attempt_idAttempt ID of the payment
authorization_codeAuthorization code (up to 35 characters) generated for each approved or pending transaction by the acquiring provider
transaction_referenceUnique identifier of the transaction
acquirer_transaction_referenceUnique identifier of the transaction on the acquirer’s side
date_createdDate when the transaction was created
date_updatedDate when the transaction was last updated
date_authorizedDate when the transaction was authorized
statusTransaction status. A list of possible statuses can be found in the Transaction statuses article
messageTransaction message
authorized_amountTransaction amount
captured_amountCaptured amount
refunded_amountRefunded amount
decimalsDecimal precision of the transaction amount
currency

Base currency for the transaction.

This three-character currency code complies with ISO 4217.

ip_addressIP address of the customer making the purchase
ip_countryCountry code associated to the customer’s IP address
device_idUnique identifier assigned to the device (the customer’s browser) by HiPay

custom_data%5Bnom_de_la_custom_data%5D=valeur_de_la_custom_data

Custom data
avs_resultResult of the Address Verification Service (AVS). Possible AVS result codes can be found in the Address Verification Service article.
cvc_resultResult of the CVC (Card Verification Code) check. Possible CVC result codes can be found in the Card Verification Code article.
eciElectronic Commerce Indicator (ECI) Possible ECIs can be found in the Electronic Commerce Indicator article.
payment_productPayment 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_methodFor 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 nameDescription
tokenCard token
brandCard 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_holderCardholder’s name
card_expiry_monthCard expiry month (2 digits)
card_expiry_yearCard 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 stateDescription
completedIf 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.
forwardingIf 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.
pendingThe transaction request was submitted to the acquirer but the response is not available yet.
declinedThe transaction was processed and declined by the gateway.
errorThe 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]