WebLINK Developer Guide
- Mark Mauer
- Timothy Taylor
- Noah Hippensteel
- Angela Nicgorski (Unlicensed)
Overview
BridgePay's WebLINK interface is a flexible, integrated payment solution for e-Commerce transaction processing. WebLINK accepts transaction request data through an HTTPS POST from the merchant website.
WebLINK creates a payment page for you in response to an HTTPS POST from a web <form> and hosts it on the BridgePay servers. You can customize the payment page to match your website's branding and data collection needs.
Use WebLINK to ensure the merchant is outside of PCI scope and to get up and running quickly. The available template customization features provide enough flexibility for your desired user experience.
WebLINK also generates and displays a receipt for the transaction within the WebLINK interface. After processing the transaction, WebLINK returns transaction details and customer information to the merchant.
WebLINK | |
|---|---|
Use Case | Web payment form. |
PCI Scope | Merchant is outside PCI scope. |
User Interface | Hosted by WebLINK. |
Customization | Default payment form. |
Integration Effort | Simple integration with minimal configuration. |
In addition, WebLINK can be configured to send receipt emails to customers and transaction confirmation emails to merchants. BridgePay provides standard templates for all pages and emails, but you may create and save your own custom templates using the BridgePay Merchant Boarding Portal.
Integration
To use WebLINK, create an HTML form that POSTs to the WebLINK URL. Set the parameters in the form to control and customize behavior. WebLINK generates a payment form for the customer. When the customer completes the payment, WebLINK displays a receipt and sends the results to a specified URL.
See Flow Chart for an overview of WebLINK logic. The following sections describe how to use WebLINK in an integration.
Creating the Form
The first step is to create the form that submits to WebLINK. The <form> element must specify a method of post and an action pointing to the WebLINK URL:
https://www.bridgepaynetsecuretest.com/WebLink3/WebLink.aspx
The minimum fields you need to submit on the form are:
mode - This value must be PaymentForm.
purchaseToken - A previously acquired GUID from the BridgeComm ActionService (see the BridgeComm v2.3.4 or later documentation for details on acquiring a purchase token).
Purchase Tokens are used to securely represent the Login/Merchant credentials for a single transaction. Each Purchase Token is valid for 15 minutes and is then deleted.
Include data fields as <input> elements in the form. Specify the name of the field in the name attribute and the value in the value attribute. Specify a type attribute value of hidden to prevent the value from being displayed on your HTML page, or use a standard HTML input type to allow customers to fill in values.
The following example configures WebLINK in the simplest format possible. WebLINK creates a hosted payment form, collects all customer and payment data, and handles the receipt.
<form method=post action="https://www.bridgepaynetsecuretest.com/WebLink3/WebLink.aspx" ">
<input type="hidden" name="mode" value="PaymentForm"/>
<input type="hidden" name="purchasetoken" value="PREVIOUSLY_ACQUIRED_PURCHASE_TOKEN"/>
<input type="submit" value="Submit payment"/>
<input type="hidden" name="TotalAmt" value="6.07"/>
<input type="submit" value="Submit payment"/>
</form>
The following shows an example of the default payment page:
Sending Additional Data
In addition to the minimum fields, you can send additional data regarding the transaction to the form. Any additional data that you send, such as billing information, is pre- filled when WebLINK displays the payment form.
The following example pre-fills an amount of $20.00 on the payment form:
<form method=post action="https://www.bridgepaynetsecuretest.com/WebLink3/WebLink.aspx"">
<input type="hidden" name="mode" value="PaymentForm" />
<input type="hidden" name="purchasetoken" value="PREVIOUSLY_ACQUIRED_PURCHASE_TOKEN" />
<input type="submit" value="Submit payment" />
<input type="hidden" name="TotalAmt" value="20.00" />
<input type="submit" value="Submit payment" />
</form>
See Request Fields for a complete list.
Handling Responses
When operating WebLINK, applications typically need to know when/if a transaction completed successfully in order to record that in the merchant’s system. WebLINK provides a few parameters that can be used for this purpose:
ReceiptURL – If provided, WebLINK POSTs all transaction data and re-direct the user’s browser to this URL after a successful transaction. If this parameter is not provided, WebLINK simply displays the standard receipt page by default. See ReceiptURL Sample for an example of this page in ASP.
FailURL – If provided, WebLINK POSTs all transaction data and re-directs the user’s browser to this URL after a declined transaction. If this parameter is not provided,
WebLINK simply displays the payment form again with the error message displayed.CompleteURL – If provided, WebLINK POSTs all transaction data to this URL. Any output generated from this URL is NOT sent to the user’s browser, however. This is the ideal place to do any post transaction work. See CompleteURL Sample for an example of this page in ASP.
<form method=post action="https://www.bridgepaynetsecuretest.com/WebLink3/WebLink.aspx"">
<input type="hidden" name="mode" value="PaymentForm" />
<input type="hidden" name="purchasetoken" value="PREVIOUSLY_ACQUIRED_PURCHASE_TOKEN" />
<input type="submit" value="Submit payment" />
<input type="hidden" name="TotalAmt" value="23.89" />
<input type="hidden" name="ReceiptURL" value="https://www.somehost.com/receipt.aspx" />
<input type="hidden" name="MerchantEmail" value="owner@somehost.com" />
<input type="hidden" name="EmailFrom" value="noreply@somehost.com" />
<input type="submit" value="Submit payment" />
</form>
The following example uses WebLINK to display the payment form, collect the customer and payment information, and generate a merchant confirmation email. The receipt, however, displays on the merchant's website, as set in the ReceiptURL value.
Once this data is posted to WebLINK, the transaction is processed and an XML response is immediately returned to the caller. The response parameters are contained in the <Data> element.
Every parameter received in the POST message is echoed back to the calling application in the response XML.
The response fields from the gateway are also included in the XML. Response fields are prefixed by r_, for example: r_Result.
The format of the xml is:
For each of transaction, address verification, and card verification results, WebLINK returns two fields: a response code (r_Result, r_AvsResult, r_CvResult) and a text description of the response (r_RespMsg or r_Message, r_AvsResultText, r_CvResultTest). Always use the response codes (r_Result, r_AvsResult, r_CvResult) to verify the results. The text description values cannot be guaranteed to be consistent.
See Response Fields for a complete list.
The merchant application should use the data in the response field to display transaction results to the user and to perform any updates to the merchant’s database that need to be performed.
Styling the Payment Form
You can customize the appearance of the default payment form displayed by WebLINK by including style fields in your request.
The following example sets the page background to dark gray, the form background to light gray, and the font to Times New Roman:
See Payment Form Style Fields for a complete list of style options.
Adding a Cancel Button
If you submit a CancelUrl value, the payment form will include a cancel button. When customers click the cancel button, they are returned to the specified CancelUrl.
The following example adds a Cancel Button to the payment form:
The following shows an example of a payment form with a cancel button:
Using Custom Templates
In addition to customizing the default templates provided by BridgePay, you can also use your own custom payment templates. WebLINK allows you to create custom templates for the payment form, receipts, emails, and timeout errors.
The following example uses a custom payment form template created in the Merchant Boarding Portal.
The integrator collects the customer information, leaving WebLINK to collect payment information and display the receipt.
The element <input type="hidden" name="PaymentFormTID" value="1" /> tells WebLINK to use the custom payment form number one.
Custom templates are set in the Merchant Boarding Portal. See Templates for complete instructions on creating and editing templates.
Tokenization
WebLINK supports the ability to tokenize a card number and re-use it in place of the actual card number in subsequent transactions. These tokens do not expire and are valid as long as the credit card number is valid. For recurring transactions the token and expiration date are required along with the normal sale, auth, etc. transaction request information.
Basic use
Every transaction performed, results in a token being returned to the caller. This token can then be used in subsequent transactions in place of the actual card number. You will still need to provide expiration date and CV number as necessary.
Wallet
WebLINK supports storing card holder payment information for use in subsequent transactions. This functionality expands upon tokenization by also securely storing additional card holder data such as expiration date, card holder name and AVS data.
Requirements
In order to enable the wallet functionality, you must obtain a wallet site identifier. This is used to logically group your wallets for administration purposes. Please work with your Bridgepay integration specialist to obtain a wallet site identifier.
Basic use
Provide the wallet site id you obtained from your Bridgepay integration specialist and enable the wallet via the EnableWallet request field. The payment form will then display an option for the user to save their current payment information for later use. If they select this option and the transaction is processed successfully, a wallet key and wallet token are returned to the caller.
These two values are then used on subsequent requests to WebLINK to enable the end user to use their stored payment information.
Request Fields
WebLINK's standard request fields include customer information, payment information, formatting parameters, and fields that govern WebLINK's behavior. All fields are case-sensitive.
⚡ Request field values for form style and application behavior take precedence over the default Templates and Settings configured in the Merchant Boarding Portal.
The following tables contains field descriptions. Unless otherwise stated, all fields are optional.
🛈 Varchar indicates variable length character string which can include alphanumeric (0-9, a-z, A-Z and hyphens) unless otherwise specified.
🛈 Integer indicates numeric with maximum length of 9 digits unless otherwise specified.
General Purpose Request Fields
The following fields set credentials and basic processing options and are case-sensitive:
Field | Data Type (Length) | Description |
|---|---|---|
PurchaseToken | Varchar(36) | A previously acquired GUID from BridgeComm’s |
Mode | Enumeration | Required. PaymentForm | TokenizationForm PaymentForm: displays a form to collect payment data forprocessing a transaction. |
TransType | Varchar(10) | The transaction type to perform. Valid values are: Sale | Auth Sale: performs a sale transaction. |
Credit Transaction Detail Request Fields
The fields in this table describe the credit transaction being submitted. All fields are case-sensitive.
Field | Data Type (Length) | Description |
|---|---|---|
TotalAmt | Decimal(10,2) | Required. Note: When using Service Fees, the TotalAmt should reflect the base amount plus the Service Fee amount. |
CardTypeName | Varchar(10) | Card Type. Valid values are: Visa, MasterCard, Discover, Amex, Diners, eCheck |
CardNumber | Varchar(16) | Credit card number. |
CardExpMonth | Char(2) | Two digit credit card expiration month. (e.g., 02 for February). |
CardExpYear | Varchar(4) | Two or four digit credit card expiration year (e.g., 2013 or 13). |
CVNum | Varchar(4) | Three or four digit credit card security code (a.k.a., CVV, CV2). |
Description | Varchar(255) | The description of the transaction. |
BillToName | Varchar(150) | Full name of the cardholder. |
BillToStreet | Varchar(128) | The cardholder's street address. |
BillToCity | Varchar(50) | The cardholder's city. |
BillToState | Char(2) | The cardholder's state. |
BillToZip | Varchar(15) | The cardholder's ZIP code. (5 or 5+4 and if 5+4, NNNNN or NNNNNNNNN). |
BillToEmail | Varchar(100) | The email address of the cardholder. If this field is included, an email receipt is sent to this address after a successful transaction. |
MerchantEmail | Varchar(100) | The email address of the merchant. If included, an email receipt is sent to this address after a successful transaction. |
EmailFrom | Varchar(100) | Email address WebLINK specifies as the "from" address for customer and merchant emails. |
InvoiceNum | Varchar(40) | The invoice number to associate with the transaction. |
PONum | Varchar(24) | Purchase order number to associate with the transaction. |
Token | Varchar(40) | The token to process the transaction against. |
TransSequenceNo | Integer | Required only for split transactions. |
Behavior Request Fields
These fields influence how the WebLINK application processes. All fields are case-sensitive. All URL’s must use ‘HTTPS’.
Field | Data Type (Length) | Description |
|---|---|---|
ReceiptURL | Varchar(255) | If the transaction submits successfully, WebLINK |
ReturnReceiptUrl | Varchar(255) | If you choose to have WebLINK handle the receipt and do not provide a value for ReceiptURL, WebLINK provides a link on the receipt page labeled “Return to [Merchant Name]” that will redirect the browser to the ReturnReceiptUrl. |
CompleteURL | Varchar(255) | After a transaction is processed, regardless of its result status, the results are POSTed to CompleteURL. 🛈 If the input parameters passed to WebLINK are configured for WebLINK to display the receipt, WebLINK displays the receipt and POSTs the transaction result to the CompleteURL 🛈 The CompleteURL, and other postback URLs, must be public sites with port 443 open to traffic. We do not support private ports on any postback URLs. 🛈 The results of this POST, if any, are not rendered back to the browser for display to the user. Other receipt behaviors will need to be passed to handle receipt display. |
FailURL | Varchar(255) | WebLINK POSTs to this URL if the payment form 🛈 Leaving this blank causes WebLINK to show the payment form again with any response from the payment gateway displayed on the form.
|
CancelURL | Varchar(255) | If provided, a cancel button is rendered on the payment form that, when clicked, redirects to the CancelUrl. 🛈 Adding a space and then "confirm" causes a confirmation dialog to appear before the end user is re-directed. E.g., "https://www.domain.com/cancelTransaction.php confirm". |
ReturnURL | Varchar(255) | The URL that users are returned to when their session times out. |
ReceiptLogoUrl | Varchar(255) | The URL to the logo image to display on receipts. Provide this value to display a logo image on receipts that is different from the values configured in the Merchant Boarding Portal. |
PaymentServerType | Enumeration | Type of payment server to interface with. Valid BPN BPN: uses the BridgePay payment server for live transactions (default) |
PaymentTypes | Varchar(50) | The payment types to display on the payment form. This also enables the Card Type to be displayed in the drop down box. This is a comma delimited string of the following possible values: AMEX, Discover, Visa, Mastercard, Diners, eCheck The default value is: AMEX, Discover, Visa, Mastercard, eCheck 🛈 The values are case sensitive. |
SessionTimeout | Integer | The amount of time in minutes before the user’s session times out. Min: 1, Default: 10, Max: 30 |
RespondWithLastFailureOnly | Varchar(1) | Provide a non-empty string in this field to indicate to WebLINK that a response of a declined transaction to the CompleteURL parameter URL should only occur after the user’s session times out and should only include the last failure if there were more than one. Successful transactions will always be POSTed back to CompleteURL immediately regardless of this setting. |
UseServerSidePostBacks | Varchar(1) | Provide a non-empty string in this field to indicate to WebLINK that it should POST results to ReceiptURL and FailURL from the server instead of a client-side re-direct. Server-side posting is more secure than client-side, but can only be used with publicly accessible URLs. Default value is [null]. |
Template Selection Request Fields
The following fields allow you to set custom templates to use for the payment form, receipts, and email. If you do not submit values, WebLINK uses the default forms. All fields are case-sensitive.
Field | Data Type (Length) | Description |
|---|---|---|
PaymentFormTID | Integer | The template ID specifying which payment form to display. Applicable to the normal payment form, tokenized payment form and the token creation form. |
ReceiptTID | Integer | The template ID specifying which receipt form to display. |
CustomerEmailTID | Integer | The template ID specifying which customer email to send. |
MerchantEmailTID | Integer | The template ID specifying which merchant email to display. |
SettlementDelay | Integer | The number of days to delay auto settlement of the transaction. |
Payment Form Style Fields
The following fields can be used to customize the look and feel of the WebLINK payment collection form. All fields are case-sensitive.
Field | Data Type (Length) | Description |
|---|---|---|
Style_Page_BackgroundImage | Varchar(255) | The URL to an image file to be included as the background image for the payment form. |
Style_Page_BackgroundColor | Varchar(7) | The color to use for the page background color. The default value is “#FFF”. |
Style_Form_BackgroundColor | Varchar(7) | The color to use for the payment form background color. The default value is “#FFF”. |
Style_FontFamily | Varchar(255) | The font family to use on the payment form. One or more font names, separated by commas. The default value is “Verdana, Arial, Helvetica, sans- serif”. |
Style_Heading_FontColor | Varchar(7) | The color to use for heading text on the payment form. The default value is “#000”. |
Style_Heading_FontSize | Integer | The size of the font to display for heading text on the payment form. The default value is “13”. |
Style_Heading_BackgroundColor | Varchar(7) | The background color for the heading sections of the payment form. |
Style_Instruction_FontColor | Varchar(7) | The color to use for instruction text on the payment form. The default value is “#000”. |
Style_Instruction_FontSize | Integer | The size of the font to display for instruction text on the payment form. The default value is “11”. |
Style_Label_FontColor | Varchar(7) | The color to use for the field label text on the payment form. The default value is “#000”. |
Style_Label_FontSize | Integer | The size of the font to display for field label text on the payment form. The default size is “10”. |
Style_Field_FontColor | Varchar(7) | The color to use for field input text on the payment form. The default value is “#000”. |
Style_Field_FontSize | Integer | The size of the font to display for field input text on the payment form. The default size is “12”. |
Wallet Request Fields
The following fields are used when you wish to take advantage of the wallet functionality. All fields are case-sensitive.
Field | Data Type (Length) | Description |
|---|---|---|
EnableWallet | Varchar(1) | Check to Enable Wallet functionality. True or False. |
SiteId | Guid | The id of the site to create the wallet under. ⚡This value should only be provided when creating a new wallet. Leave this field blank if you are using a previously created wallet. |
WalletToken | Varchar(500) | The Wallet Token of the wallet you wish to use for the transaction. ⚡Do not provide a value here if you are creating a new wallet. |
WalletKey | Varchar(500) | The Wallet Token of the wallet you wish to use for the transaction ⚡Do not provide a value here if you are creating a new wallet. |
Response Fields
All request fields are echoed back in the response messages sent by WebLINK and are case-sensitive. The transaction results from the host are also included, prefixed by r_.
These fields are available for use in email and receipt templates, and when specified, these fields post to FailURL, CompleteURL, and ReceiptURL.
⚡ Some fields are only available after initiating the transaction (e.g, AuthCode).
The following table contains field descriptions of the host response fields:
Field | Data Type (Length) | Description |
|---|---|---|
r_AuthCode | Varchar(50) | The transaction result code from the payment processor. Format varies by processor. |
r_HostCode | Varchar(30) | A number that uniquely identifies the transaction in the payment processor. Format varies by processor. ⚡Not all payments processors return this value. |
r_Message | Varchar(255) | A formatted response message concerning the processed transaction. This value is typically APPROVAL for approved transactions or an error message for declined transactions. |
r_Result | Varchar(50) | Result code that signifies the result of the transaction. ⚡When programmatically validating a |
r_Id | Integer | Number that uniquely identifies the transaction in the |
r_Token | Integer | The tokenized card number returned from the payment server. This can be used in subsequent transactions in place of the CardNumber field by sending the token in the Token field and leaving the CardNumber field blank. |
r_CardType | Varchar(50) | The card type name of the card used. ⚡This field is only populated when the CardNumber field is used. |
r_LastFour | Varchar(4) | The last four digits of the card number used in the transaction. |
r_AuthorizedAmount | Decimal | The actual amount authorized to the card. This amount will differ from the requested amount for partial approvals. |
r_WalletToken | Varchar(500) | The wallet token of the newly created wallet if applicable. |
r_WalletKey | Varchar(500) | The wallet key of the newly created wallet if applicable. |
r_AvsMessage | Varchar | Unipay AVS Match Result Message. |
r_AvsResult | Varchar | Unipay AVS Match Result Code. |
r_CvMessage | Varchar | Unipay CVV/CVV2 Match Result Message. |
r_CvResult | Varchar | Unipay CVV/CVV2 Match Result Code. |
Templates and Settings
The following sections discuss how to use the BridgePay Merchant Boarding Portal to configure templates and default settings. The Merchant Boarding Portal is available at:
https://www.mybridgepaytest.com/
Settings
The application settings available for configuration are:
PaymentTypes
MerchantEmail
ReceiptURL
FailURL
EmailFrom
ReceiptLogoURL
For description of these fields, see Request Fields.
⚡Remember that you can also set the values for these fields on a case-by-case basis in the form post. Values in the form posts take precedence over values set in the
Merchant Boarding Portal.
Templates
WebLINK uses these types of templates:
CustomerEmail – Customizes the display of the transaction receipt email sent to customer.
MerchantEmail – Customizes the display of the transaction confirmation email sent to the merchant.
PaymentForm – Configures the settings and display of the payment form.
PaymentFormSplit – Configures the settings and display of the payment form for split transactions.
TokenziationForm – Configures the settings and display of the tokenization form.
Receipt – Configures the settings and display of the transaction receipt.
ReceiptSplit – Configures the settings and display of the transaction receipt for split transactions.
SessionTimeout – Configures the settings and display of the page when a session timeout occurs.
There are two categories of templates: merchant and custom. WebLINK invokes merchant templates by default if you don't pass a custom template ID in the request data. You may also create a custom template and invoke it on-demand by passing the corresponding Template ID (TID) when posting to WebLINK.
To customize a merchant template, paste your formatted code into the HTML field for the specified template and click Save. To create a custom template, select the template type from the dropdown menu and click Create. A new template entry appears with a new TID. Paste your custom template code into the HTML field and click Save.
You are responsible for pasting in the proper HTML for the new template. See Request Fields for a list of custom template ID fields and Formatting Templates below for information on formatting the template HTML properly.
Formatting Templates
All templates consist of HTML pages. HTML pages can be customized using various WebLINK-specific placeholder tags. The following sections describe how to use the placeholder tags. See the default templates in the merchant boarding portal for more examples on how to create templates.
Parameter Placeholders
WebLINK uses unique placeholders inside of templates to render the payment form, payment receipt, merchant transaction confirmation email, and customer transaction receipt email. You structure these templates just like typical HTML documents, but you also include specific placeholders that WebLINK uses to assemble the form or email.
Placeholder Format
⚡Remember that you can also set the values for these fields on a case-by-case basis in the form post. Values in the form posts take precedence over values set in the
Merchant Boarding Portal.
If the customer's browser supports JavaScript, there is client-side validation in addition to server-side validation after submitting the payment form. WebLINK automatically generates the necessary JavaScript code for you.
You can use placeholders almost anywhere in an HTML template. Simply use the placeholder inside an HTML tag, such as a <span> and WebLINK displays the placeholder’s value in the template.
Placeholder Format
You can also use a placeholder as the value attribute of an <input> element. In this case, WebLINK pre-fills the input field with the value of the placeholder when rendering the template.
⚡The element's <input> name attribute must match the name of the placeholder.
Required Placeholders
These placeholders must be in every template in order for WebLINK to function properly:
Placeholder | Description |
|---|---|
<!-- %%STYLES%% --> | This must reside inside the <head> tag of the template. |
<!-- %%HEAD_SCRIPT%% --> | This must reside in the <head> tag of the template. |
<!--%%BODY_SCRIPT%% --> | This must reside before the closing </body> tag. |
Security Logo Placeholders
These optional placeholders display security logos:
Placeholder | Description |
|---|---|
<!—{{ thawte }} --> | This is the placeholder for the Secured by Thawte logo and must reside within the <body> of the document. |
<!—{{ align }} --> | This is the placeholder for the A-lign PCI DSS logo and must reside within the <body> of the document. |
Reserved Placeholders
All Request Fields are reserved placeholders. For example, if you put <!--[ InvoiceNum]--> in the HTML template for the payment form and submitted a value of 123456 in the text box, the payment server receives 123456 as the invoice number for the transaction.
Special Reserved Placeholders
The following table contains special reserved placeholders. See Parameter Placeholders for an example of placeholder usage.
Placeholder | Description |
|---|---|
TotalAmt | Renders as an input tag for the TotalAmt field in the payment form and plaintext for emails and receipts. (E.g., 3.63.) |
BillToState | Renders a select tag for the BilltoState field. |
CardTypeName | Renders a select tag for the card type. |
PaymentTypeImages | Renders <img> tags for the available payment types. |
CardExpMonth | Renders a select tag for the CardExpMonth field. |
CardExpYear | Renders a select tag for the CardExpYear field. Year range includes the current year + 9 years. |
CheckType | Renders a select tag for the CheckType field. Possible values include: Personal | Corporate | Government |
AcctType | Renders a select tag for the AcctType field. Possible values include: Savings | Checking |
ValidationErrors | Renders an unordered list tag and list elements for each server validation error WebLINK encounters. |
GenericAcctNum | Displays the masked credit card or checking account number. |
TransDate | Displays the date and time of transaction processing. |
SplitAmounts | Renders each transaction line item for split payment transactions. This placeholder is only used in the PaymentFormSplit template. The following HTML template (from the bottom of the default PaymentFormSplit template) can be customized to alter how each transaction total line item appears: |