EveryPay Payment API Field Specifications

Transcription

1 EveryPay Payment API Field Specifications Merchant Integration Manual

2 Contents Contents Payment Initiation from E-shop to Payment Gateway HMAC-data generation example in Ruby HTML form example Embedded payment form using iframe Embedding iframe Automatic Callback to E-shop with Transaction Results Redirect to E-shop After Payment Attempt Payment cancellation Tailoring the integration HMAC Changelog 1

3 Payment Initiation from E-shop to Payment Gateway Gateway API endpoint URLs (for HTTP POST form target) in EveryPay environments: Test/demo/sandbox: Production: Description of the optional field markings: O - field is optional OF - field is optional, but including it improves fraud detection (therefore it s highly recommended to provide this information whenever possible) Field name Optional Description api_username account_id Merchant API username. The value can be found in Merchant Portal in the Settings section. Processing account to be used for the transaction. Processing account defines the transaction processing configuration, including the currency to be used, pricelist, 3D Secure settings, payment recurrence, clearing settings, etc. Example values could be: EUR1, USD2. The field value can be found in Merchant Portal in the Settings section. timestamp callback_url customer_url Random unique value to prevent replay attacks Time of creating the transaction. Expressed as seconds from January 1, 1970 UTC Once EveryPay gateway has processed the transaction, processing result data is posted to this URL. When the buyer clicks on the Back button, he will be redirected to this URL. OF address (buyer) amount Payment amount Order reference, must be unique for every payment attempt 2

4 user_ip IP-address (buyer) billing_address OF Billing address billing_country OF Billing country, in two-character ISO format billing_city OF Billing city billing_postcode OF Billing postcode delivery_address OF Delivery address delivery_country OF Delivery country, in two-character ISO 3166 format delivery_city OF Delivery city delivery_postcode OF Delivery postcode hmac hmac_fields Keyed-hash message authentication code. HMAC is constructed by concatenating form parameter keys and values into a string ordered by alphabetic order of the key name and returning its hexdigest with shared secret. Shared secret key can be viewed and changed in Merchant Portal in the Settings section. It is a string which contains all fields (keys) that are going to be used in hmac calculation, separated by comma. hmac_fields should contain a key hmac_fields and should not contain a key hmac. E.g: "account_id,,timestamp,amount,,user _ip,callback_url,customer_url,api_username,transaction_ty pe,hmac_fields" transaction_type Card transaction type to be initiated. Accepted values are: authorisation charge Authorisation: A process of getting approval to the transaction and booking the required amount on the card (without actually transferring the funds yet). The funds need to be captured manually from the merchant portal. Charge: An authorisation followed by an immediate capture - request to transfer the funds for the delivery of goods or services automatically, without the need for 1 3

