BLUEFIN HOSTED PAYMENT FORMS

Transcription

1 BLUEFIN HOSTED PAYMENT FORMS Date modified: 4/15/16 (Version 1.2)

2 Bluefin Payment Systems Page 2

3 Contents Settings Menu... 4 Account Settings... 5 Managing Groups... 5 Hosted Payment Forms... 7 Hosted Payment Form List... 8 Editing Hosted Payment Forms... 9 General Section Response Handling Section Appearance Settings Custom Fields The Hosted Payment Form Rendered Rendering Hosted Payment Forms Custom Form Fields Handling Responses: Online Receipt Pages Receipt Page Decline Page Configurable URLs for Handling Responses Example Code A text link: The same form request as an IFRAME: The same form request via HTTP POST could be done with this HTML snippet: Appendix: Using HASH for Authenticated Transactions Variables Index Bluefin Payment Systems Page 3

4 Settings Menu The Settings menu houses the configuration pages where you will control the behavior of your account, and sub-accounts. For Hosted Payment Forms, two items are of particular interest: Manage Settings: This page allows you to define the overall behavior of your account with regards to processing transactions. Manage Groups: Groups are the mechanism for: Informal categorization of transactions by name. Formal categorization of transactions by merchant account and/or processor. Processing split transactions. Bluefin Payment Systems Page 4

5 Account Settings The first step in getting ready for using Hosted Payment Forms is checking with Bluefin to make sure that your account is configured to allow Hosted Payment Forms. The next step is to look in your account settings (Settings Manage Settings) to ensure your transaction parameters are set correctly. Require Encrypted Swipe. If you are utilizing a P2PE (or encrypted) swipe or card reader, to make use of the Card Present form type, you must have the account set correctly. Contact Bluefin to make sure this option is set correctly. Allow Credit Cards. Set this option to YES to enable or NO to disable all forms of Credit/Debit cards on your forms. Allow Checks. Set this option to YES to enable or NO to disable ACH as a payment option on your forms. After making your selections, make sure you click the UPDATE SETTINGS button at bottom of page to save them. Managing Groups As mentioned above, Groups can provide the mechanism to create categories, or buckets, for transactions, but is optional. Shown below is the List view of your Groups. The right hand column contains four clickable icons providing the following Actions, from left to right: View Show more details of the selected Group. Edit Open an edit window to alter the Group s parameters. Manage Forms Open the Hosted Payment Forms list for the selected Group. Delete Remove the Group from PayConex. Bluefin Payment Systems Page 5

6 Each Group has the following attributes: a) ID. This is a numerical identifier, unique throughout the PayConex system. It is not editable. b) Name. This is a short descriptor, comprised of letters and numbers only, unique to your account. It cannot be changed once set. c) Description. This is a human readable, long descriptor, for display/reporting use. d) Merchant Account. Sometimes this is referred to as the Processor. This ties the Group to a merchant account associated with your primary account. Merchant Account may be left blank/default to define the Group as simply a tool for categorizing transactions. Bluefin Payment Systems Page 6

7 Hosted Payment Forms The Tools menu provides links to the reporting engine within PayConex, quick-links to the Settings and Agent menus, and of particular relevance to this document, the Hosted Payment Forms module. Bluefin Payment Systems Page 7

8 Hosted Payment Form List The Hosted Payment Forms (HPF) List view displays your existing forms/pages grouped by the Group they have been assigned, and allows you to create a new one. Within each Group of HPF s one of the forms can be assigned as the default for the account. The right-hand column contains four clickable icons providing the following Actions : Edit - Update the inputs, layout settings, and other attributes of the form. Preview - Renders the selected HPF in a new tab/window. Delete - Physically deletes the selected HPF. Create a Copy - Creates an exact copy of the selected HPF to facilitate template building. Bluefin Payment Systems Page 8

