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.
Please refer to the Transaction statuses article
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. |
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:XML
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:
HTTP
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]