5 further manual actions. locale O Sets the locale and the language of the EveryPay Payment Page user interface displayed to the customer. Defaults to en. Accepted values are: en - English et - Estonian ru - Russian Please contact the Everypay support if you need other supported locales. Note: This field must not be included for HMAC calculation. cc_token O Enables payment with stored card token. If a valid cc_token is provided, the buyer will not be required to fill in card details. request_cc_token O Accepted values are: 1 - cc_token will be returned in callback 0 (default) - cc_token will not be returned in callback HMAC-data generation example in Ruby data = { transaction_type: "authorisation", amount: "10.0", api_username: "1adcffbf5e2df582", account_id: "EUR1", billing_address: "Tamme 2", billing_city: "Tallinn", billing_country: "EE", billing_postcode: "12345", callback_url: " 4", customer_url: " delivery_address: "Kuuse 3", delivery_city: "Tallinn", delivery_country: "EE", delivery_postcode: "12345", " @example.org", : "d6e33441e e f754", : "98c9fa2e52f ff4da714", timestamp: " ", user_ip: " ", hmac_fields: "account_id,,timestamp,amount,,user_ip,callback_url,customer_url,api_usernam e,transaction_type,hmac_fields,billing_address,billing_city,billing_country,billing_postcode,del ivery_address,delivery_city,delivery_country,delivery_postcode" } hmac_string = data.sort.map{ k,v "#{k}=#{v}" }.join("&") 4

6 hmac = OpenSSL::HMAC.hexdigest("sha1", "shared_api_secret", hmac_string) HTML form example <form action=" method="post"> <input name="hmac" value="75ed21e06d7e3ed26d1eb8b3fab24bdf3d73df20"> <input name="hmac_fields" value="account_id,,timestamp,amount,,user_ip,callback_url,customer_url,api_u sername,transaction_type,hmac_fields,billing_address,billing_city,billing_country,billing_postco de,delivery_address,delivery_city,delivery_country,delivery_postcode"> <input name="transaction_type" value="authorisation"> <input name="locale" value="en"> <input name="amount" value="10.0"> <input name="api_username" value="1adcffbf5e2df582"> <input name="account_id" value="eur1"> <input name="billing_address" value="tamme 2"> <input name="billing_city" value="tallinn"> <input name="billing_country" value="ee"> <input name="billing_postcode" value="12345"> <input name="callback_url" value=" f4da714"> <input name="customer_url" value=" <input name="delivery_address" value="kuuse 3"> <input name="delivery_city" value="tallinn"> <input name="delivery_country" value="ee"> <input name="delivery_postcode" value="12345"> <input name=" " value=" @example.org"> <input name="" value="d6e33441e e f754"> <input name="" value="98c9fa2e52f ff4da714"> <input name="timestamp" value=" "> <input name="user_ip" value=" "> <input class="btn btn-danger" type="submit" value="proceed to Payment"> </form> Embedded payment form using iframe If you don t want buyers to redirect away from your site during the payment process then just embed the iframe in payment flow to take care of collecting the payment information and charge the user. Field name Optional Description skin_name To get it, go to merchant portal and create skin under IFrame skins tab. Use default if you want to use default skin design. 5

7 Embedding iframe <iframe id="iframe-payment-container" name="iframe-payment-container", width="460", height="400"></iframe> <form action=" id="iframe_form" method="post" style="display: none" target="iframe-payment-container"> <input name="hmac" value="75ed21e06d7e3ed26d1eb8b3fab24bdf3d73df20"> <input name="transaction_type" value="authorisation"> <input name="locale" value="en"> <input name="amount" value="1.0"> <input name="api_username" value="b3616e26a91d3cb4"> <input name="account_id" value="eur1"> <input name="callback_url" value=" ff4da714"> <input name="customer_url" value=" <input name="" value="30d7810d31dbb77d4300fd3f6a59ff11"> <input name="" value="98c9fa2e52f ff4da714"> <input name="timestamp" value=" "> <input name="user_ip" value=" "> <input name="skin_name" value="default"> </form> <script> window.onload = function() { document.getelementbyid("iframe_form").submit(); } </script> Automatic Callback to E-shop with Transaction Results Field name Optional Description api_username account_id timestamp amount payment_reference payment_state Merchant API username Processing account ID that was used to process the transaction Random unique value to prevent replay attacks. Validating the uniqueness of the returned '' value on merchant's side will add an extra layer of security. Seconds from January 1, 1970 UTC Transaction amount Order reference Payment reference ID Current state of the payment. Possible values are: 6

8 settled authorised failed processing_errors processing_warnings hmac hmac_fields Array of error hashes in JSON format. Note: Don t use code escapes for HMAC calculation. Hash of fraud check warnings in JSON format. Note: Don t use code escapes for HMAC calculation. Calculated HMAC for request authenticity verification over the fields in the response message. Use only the fields listed in hmac_fields for HMAC calculation, all the other fields should be ignored. The HMAC must be generated based on the exact returned fields, i.e. without code escapes for processing_errors and processing_warnings fields. It is a string which contains all fields (keys) that are going to be used in hmac calculation, separated by comma. hmac_fields contains a key hmac_fields and does not contain a key hmac. E.g: "account_id,,timestamp,amount,,us er_ip,payment_reference,payment_state,api_username,tr ansaction_result,hmac_fields" transaction_result Result of the transaction. Possible values are: completed failed cc_token O cc_token will be returned only if it was requested in the Payment Initiation. cc_last_four_digits Last four digits of the card number. 7

9 Redirect to E-shop After Payment Attempt Once the buyer has been redirected back to the merchant's shop after the payment attempt, the following parameters will posted to the redirect URL (customer_url): Field name api_username account_id timestamp amount payment_reference payment_state hmac hmac_fields Description Merchant API username Processing account ID that was used to process the transaction Random unique value to prevent replay attacks. Validating the uniqueness of the returned '' value on merchant's side will add an extra layer of security. Seconds from January 1, 1970 UTC Transaction amount Order reference Payment reference ID Current state of the payment Calculated HMAC for request authenticity verification. Use only the fields listed in hmac_fields for HMAC calculation, all the other fields should be ignored. It is a string which contains all fields (keys) that are going to be used in hmac calculation, separated by comma. hmac_fields contains a key hmac_fields and does not contain a key hmac. E.g: "account_id,,timestamp,amount,,user_ip,payme nt_reference,payment_state,api_username,transaction_result,hmac_fi elds" transaction_result Result of the transaction. Possible values failed - if the transaction failed completed - if the transaction was successfully completed 8

10 Payment cancellation If the buyer decides to cancel the payment and move back to the merchant s e-shop, the following parameters will posted to the given URL (customer_url): Field name timestamp payment_state hmac hmac_fields Description Random unique value to prevent replay attacks. Validating the uniqueness of the returned '' value on merchant's side will add an extra layer of security. Seconds from January 1, 1970 UTC Order reference Current state of the payment. In case of a cancellation the value is cancelled. Calculated HMAC for request authenticity verification. Use only the fields listed in hmac_fields for HMAC calculation, all the other fields should be ignored. t is a string which contains all fields (keys) that are going to be used in hmac calculation, separated by comma. hmac_fields contains a key hmac_fields and does not contain a key hmac. E.g: "api_username,payment_state,timestamp,,transaction_result,order_r eference,hmac_fields" transaction_result api_username Result of the transaction. In case of a cancellation the value is cancelled. Merchant API username 9

11 Tailoring the integration All Everypay message responses contain the field, that can be used to verify uniqueness of the response message. This approach helps to prevent possible message replay attacks. Validating the uniqueness of the returned value on merchant's side will add an extra layer of security. It requires storing values of the received messages and comparing the values of the received messages against the stored values. The main purpose of parameter is to match the payment in EveryPay s system to the correct corresponding order in merchant s e-shop. must be unique. As an additional benefit, matching the and validating its uniqueness in merchant s e-shop provides an extra layer of security against tampering attacks. HMAC HMAC calculation can be tricky and it s important to pay extra attention to which API parameters and how should be included in HMAC calculations. For example: the hmac_fields field is used in all stages of the payment (initiation, callback, redirect, cancellation) to assist with providing required information about which fields are included in HMAC calculation the JSON contents of processing_errors and processing_warnings fields in callback should not be escaped Changelog Date Change Added hmac_fields field Added iframe integrated payment form feature Added token payment parameters: cc_token request_cc_token cc_last_four_digits Initial document 10