9 Editing Hosted Payment Forms The HPF Edit page is split into four primary sections, discussed in separate sections: General settings: These define the required inputs. Response Handling: Used to enable transparent redirect of transaction responses for customized receipt, decline, and postback behavior. Appearance: Fonts, colors, borders, and custom copy text are all defined in this section. Custom Fields: Any data that you may wish to be passed through, along with the standard transaction data, is defined here. Bluefin Payment Systems Page 9

10 General Section The General section is where the bulk of the setup is done, and is shown below, with descriptions shown after this image. Form Name: Freeform text. Used for identification only. Bluefin Payment Systems Page 10

11 Type: Specifies the action to be taken. Group: Can be blank. If specified, the Primary Charge will flow into the merchant account associated with this Group. Payment Capture Methods: At least one is required. Your choice to enable Card Present (swipe transactions), Card Not Present (keyboard entry of card data), or ACH Check payment. Any combination can be used. Primary Charge: Mandatory. The amount can be overridden in request data. Secondary Charge: Optional, and disabled by default. If specified, this payment will flow into the Main/Master merchant account. The amount can be overridden in request data. Customer Contact Fields: For reporting use only, unless AVS authentication is required by your account settings. Bluefin Payment Systems Page 11

12 Response Handling Section Use these URLs to specify custom handling of receipts, declines, and asynchronous POSTback. NOTE: If the receipt URL is specified and the decline is left blank, the system will automatically use the receipt URL for declines. So, if using this functionality make sure your programs are constructed to handle both type of responses. Bluefin Payment Systems Page 12

13 Appearance Settings The appearance settings allow you to change the look of your HPF to better match your environment. The options are shown below and discussed in detail. Custom Logo: Upload a logo image in JPG, PNG, or GIF format, sized 600w x 200h pixels, with 1MB being the maximum file size. I responded out of this system, and informed them that the dimensions are: 1MB maximum size 600x200 maximum dimensions Accepted file types: gif, jpg, jpeg, tiff, png, bmp Bluefin Payment Systems Page 13

14 Design Elements: A color picker is provided to assist you setting colors of the layout elements in your form, or you may type the hex color code. You may select from several common web friendly fonts. The default is Helvetica. Layout Text: You may specify a custom title for your form, as well as text to be displayed at the top and bottom of your payment page, and a message shown on the payment confirmation page/receipt. Custom Fields Each Custom Field Group allows you to specify a placeholder for non-standard data that your business, or your customers, need in order to complete the end to end payment process. Unless specified as hidden, the data sent via these fields will show up on the standard receipt and decline pages. The Hosted Payment Form Rendered Below is a typical Hosted Payment Form using the default color/font pallet, a Custom Logo, and a Required Amount field. Each standard input field makes use of HTML5 placeholders to assist users in completing the form. Required fields are marked with an asterisk in the label. Real-time field level form validation is performed on each relevant form field, and the form itself will not submit until it is validated, further ensuring that the data sent through to the PayConex API is as complete and accurate as possible. Bluefin Payment Systems Page 14

15 Rendering Hosted Payment Forms The Hosted Payment Forms can be accessed via a direct HTTP request using either GET or POST methods. The base URL to the Hosted Payment Pages is: Certification: Production: These parameters must be sent with your request: PARAMETER TYPE CONTEXT DESCRIPTION action string Required The API method name for rendering HPF s aid integer Required Your PayConex Account ID (Zero-padded 12-digit) id integer Required The Hosted Payment Form numerical ID. Bluefin Payment Systems Page 15

