Вы находитесь на странице: 1из 9

Direct Merchant Notification API v 1.0.

Introduction
The purpose of the Direct Merchant Notification (DMN) is to ensure reliable server-to-server communication between G2S and the Merchants 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 G2S HTTP API, the communication is 3-sided and the data travels from G2S server to the end user browser and then to the merchants server. This happens through an HTTP Redirect issued on the end users 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 merchants server will not be able to receive G2S response. The DMN is here to reduce the cases of data (G2S response) losses by establishing direct 2 sided server to server communication, this way enabling the G2S server to directly callback the merchants web server.

G re 2S sp s on er se ve em da r is ai ta: sue l, t o st a s a ta tu H l a s, TT m tra P ou n re nt sa di , c ct re he ion ct ck id wi su , n th m am the es ,

re E dir nd ec u t t se o rb th ro e w th succ ser e m ess exe er ch or cute an err s or the t pa ge of

Integration
When a payment page transaction is concluded the G2S 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 G2S API document for this. In the same time, if you have integrated with the DMN the G2S server will execute HTTP REUQEST directly to your web server without passing through the end users 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 thourgh the DMN channel

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 users side, just by knowing that the G2S 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 email 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 G2S server. You will need to provide an URL which will be used by the G2S server to call you back when the DMN data needs to be transmitted. When the G2S 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. If you supply for DMN the following URL: http://myserver.com/g2s/dmn/listen.to, the G2S server will call you back by using the HTTP GET to this URL. It will include all the relevant data as HTTP GET parameters. For example, the G2S server will execute the following HTTP GET request to your server in a attempt to send the Payment Page response via the DMN channel. http://myserver.com/g2s/dmn/listen.to?ppp_status=OK&PPP_TransactionID=547&TransactionI D=45402&userid=111&merchant_unique_id=234234unique_id&customData=342dssdee&productId=1 2345product_id&first_name=Diyan&last_name=Yordanov&email=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 G2S 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 note above, when you are integrated with DMN you will receive the G2S Payment Response twice via different channels and you may like to create some mapping on your side between these two channels.

DMN Parameters and DMN checksum


The DMN works by utilizing HTTP GET requests. Therefore all the data of a DMN callback is include 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 forget 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 G2S Payment Page integration. This checksum also uses you secret key, provided during the standard integration process. The http parameter holding the DMN checksum is named responsechecksum. The checksum is constructed using the following algorithm: Concatenate the following parameters in the exact same way: 1. your secret key 2. the ppp_status parameter from the DMN callback 3. the PPP_Transaction_ID 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 FC5B42EBF9A8487BD39B0E78C4427797 ppp_status is OK PPP_Transaction_ID is 349583945

After concatenation you will have the following string:


sjkdfhKJHScnn3485OK349583945 (note, no white spaces inside.)

After doing the MD5 on the above string the result is: fc5b42ebf9a8487bd39b0e78c4427797

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 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.

DMN Paramters description


Below is table with all the DMN callback parameters you may receive from the G2S server. Note, that some of them are optional and they might be empty. For example, if you havent supplied merchant_unique_id when initially made the request to the G2S payment page, you will receive empty value for this parameter later in the DMN callback.

ppp_status PPP_TransactionID totalAmount currency responsechecksum TransactionID

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 G2S payment page transaction Mandatory. Total amount of the transaction. Mandatory. Currency of the transaction. 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 G2S payment gateway. If no fiscal transaction actually occurred the ppp_status will be FAIL and this will be empty. Optional. Status of the G2S 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. Optional. The string which you have passed as the userid parameter initially when making the first request to the G2S 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 request to the G2S Payment Page. Check the Payment Page API guide. Optional. The ID which you have passed as the customData parameter initially when making the first request to the G2S Payment Page. Check the Payment Page API guide. Optional. The ID which you have passed as the productId parameter initially when making the first request to the G2S Payment Page. Check the Payment Page API guide. Optional. Firstname of the user that processes a PPP transaction, if supplied. Optional. Lastname of the user that processes a PPP transaction, if supplied. Optional. Email 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 G2S Payment Page. Check the Payment Page API guide. Optional. The invoice_id which you have passed as the invoice_id parameter initially when making the first request to the G2S Payment Page. Check the Payment Page API guide. Optional. Address1 of the user that processes a PPP transaction, if supplied. Optional. Address2 of the user that processes a PPP transaction, if supplied. Optional. Country of the user that processes a PPP transaction, if supplied. Optional. State of the user that processes a PPP transaction, if supplied. Optional. City of the user that processes a PPP transaction, if supplied.

Status

userid

merchant_unique_id

customData

productId

first_name last_name Email customFieldX

