Direct Merchant Notification Guide API v 1.0.0

Transcription

1 Introduction The purpose of the Direct Merchant Notification (DMN) is to ensure reliable server-to-server communication between xt-payments and the Merchant s web server. Please note that DMN does not replace the standard HTTP API integration with success/error pages. The DMN just supplements the standard integration by decreasing the chances of data loss. You will still need the standard HTTP API integration in order to show the results to the end user, because the DMN happens behind the scenes and the end user is not/should not be aware of it. Data (response) flow diagram When using only the standard xt-payments HTTP API, the communication is 3-sided and the data travels from xt-payments server to the end user browser and then to the merchant s server. This happens through an HTTP Redirect issued on the end user s browser. As the end user browser is a weak node and is prone to data loss, there are cases in which the data could be lost and the merchant s server will not be able to receive xt-payments response. The DMN is here to reduce the cases of data (xt-payments response) loss by establishing direct 2 sided server to server communication, this way enabling the xt-payments server to directly callback the merchant s web server.

2 Integration When a payment page transaction is concluded the xt-payments server sends the normal HTTP Redirect to you success or error page and includes inside the relevant information, such as outcome of the transaction, total amount and other parameters. Please, check the xt-payments API document for this. In the same time, if you have integrated with the DMN the xt-payments server will execute HTTP REUQEST directly to your web server without passing through the end user s browser. This direct request will have included almost the same data as HTTP GET parameters, such as transaction outcome, total amount, etc. In the normal situation, when both the HTTP Redirect and the DMN request succeed, you will receive the Payment Page response twice: once through your success or error page second through the DMN channel

3 For example, there might be cases when the response coming through the success or error page is lost. In such cases you will receive only the DMN channel response. You will be able to determine that something went wrong on the end user s side, just by knowing that the xtpayments server executed a transaction (and you have its result via DMN), but it had never shown the result on your success or error page. In such case the end user is not aware of the transaction outcome and you may want to do some additional action, like call or the end user. In order to integrate with the DMN you will need to supply a callback entry point on your server. This is usually a small module/application, which should constantly listen and wait for incoming HTTP request from xt-payments server. You will need to provide an URL which will be used by the xt-payments server to call you back when the DMN data needs to be transmitted. When the xt-payments server needs to send you data via the DMN it will execute an HTTP GET request to your server on the supplied URL and it will include the relevant parameters in the HTTP GET. In order for xt-payments to send DMN callbacks, the vendor must provide the IP address of his DMN URL. In case the IP address of the DMN URL has to be changed, the vendor must notify xtpayments in advance, in order to prevent interruption of the service. If you supply for DMN the following URL: the xt-payments server will call you back by using the HTTP GET to this URL. It will include all the relevant data as HTTP GET parameters.

4 For example, the xt-payments server will execute the following HTTP GET request to your server in a attempt to send the Payment Page response via the DMN channel. sactionid=45402&userid=111&merchant_unique_id=234234unique_id&customdata=342dssdee &productid=12345product_id&first_name=diyan&last_name=yordanov& =dido%40domain.com&totalamount=47.25&currency=usd&status=approved When using DMN we recommend that you always use the merchant_unique_id parameter from the xt-payments Payment Page API. This way you will be able to map between responses coming to you from you success or error page and DMN data. As noted above, when you are integrated with DMN you will receive the xt-payments Payment Response twice via different channels and you may like to create some mapping on your side between these two channels. Attention: The DMN system is expecting status code 200 OK as response to the callback. If your DMN URL responds with any other code or is not accessible at all, the DMN callback will enter retry mode. In retry mode, the DMN callback is resent to your DMN URL every 15 minutes for 24 hours. The retry mode s purpose is to ensure that you would receive your DMN callback, even if your DMN URL is temporarily unavailable. DMN Parameters and DMN checksum The DMN works by utilizing HTTP GET requests. Therefore all the data of a DMN callback is included in the HTTP parameters of the request. Please see the table below. You can extract the callback data by parsing this HTTP parameters. In order to ensure authenticity of the DMN callback, we have included a checksum among the HTTP parameters. You should use this checksum in order to be sure that the DMN callback was not forged by a 3rd party. The checksum uses MD5 hashing and works in a very similar way to the checksum you will be generating during normal xt-payments Payment Page integration. This checksum also uses you secret key, provided during the standard integration process.