16 These parameters are optional, depending upon your payment pages settings: PARAMETER TYPE CONTEXT DESCRIPTION amount string conditional Required for display_only & hidden fields. Default amount can be sent for required & optional. If form uses multiple amounts both must be sent, delimited by a colon (e.g :1.57) first_name string conditional Payer/customer First Name. Required if display_only or hidden. last_name string conditional Payer/customer Last Name. Required if display_only or hidden. street_address1 string conditional Payer/customer street address. Required if display_only or hidden. city string conditional Payer/customer city. Required if display_only or hidden. state string conditional Payer/customer state (2-character). Required if display_only or hidden. zip string conditional Payer/customer postal (zip) code. Required if display_only or hidden. country string conditional Payer/customer Country. Required if display_only or hidden. phone string conditional Payer/customer phone number. Required if display_only or hidden. string conditional Payer/customer address. Required if display_only or hidden. token_id integer optional A valid payment token ID (transaction id from previous successful AUTH, SALE, or STORE). Setting this disables the Payment Inputs for Card & ACH data. Custom Form Fields In addition to the pre-defined fields listed above, merchants can pass their own user-defined custom parameters. These parameters are defined when creating the hosted form. To submit data to be passed through the system via custom form fields simply send key/value pairs representing the custom field s name, and its value. For example, if one of your custom fields is capturing customer account numbers you might define that as customer_number and in the API request transmit it as &customer_number= If a custom field is defined as either Display Only or Hidden, it must be passed with the request, even if its value is blank/null. Bluefin Payment Systems Page 16

17 Handling Responses: The Hosted Payment Forms module essentially has two (2) ways of handling transaction responses. Online Receipt pages, and Transparent Redirect. Online Receipt Pages For merchants that do not have a full-service back-end application, or do not require direct feedback, the online receipt pages provide the easiest solution for providing customers with confirmation receipts and decline notifications. Receipt Page The receipt page is displayed whenever a transaction is successful, or approved. It will utilize the same logo as the hosted payment form, and will echo the confirmation text as defined on the HPF edit admin page. Receipts will display the following data from the transaction: Payment Amount, or amounts in the case of split transactions. Payment Date Payment Method. The type & last 4 digits of card or account. Payment Status: Approved for Cards, Pending for ACH. Billing name Custom field(s) A button is included to allow customers to print their receipt. Decline Page The decline pages are terminal. They do not provide a means to re-try the transaction. Customers will be presented with a generic message telling them the payment was declined, plus: Payment date Response Code. A numeric code. Response Message. This is the decline notice reflected back from the processor. Bluefin Payment Systems Page 17

18 Configurable URLs for Handling Responses It is possible for the Merchant to specify the various URL s for Response Handling outside of the form setup, if desired. Doing so could lessen the number of forms needed for a Merchant, but it needs t handled in a secure fashion, so care and expertise needs to be used. In the URL that is used to render the Hosted Payment Form, you can control the back-end behavior with by adding even more elements to the URL string. The possible values are explained in the table below. Note that none of them can be sent directly (plain text) and must be included in a hash for security reasons. They do not however need to be specified in a hash_key since they are required to be hashed. For more on HASH and its use, refer to the appendix in this document. PARAMETER TYPE CONTEXT DESCRIPTION success_url string optional Used for a non-default (merchant "hosted") successful transaction receipt. Must be a valid URL that will be called if transaction is successful. It needs to be specified inside the hash, but does NOT need to be included in the hash_key. decline_url string optional Used for a non-default (merchant "hosted") NOT successful transaction receipt. Must be a valid URL that will be called if transaction is declined. It needs to be specified inside the hash, but does NOT need to be included in the hash_key. cancel_url string optional Must be a valid URL that will be called if user presses Cancel button on HPF. It needs to be specified inside the hash, but does NOT need to be included in the hash_key. timeout_redirect string optional Must be a valid URL that will be used if the HPF times out on the user. It needs to be specified inside the hash, but does NOT need to be included in the hash_key. postback_url string optional Must be a valid URL to receive POSTback data. Bluefin Payment Systems Page 18

