WebLINK Developer Guide
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:
<Data>
<Login>loginName</Login>
…other posted fields
<r_Result>0</r_Result>
…other result field
</Data>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:
<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="hidden" name="Style_Page_BackgroundColor" value="#A9A9A9" />
<input type="hidden" name="Style_Form_BackgroundColor" value="#D3D3D3" />
<input type="hidden" name="Style_FontFamily" value="’Times New Roman’" />
<input type="submit" value="Submit payment" />
</form>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:
<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="hidden" name="CancelUrl" value="<https://bridgepaynetwork.com/ confirm>" />
<input type="submit" value="Cancel 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.
<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="PaymentFormTID" value="1" />
<input type="text" name="BillToName" value="John Doe" />
<input type="text" name="BillToStreet" value="100 N Main St." />
<input type="text" name="BillToCity" value="Beverly Hills" />
<input type="text" name="BillToState" value="CA" />
<input type="text" name="BillToZip" value="90120" />
<input type="submit" value="Submit payment" />
</form>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 for Mode = PaymentForm Not Required for Mode = TokenizationForm The total amount of the transaction. The decimal should be explicitly entered with the amount (e.g., 5.83; 0.99). 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 |