5 The http parameter holding the DMN checksum is named responsechecksum. The checksum is constructed using the following algorithm. Concatenate the following parameters as described below: 1. your secret key 2. the ppp_status parameter from the DMN callback 3. the PPP_TransactionID parameter from the DMN callback 4. do a MD5 has on the result string from the concatenation. Use encoding passed to the PPP from the merchant site to create the MD5 hash. 5. compare the result from MD5 to the responsechecksum parameter from the DMN callback 6. if your hash does not match to the responsechecksum parameter this could be sign for fraud attempt. Be careful and investigate the case. Example: Given you secret key is: sjkdfhkjhscnn3485 responsechecksum is FC5B42EBF9A8487BD39B0E78C ppp_status is OK PPP_TransactionID is After concatenation you will have the following string: sjkdfhkjhscnn3485ok (note, no white spaces inside.) After doing the MD5 on the above string the result is: fc5b42ebf9a8487bd39b0e78c Now, if you compare your result to the responsechecksum parameter you will they match and this means that the DMN callback is authentic and is not forged, because the MD5 hash

6 is based on your SECRET KEY. Note, that the responsechecksum is all upper case and your result maybe in lower case. However, both are matching in content. MD5 results should not be compared in a case sensitive way. Chargeback and Refunds DMN Notification This service will allow you to receive notifications for Credit, Void, ChargeBack, Modification transaction types in addition to the regular ones (Sale, Auth). In order for you to differentiate between the different transactions we have included and additional parameter called transactiontype. The available values can be found in the table below. Transaction type Description Sale Charge Auth Authorization of a certain amount to a credit card Credit Refund of a charge Void Cancelation of a charge Chargeback Indicates that the credit card holder "charges back" a given charge Retrieval Request for information Modification Indicates a change of transaction status after the original transaction is processed

7 DMN Parameters description Below is table with all the DMN callback parameters you may receive from the xt-payments server. Note, that some of them are optional and they might be empty. For example, if you haven t supplied merchant_unique_id when initially made the request to the xt-payments payment page, you will receive empty value for this parameter later in the DMN callback. Transaction type Description ppp_status PPP_TransactionID totalamount Mandatory. The status of the PPP transaction OK means transaction was approved. FAIL means transaction was declined or there was an error. Mandatory A unique 64 bits number, which identified the xtpayments payment page transaction Mandatory. Total amount of the transaction. currency Mandatory. Currency of the transaction. responsechecksum TransactionID transactiontype Status Mandatory. A response checksum that will ensure that the DMN callback was not forged. Optional. A unique 64 bits number, which identifies the fiscal transaction in the xt-payments payment gateway. If no fiscal transaction actually occurred the ppp_status will be FAIL and this will be empty. Optional. The value of this parameter shows the type of transaction that you have been notified of Sale, Auth, Credit, Void, ChargeBack, Modification. This service is available ONLY upon request. Optional. Status of the xt-payments Payment Gateway fiscal transaction Approved, Success, Declined, Error, Pending.. If no fiscal transaction actually occurred the ppp_status will be FAIL and this will be empty.

8 userid merchant_unique_id Optional. The string which you have passed as the userid parameter initially when making the first request to the xtpayments Payment Page. Check the Payment Page API guide. Optional. The ID which you have passed as the merchant_unique_id parameter initially when making the first Page API guide. customdata Optional. The ID which you have passed as the customdata parameter initially when making the first request to the xtpayments Payment Page. Check the Payment Page API guide. productid Optional. The ID which you have passed as the productid parameter initially when making the first request to the xtpayments Payment Page. Check the Payment Page API guide. first_name last_name customfieldx Optional. Firstname of the user that processes a PPP Optional. Lastname of the user that processes a PPP Optional. of the user that processes a PPP transaction, if supplied. Optional. These are five custom fields that merchant may use(replace X with 1 to 5). The customfieldx which you have passed as the customfieldx parameter initially when making the first request to the xt-payments Payment Page. Check the Payment Page API guide. invoice_id address1 Optional. The invoice_id which you have passed as the invoice_id parameter initially when making the first request to the xt-payments Payment Page. Check the Payment Page API guide. Optional. Address1 of the user that processes a PPP

9 address2 country state city zip phone1 Phone2 Phone3 nameoncard cardnumber expmonth expyear Token tokenid Optional. Address2 of the user that processes a PPP Optional. Country of the user that processes a PPP Optional. State of the user that processes a PPP transaction, if supplied. Optional. City of the user that processes a PPP transaction, if supplied. Optional. Zip of the user that processes a PPP transaction, if supplied. Optional. Phone1 of the user that processes a PPP Optional. Phone2 of the user that processes a PPP Optional. Phone3 of the user that processes a PPP Optional. Name on card of the user that processes a PPP Depends. Masked card number of the user that processes a PPP The parameter becomes mandatory if payment method is Credit card or Debit Card. If other payment method is used empty string is returned. Depends. Expiration month of card used for this PPP The parameter becomes mandatory if payment method is Credit card. If other payment method is used empty string is returned. Depends. Expiration year of card used for this PPP The field becomes mandatory if payment method is Credit card. If other payment method is used empty string is returned. Depends. Hash returned from the GW, which can be used instead of credit card number. Depends. Id of the Token. Used in combination with the Token.