19 Example Code To render Form ID 21 on Account , passing 2 amounts ($ & $3.95) A text link: <a href=" id=21&amount=123.45:3.95">make a Payment</a> The same form request as an IFRAME: <iframe src=" unt=10.10:1.50" frameborder="0" height="850" width="660" scrolling="no" seamless="seamless" ></iframe> The same form request via HTTP POST could be done with this HTML snippet: <html> <head></head> <body onload="submitform()"> <form action=" method="post" id="autopostform" hidden="hidden" style="visibility:hidden;"> <input type="hidden" name="action" value="view"/> <input type="hidden" name="aid" value=" "/> <input type="hidden" name="id" value="21"/> <input type="hidden" name="amount" value="123.45:3.95"/> <input type="hidden" name="customer_number" value="1234-abcd-001-b"/> <!-- Custom Field --> </form> <script type="text/javascript"> function submitform() { var myform = document.getelementbyid('autopostform'); myform.submit(); } </script> </body> </html> Bluefin Payment Systems Page 19

20 Appendix: Using HASH for Authenticated Transactions A hash function is an algorithm that transforms (hashes) an arbitrary set of data elements, such as a text string or file, into a single fixed length value (the hash). The computed hash value is a means of protecting sensitive data. Bluefin has included this functionality in to its API s, and it uses a Secure Hash Algorithm (SHA-256) type of hash. There are two pieces that are tied to sending a hash; the hash value and the hash_key value (string), although the hash_key is not always required. A description of each REQUIRED parameter in any HASH is included below. Parameter Req'd Description account_id Yes This is the merchant account ID. For any hash, this MUST be included and be the first parameter. api_accesskey Yes This is the merchant s unique key. It should NEVER be given out to anyone. For any hash, this MUST be included and be the second parameter. If it is ever sent in the hash, and outside the hash (it is sent twice), you will receive a Security Violation error. timestamp Yes This is a 10-digit UNIX timestamp representing the number of seconds since Epoch (00:00:00 on January 1, 1970) and should represent the time this transaction occurs. For any hash, this MUST be included and be the third parameter. It is possible in any transaction type to use the HASH method for more than just the required fields (listed above). This is strictly up to the vendor/merchant, but it is recommended by Bluefin to do so. If the merchant wishes to include other data values in the hash, they can be appended to the hash value, but another element must be sent, called the hash_key, which is explained below. Parameter Req'd Description hash_key No A string containing a comma delimited list of parameters used to build the hash. This list should NOT include the three parameters above, or other parameters that are used in transparent redirect (see the Transparent Redirect section for more information). NOTE: All HASH parameters are case sensitive. NOTE: When using the transparent redirect method, the HASH method is REQUIRED. Example #1: If the merchant wishes to send the minimum values of a hash, given the following values: account_id :: api_accesskey :: e6f157d2-66cf-43d5-8a56-c4c57d5760d7 timestamp :: Bluefin Payment Systems Page 20

21 This would be the hash string: ,e6f157d2-66cf-43d5-8a56-c4c57d5760d7, With a resulting hash value that is sent as something like: b48171ba3c4ffbc d661d52a109d d208f52bf7392cbf95 Example #2: Given the same minimum values, and a transaction amount of $123.00, the hash string would look like: ,e6f157d2-66cf-43d5-8a56-c4c57d5760d7, , And the resulting hash value that is sent is something like: c602825bed7fdc9b256ec6ce074b88e6befc18bd0eb295a9acb7af024708aedf Note that in the above example #2 that the merchant would also have to send the following, which would indicate the optional hash_key parameter is included in the hash: hash_key = transaction_amount Variables Index When using a hash, the table below shows the variables that would be sent to QSAPI, along with the request format variables for the given transaction type. Parameter Req'd Description account_id Yes This is the merchant account ID. timestamp Yes This is a 10-digit UNIX timestamp representing the number of seconds since Epoch (00:00:00 on January 1, 1970) and should represent the time this transaction occurs. hash Yes The hash value (NOT the hash string) hash_key No Only required if additional (optional) parameters were included in the hash string NOTE: The parameter "api_accesskey" is NOT to be sent as a separate variable when using transparent redirect. Doing so compromises the integrity of the data, PCI compliancy, and will result in a "security violation" error. NOTE: All HASH parameters are case sensitive. NOTE: The HASH function is new in version 3.8 of the API. Prior versions do not contain this feature. Bluefin Payment Systems Page 21