invoice_id

address1 address2 country state city

zip phone1 Phone2 Phone3 nameOnCard cardNumber

Optional. Zip of the user that processes a PPP transaction, if supplied. Optional. Phone1 of the user that processes a PPP transaction, if supplied. Optional. Phone2 of the user that processes a PPP transaction, if supplied. Optional. Phone3 of the user that processes a PPP transaction, if supplied. Optional. Name on card of the user that processes a PPP transaction, if supplied. Depends. Masked card number of the user that processes a PPP transaction, if supplied. 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 transaction, if supplied. 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 transaction, if supplied. 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. 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 transaction, if supplied. Empty string is returned if shipping feature is not enabled. Optional. Shipping state of the user that processes a PPP transaction, if supplied. Empty string is returned if shipping feature is not enabled. Optional. Shipping city of the user that processes a PPP transaction, if supplied. Empty string is returned if shipping feature is not enabled. Optional. Shipping address of the user that processes a PPP transaction, if supplied. Empty string is returned if shipping feature is not enabled. Optional. Shipping address of the user that processes a PPP transaction, if supplied. Empty string is returned if shipping feature is not enabled. Optional. Shipping first name of the user that processes a PPP transaction, if supplied. Empty string is returned if shipping feature is not enabled. Optional. Shipping last name of the user that processes a PPP transaction, if supplied. Empty string is returned if shipping feature is not enabled. Optional. Shipping phone of the user that processes a PPP transaction, if supplied. Empty string is returned if shipping feature is not enabled. Optional. Shipping mobile phone of the user that processes a PPP transaction, if supplied. Empty string is returned if shipping feature is not enabled. Optional. Shipping email of the user that processes a PPP transaction, if supplied. Empty string is returned if shipping feature is not enabled. Optional. coupons Optional. The handling which you have passed as the handling parameter initially when making the first request to the G2S Payment Page. Check the Payment Page API guide.

expMonth

expYear

Token tokenId ExErrCode ErrCode AuthCode shippingCountry shippingState shippingCity shippingAddress shippingZip shippingFirstName shippingLastName shippingPhone shippingCell shippingMail total_discount total_handling

total_shipping

Optional. The shipping which you have passed as the shipping parameter initially when making the first request to the G2S Payment Page. Check the Payment Page API guide. Optional. The total tax which you have passed as the total_tax parameter initially when making the first request to the G2S Payment Page. Check the Payment Page API guide. Depends. Only when buy button payment was processed. Contain the ID of the product bundle. Mandatory. The ID, provided by Safecharge, which uniquely defines a particular merchant customization. Check the Payment Page API guide. Mandatory. The version of the request. Default value is 1.0.0. Otherwise version 3.0.0 may be supplied. Mandatory. A message from the PPP about the transaction that has been done.

total_tax

buyButtonProductBundleId merchant_site_id requestVersion message merchantLocale unknownParameters payment_method ID merchant_id responseTimeStamp buyButtonProductId rebillingPriceDescriptor rebillingProductName membershipId memberId rebillingMessage dynamicDescriptor rebillingTemplateId initial_amount rebilling_amount rebilling_currency Reason ReasonCode

autorun;pppurl;#ppp
Mandatory. The payment method used for this transaction such as cc_card, dc_card, giro etc. Tva e Hebrew ID-to Mandatory. The unique merchant id supplied by Safecharge. Check the Payment Page API guide. 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 N/A if not rebilling N/A if not rebilling N/A if not rebilling N/A if not rebilling Mandatory. Dynamic descriptor passed to the Safecharge gateway for the current transaction. N/A if not rebilling Optional. Initial amount dynamic rebilling parameter if supplied. Optional. Rebilling amount dynamic rebilling parameter if supplied. Optional. Rebilling currency dynamic rebilling parameter if supplied. Depends. A reason that the gateway has returned if the transaction fails. See Safecharge gateway specification. N/A if it is not a regular transaction. Depends. A reason code that the gateway has returned if the transaction fails. See Safecharge gateway specification. N/A if it is not a regular transaction.

item_name_X

item_number_X

item_amount_X

item_quantity_X

item_discount_X

item_handling_X

item_shipping_X

Mandatory. The item name which you have passed as the item_name_X parameter initially when making the first request to the G2S Payment Page. Check the Payment 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 request to the G2S Payment Page. Check the Payment 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 request to the G2S Payment Page. Check the Payment 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 request to the G2S Payment Page. Check the Payment 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 request to the G2S Payment Page. Check the Payment 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 request to the G2S Payment Page. Check the Payment 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 request to the G2S Payment Page. Check the Payment Page API guide. N/A if it is not a regular transaction.

Вам также может понравиться