10 ExErrCode ErrCode AuthCode shippingcountry shippingstate shippingcity shippingaddress shippingzip shippingfirstname shippinglastname shippingphone shippingcell Depends. 0 if transaction is successfully, contains the code of the specific error. Depends. 0 if transaction is successfully, contains the code of a generic error. Depends. An authorization code (up to 35 characters) which is returned on each approved, pending transaction. Optional. Shipping country of the user that processes a PPP Empty string is returned if shipping Optional. Shipping state of the user that processes a PPP Empty string is returned if shipping Optional. Shipping city of the user that processes a PPP Empty string is returned if shipping Optional. Shipping address of the user that processes a PPP Empty string is returned if shipping Optional. Shipping address of the user that processes a PPP Empty string is returned if shipping Optional. Shipping first name of the user that processes a PPP Empty string is returned if shipping Optional. Shipping last name of the user that processes a PPP Empty string is returned if shipping Optional. Shipping phone of the user that processes a PPP Empty string is returned if shipping Optional. Shipping mobile phone of the user that processes a PPP Empty string is returned if shipping

11 shippingmail total_discount Optional. Shipping of the user that processes a PPP Empty string is returned if shipping Optional. coupons total_handling Optional. The handling which you have passed as the handling parameter initially when making the first request to the xtpayments Payment Page. Check the Payment Page API guide. total_shipping Optional. The shipping which you have passed as the shipping parameter initially when making the first request to the xtpayments Payment Page. Check the Payment Page API guide. total_tax Optional. The total tax which you have passed as the total_tax parameter initially when making the first request to the xtpayments Payment Page. Check the Payment Page API guide. buybuttonproductbundleid merchant_site_id Depends. Only when buy button payment was processed. Contain the ID of the product bundle. Mandatory. The ID, provided by xt-payments, which uniquely defines a particular merchant customization. Check the Payment Page API guide. requestversion Mandatory. The version of the request. Default value is Otherwise version may be supplied. message payment_method merchant_id Mandatory. A message from the PPP about the transaction that has been done. Mandatory. The payment method used for this transaction such as cc_card, dc_card, giro etc. Mandatory. The unique merchant id supplied by xt-payments. Check the Payment Page API guide.

12 responsetimestamp buybuttonproductid rebillingpricedescriptor Mandatory. Time set by the PPP, when response is received from the GW. Depends. Only when buy button payment was processed. Contain the ID of the product. N/A if not rebilling rebillingproductname N/A if not rebilling membershipid N/A if not rebilling memberid N/A if not rebilling rebillingmessage N/A if not rebilling dynamicdescriptor rebillingtemplateid Mandatory. Dynamic descriptor passed to the xt-payments gateway for the current transaction. N/A if not rebilling initial_amount rebilling_amount rebilling_initial_transaction_id rebilling_initial_amount rebilling_initial_currency Reason Optional. Initial amount dynamic rebilling parameter if supplied. Optional. Rebilling amount dynamic rebilling parameter if supplied. Optional. The Gateway transactionid of the membership initialization step. It can be 0 if the rebilling hasn t initialization transaction or membership creation failed, because of some validation error. Optional. The amount of the Gateway transaction of the membership initialization step. Optional. The currency of the Gateway transaction of the membership initialization step. Depends. A reason that the gateway has returned if the transaction fails. See gateway specification. N/A if it is not a regular transaction.

13 ReasonCode item_name_x item_number_x item_amount_x item_quantity_x item_discount_x item_handling_x item_shipping_x Depends. A reason code that the gateway has returned if the transaction fails. See gateway specification. N/A if it is not a regular transaction. Mandatory. The item name which you have passed as the item_name_x parameter initially when making the first Page API guide. N/A if it is not a regular transaction. Optional. The item number which you have passed as the item_number_x parameter initially when making the first Page API guide. N/A if it is not a regular transaction. Mandatory. The item amount which you have passed as the item_amount_x parameter initially when making the first Page API guide. N/A if it is not a regular transaction. Optional. The item quantity which you have passed as the item_quantity_x parameter initially when making the first Page API guide. The default value is 1 if not supplied. Optional. The item discount which you have passed as the item_discount_x parameter initially when making the first Page API guide. N/A if it is not a regular transaction. Optional. The item handling which you have passed as the item_handling_x parameter initially when making the first Page API guide. N/A if it is not a regular transaction. Optional. The item shipping which you have passed as the item_shipping_x parameter initially when making the first Page API guide. N/A if it is not a regular transaction.