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.
Highly customizable payment form templates available.

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: 

image-20240212-215532.png

 

 

 

 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:

image-20240222-151414.png

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

Mode

Enumeration

Required.
Valid values are:

PaymentForm | TokenizationForm

PaymentForm: displays a form to collect payment data forprocessing a transaction.
TokenizationForm: displays a form to capture card info, returning a token.
 

TransType

Varchar(10)

The transaction type to perform. Valid values are:

Sale | Auth

Sale: performs a sale transaction.
Auth: performs an authorization only transaction; the amount is authorized but not collected from the customer. (The default value is Sale.)
 

 

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.
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.
The transaction sequence number for this transaction.

 

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
performs an HTTPS POST to this URL for a receipt or transaction confirmation.
Leave this field blank to allow WebLINK to display the receipt automatically. When left blank, WEBLINK displays the receipt in addition to other behaviors, such as the CompleteURL behavior discussed below.
 

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
submission is unsuccessful. All form fields, including transaction result, is POSTed to this URL.

  🛈 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
values:

      BPN
      BridgeComm

BPN: uses the BridgePay payment server for live transactions (default)
BridgeComm: for use with Service Fees. If not present, Service Fees will not function.

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.
   
    ⚡Never use this value when programmatically validating a transaction's result; please see the r_Result.

r_Result

Varchar(50)

Result code that signifies the result of the transaction.

    ⚡When programmatically validating a
transaction's result, always use this value
instead of any response message describing the result.

r_Id

Integer

Number that uniquely identifies the transaction in the
payment gateway. (E.g., 7654314, 245683300.) This
field is more commonly referred to as the reference.

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:
 
<script type="text/template" id="SplitAmounts"><div class="field"><label><!--[Description]--></label>
<label><!--[TotalAmt]--></label></div></script>
 

 

Error Placeholders

Errors display on the payment form with two reserved placeholder fields, r_Message and ValidationErrors. r_Message contains a formatted response message from the payment gateway, describing the status of the processed transaction. ValidationErrors contains a comma-delimited list of errors deriving from improper data entry on the initial post to WebLINK or from the end-user submitting the payment form. If you specify a FailURL,errors post to the given URL instead of displaying on the payment form.

🛈 Validation errors resulting from the end-user's form submission are rare as the forms use client-side validation to handle these types of errors.

 

Conditional HTML Placeholders

Conditional HTML placeholders consist of an opening tag and closing tag. Any HTML between the tags is conditionally rendered by WebLINK based on the following rules:

Placeholder

Description

<!-- PaymentInformation -->
HTML code
<!-- /PaymentInformation -->

If a token is POSTed to WebLINK, then WebLINK does not render this HTML. WebLINK assumes that payment information does not need to be collected from the user.

<!-- WalletUse -->
HTML code
<!-- /WalletUse -->

If a WalletToken, WalletKey and EnableWallet are POSTed in to WebLINK, then WebLINK renders this HTML.

<!-- WalletSave -->
HTML code
<!-- /WalletSave -->

If a SiteId and EnableWallet are POSTed to WebLINK, then WebLINK renders this HTML.

<!-- CancelPayment -->
HTML code
<!-- /CancelPayment -->

If CancelUrl is POSTed to WebLINK, then WebLINK renders this HTML.

 

Custom Placeholders

You can also create custom placeholders to use in the payment form to gather and pass to the receipt or CompleteURL. Format custom placeholders like WebLINK's reserved placeholders.

For example, if you want to give customers a space to include an optional note concerning their order:


⚡Since the placeholder was used in the value parameter, any initial value for “AdditionalNotes” POSTed to WebLINK is rendered in the form. If you do not need to pre-fill the input value, you can simply omit the value attribute.
 

Example

The following is an example of the special placeholder for CardTypeName to generate an HTML <select>, followed by the rendered HTML

 

Placeholder

 

Rendered HTML

eCommerce Integration Options

The following sections discuss several different eCommerce implementations supported by the BridgePay WebLINK application. Each implementation type has different recommendations for secure operation. Impact to merchant operations, PCI DSS compliance and scoping is also discussed and exhibits their own set of advantages and disadvantages.

Integration Types

  1. URL Redirect - Hosted payment page which redirects the consumer to a page on an entirely different domain hosted by Bridgepay for payment entry.

    1. iFrame - An inline frame (or “iFrame”) that allows a payment form hosted by a BridgePay to be embedded within the merchant’s page(s). 

URL Redirect Implementation

In the Redirect model, the cardholder is redirected from the merchant’s website to BridgePay’s hosted payment page. The cardholder enters their data (Card Holder Data – CHD) into the payment page hosted by BridgePay.

Redirect Process

  1. The user browses the Merchant’s website to build a shopping cart. This website is hosted by a PCI Web Hosting facility which is a third-party hosting company.

  2. The Merchant's website issues a redirect to the BridgePay payment page, which is displayed within the cardholder’s web browser.

  3. The cardholder enters all CHD into the payment page. CHD is submitted directly to the BridgePay Gateway.

  4. The transaction result is returned to the specified URI. Does not contain CHD.

 

Merchant Impact

In this scenario, no CHD is submitted to the merchant, therefore the merchant has no cardholder data environment. The merchant may be eligible to validate PCI DSS compliance via self-assessment, SAQ A, which is applicable to outsourced e-commerce environments using redirection mechanisms to redirect customers to a PCI DSS compliant payment service provider.

While there is no CHD in the merchant environment, it is still important for merchants using a URL redirect to ensure their websites are secure. A compromised web server could mean the redirect was changed to a bogus payment site in order to steal cardholder data—e.g., man-in-the-middle attacks wherein the web server collects and sends data to malicious individuals.

⚡Merchants should consult their QSA for complete compliance requirements for their environment.
 

Summary

The redirect method is usually easier for merchants to secure, and typically results in fewer applicable PCI DSS requirements and lower risk of merchant systems being compromised. While this method may be the best option for merchants with limited security or technical ability, this option may not suit many merchants wishing to provide advanced features, or a more customizable customer payment experience.

Merchants should consider the benefits and costs of customization versus the increased need for security controls, and the resulting increase in security responsibility in conjunction with the applicable PCI DSS requirements.

iFrame Implementation

An iFrame (or Inline Frame) is a method of seamlessly embedding a web page within another web page—the iFrame becomes a frame for displaying another web page, in this case the payment form.

In e-commerce payments, the pages delivered during the checkout process would be supplied by the merchant's website, with an embedded iFrame supplied by BridgePay within that process. BridgePay’s iFrame receives all cardholder data entered by the cardholder.

iFrame Process

  1. The cardholder browses a Merchant's website, filling a shopping basket before reaching the payment page.

  2. The Merchant's shopping cart embeds an iFrame with the WebLINK payment form (received, in its entirety, from the BridgePay web server) to the cardholder’s web browser.

  3. The cardholder enters all CHD into this embedded iFrame. The CHD is submitted directly to the BridgePay Gateway.

  4. The transaction result is returned to a specified URL / results page. Does not contain CHD.

  5. Transaction Results are displayed to the cardholder.

iFrame Security Considerations

iFrames rely on a technique known as same-origin policy for secure operations. Enforcing origin policy in the http response headers helps prevent vulnerabilities such as Click-Jacking. Merchants need to ensure their website is configured to prevent framing of the payment iFrame by malicious code. There are couple of options when configuring origin policy:

  1. X-Frame-Options

“The X-Frame-Options HTTP response header can be used to indicate whether or not a browser should be allowed to render a page in a <frame>, <iframe> or <object>. Sites can use this to avoid clickjacking attacks, by ensuring that their content is not embedded into other sites.” “The added security is only provided if the user accessing the document is using a browser supporting X-Frame-Options.” –  Mozilla MDN web docs

 

2. Content Security Policy (CSP)

“The HTTP Content-Security-Policy response header allows web site administrators to control resources the user agent is allowed to load for a given page. With a few exceptions, policies mostly involve specifying server origins and script endpoints. This helps guard against cross- site scripting attacks (XSS).”

“The HTTP Content-Security-Policy (CSP) frame-ancestors directive specifies valid parents that may embed a page using <frame>, <iframe>, <object>, <embed>, or <applet>.” –  Mozilla MDN web docs

⚡It is recommended that both options be implemented since not all browsers support X-Frame-Options and CSP. Implementing both ensures the widest range
of browsers are protected.
 

Example Configuration – Web.Config

 

Example Configuration – Apache

Header set X-Frame-Options "ALLOW-FROM https://www.merchant-website.com/"" Header set Content-Secure-Policy frame-ancestors "https://www.merchant- http://website.com/ "

While no CHD is submitted to the merchant environment, merchants should consider additional security controls to reduce eCommerce risk even if not required by a PCI DSS SAQ. Server hardening, vulnerability management monitoring server / application activity are effective controls to reducerisk.

References

Mozilla – X-Frame-Options
Mozilla - Content Security Polity
Owasp – Clickjacking Defense

Merchant Impact

In this scenario, no CHD is submitted to the merchant, therefore the merchant has no cardholder data environment. The merchant may be eligible to validate PCI DSS compliance via self-assessment, SAQ A, which is applicable to outsourced e-commerce environments using iFrames to redirect customers to a PCI DSS compliant payment service provider.

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

 Summary 

The iFrame e-commerce method is usually easier for merchants to secure, and typically results in fewer applicable PCI DSS requirements. This method also will lower risk of merchant systems from being compromised, although not as low as the redirect method. However, this method also offers a better customer payment experience since the customer remains on the merchant website throughout the payment process. The inline payment form can provide a better “look and feel” than the redirect 
payment method, as the payment page can be customized to match the website design using WebLINK’s custom templates.

 

PCI DSS Documentation Requirements by Integration Type
 

Integration Method

PCI Type for eligible merchants

Guidance for merchants who are required to submit a Report on Compliance (ROC)

Number of questions under PCI 3.2 (not including any relevant appendices)

Redirect

SAQ A

Merchants may be required to submit a Report on Compliance (ROC) but may be able to use SAQ A as a reference to identify applicable PCI DSS requirements for that environment, providing the environment fully meets all eligibility criteria defined in that SAQ.

22

iFrame

SAQ A

*From the Best Practices for Securing E-commerce PCI DSS Information Supplement
Merchants should consult their QSA for complete compliance requirement for their environment.


Appendix

Flow Chart

 

 

reCAPTCHA

The following section describes the different reCAPTCHA implementations supported by the BridgePay WebLINK application. Each implementation has different advantages and disadvantages based on implementation type.

What is reCAPTCHA?

reCAPTCHA protects WebLINK hosted payment forms from SPAM and bot abuse. Using reCAPTCHA on the payment forms reduces the risk of fraudulent transactions from being processed through a merchant’s eCommerce site, by performing a Completely Automated Public Turing Test to Tell Computers and Humans Apart (CAPTCHA) test, which differentiates between humans and bots.

One of the most common CAPTCHA methods used today are forms that request you to enter a combination of letters and numbers that are displayed in a distorted format, and are often difficult to read.

BridgePay has adopted an alternative solution to secure its payment forms through Google’s implementation method, reCAPTCHA. During the payment process when the cardholder is ready to submit their purchase, the cardholder simply checks the box “I’m not a robot”, and the transaction is submitted. This is the default integration method.

 

 

Key Features of reCAPTCHA

  1. Provide merchants with a secure payment form with visible security.

  2. No disruption to the payment process.

  3. Block bots, spammers and automated scripts from using the payment form on the merchant’s site.

  4. Reduce fraudulent transactions.

Integration Types 

  1.  reCAPTCHA Widget – Displays the reCAPTCHA widget on the payment form. Users click the “I’m not a robot” check box during the payment process to complete the transaction submission.

 

2. Invisible reCAPTCHA – Invisible reCAPTCHA does not require the user to click on a check box. This method automatically binds the submit button on the payment page to submit the reCAPTCHA challenge.

 

Payment Form Templates

  1. Default Payment Form templates have the reCAPTCHA implemented by default and has the widget displayed to the user.

  2. Custom templates uploaded by integrators will need to add the necessary reCAPTCHA code to their template
     

Code Examples

You just need include the code below in your template and the BridgePay code will do the rest.  The examples below include code that will present the reCAPTCHA widget.

  1. Payment Form 

 

2. Tokenization Form

 

Default Payment Form

Code Samples

 
CompleteURL Sample

The following ASP code is an example of a CompleteURL page. This page receives a POST containing the result of the transaction, regardless of the transaction result. This page should display the results to the customer and perform any needed updates to the merchant’s system.
 


ReceiptURL Sample

The following ASP code is an example of a ReceiptURL page. This page receives a POST containing the result of a successful transaction in order to display a receipt.

The sample page displays the receipt.


 

The sample code processes the results and performs any needed updates to the merchant’s system.

 

iFrame Integration and Setup

The purpose of the Payment iFrame, is to allow a merchant to embed an HTML document within their checkout page that will collect user-entered payment data, and return the standard data. The token can be used for processing payments through WebLINK3. The Payment iFrame and the accompanying client library, allow the merchant to process card data in a PCI compliant manner, while also affording them greater programmatic control over the look and feel of the embedded input form.

PCI Scope

The Payment iFrame reduces PCI scope for the merchant by enabling them to outsource the capture of sensitive credit and debit card data. Bridgepay Gateway controls the data capture, sends it to our server for encryption, and returns an encrypted token to the merchant which can be used with WebLINK3 for further payment processing. With our solution, merchants never handle card data directly, putting their environment outside of PCI scope.


Payment iFrame Flow


Security and Safety Measures

The following security measures and restrictions must be taken into consideration when integrating with the WebLINK3 Payment iFrame.

 

Domain Whitelist

A whitelist of allowed domains is maintained in the Weblink Configuration page. The list is consulted before the iframe is loaded. The domain must first be added to the IFRAME DOMAINS section on their settings page. The input supports a comma separated list of domains, subdomains, and wildcard subdomains. Entries must exclude the protocol.

Sample entry:

bridgepay.com, www.mybridgepay.com, *.yourdomain.com If the iframe is loaded from a domain not included in this list, a security error message is presented.

 

iFrame Timeout

As the Payment iFrame contains sensitive card data, it is treated with high security standards. Part of that increased security includes a process whereby the HTML page will timeout after 10 minutes of inactivity. The reasoning behind this feature is to protect end users who may enter their card data on an open page, and then walk away leaving their computer unattended before submitting the page. By automatically redirecting the iFrame, we protect their card data from other users on the same computer.


iFrame Setup

Add host name

You need to add all of the domains that will integrate to WebLINK3. If the iframe is loaded from a domain not included in this list, the page will not display.

 

 


Templates

There are two categories of templates: merchant and custom. WebLINK invokes merchant templates by default if you don't pass a custom template ID with 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. 

 

WebLINK uses the following types of templates:

Customer Email
Customizes the display of the transaction receipt email sent to customer.

Merchant Email
Customizes the display of the transaction confirmation email sent to the merchant.

Payment Form
Configures the settings and display of the payment form.

Payment Form Split
Configures the settings and display of the payment form for split transactions.

Tokenization Form
Configures the settings and display of the tokenization form.

Receipt
Configures the settings and display of the transaction receipt.

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

 


Typical Flow

Credit Card

Sample Code

Request

Response

Transaction Response

Response Information

Resource Description
 

TransType

sale

PurchaseToken

0f4c78f2-a4c3-4cb5-88fc-611633a5ef90

Transaction_Token

1000000010261111

 


Acquire a Purchase Token

In order to acquire a purchase token, you must call the Action Service on the BridgePay gateway URL. The Action Service is a Microsoft Windows Communication Foundation (WCF) Service that is accessible via a Web Services Definition Language (WSDL) endpoint and implements a standard Simple Object Access Protocol (SOAP) interface. Using Microsoft’s Visual Studio, use these steps for creating a sample project to integrate to the service.


Create a Console App

In Visual Studio, create a new C# .Net Console App.


Add a Service Reference to the Action Service

After creating your project, right-click on the project and select “Add -> Service Reference…”

In the Add Service Reference window, enter the URL for the Action Service into the Address box and click “Go.” Set the namespace you want to use in your code in the Namespace box and click OK. The URL for the UAT version of the Action Service is:

https://www.bridgepaynetsecuretest.com/PaymentService/ActionService.svc

 


Write Code to Acquire a Purchase Token

With the Service Reference created, you are now ready to write the code that will call the Action Service to acquire a purchase token.

Add the following code to the Program.cs file:

 

  • The using statement instantiates the class for accessing the Action Service.

  • The first statement within the try block calls the AcquirePurchaseToken method with the defined parameters to acquire a purchase token.

  • After you get a Purchase Token, that Purchase Token is available for 15 minutes and can then be used in future calls to BridgeComm or WebLink 3.
     


Parameter Name

Description

Field Length

AcctType

The checking account type. C,S - Checking, Savings
 

50

BillTo Name

The full name associated to the customer's billing address.
 

150

BillTo Street

The customer's street billing address.
 

128

BillToCity

The customer's city billing address
 

50

BillToEmail

A comma delimited list of email addresses to send the customer receipt to.
 

100

BillToPhone

The customer's phone number associated with the billing address.
 

10-11

BillToState

The customer's state billing address.
 

2

BillToZip

The customer's zip code billing address.
 

15

CancelUrl

If provided, a cancel button will be rendered on the payment form that when clicked will re-direct to this url. Adding a space and then "confirm" will cause a confirmation dialog to appear before the end user is re-directed. i.e.
 

255

CompleteUrl

A url that will be posted to after a transaction regardless of approval. The results of this post if any will not be rendered back to the browser
 

255

Custom Data

Custom Data
 

255

CustomerAccountCode

Merchants created Customer Account Code.
 

 

Description

Description line displays above the total amount field. (Optional)
 

255

EmailFrom

The email address to use as the email from address for customer (BillToEmail) and merchant (Merchant Email) receipts.
 

100

EnableWallet

Check to Enable Wallet functionality. True or False.
 

5

FailUrl

A url that will be posted to after the payment form is submitted unsuccessfully. Various error information is posted to this url. Leaving this blank will cause WebLINK3 to simply show the payment form again with any response from the payment gateway
 

255

FeeAmount

Convenience Fee - The portion of the TotalAmt that equals the convenience fee
 

10,2

FeeDescription 

Convenience Fee - The description of the convenience fee.
 

255

InvoiceNum

Merchants created invoice number.
 

24

mode

PaymentForm|TokenizationForm - PaymentForm: Displays the payment form. TokenizationForm: Displays a form to capture credit card info returning a token.
 

Enumeration

MerchantEmail

A comma delimited list of email addresses to send the merchant receipt to
 

100

PaymentServerType

The type of payment server to interface to BPN: Set to BPN for general use
Set to BridgeComm when using Service Fees
 

Enumeration

PONum

Merchants created purchase order number.
 

24

Purchase Token

The purchase token to use for this transaction. Required to be used in place of Login/Password and is the preferred method of authentication.
 

36

ReceiptURL

A url that will be posted to after the payment form is submitted successfully. Leave this blank to let WebLINK3 display the receipt automatically.
 

255

RespondWithLastFailureOnly

Provide a non empty string here to indicate that only the last failure should be returned to the page at CompleteUrl.
 

1

ReturnFields

A comma delimited list of field names that will be posted to the success Url. If blank, all fields are returned.
 

255

ReturnReceiptUrl

If specified and receipt_url is NOT specified this is the url that will populate the return link (Click here - hyperlink at the bottom of the receipt) in the displayed receipt.
 

255

SessionTimeout

The amount of time in minutes before a user's session times out. Default is 10 minutes, minimum is 1 minute, maximum is 30 minutes.
 

integer

SoftwareVendor

The Software Vendor that will be passed through WebLINK3. 
Required - ex. Company name - software name - software version number
 

255

Style_Field_FontColor

The color to use for field input text on the Payment Form. The default value is “#000”.
 

7

Style_Field_FontSize

The size of the font to display for field input text on the Payment Form. The default value is “12”.
 

3

Style_FontFamily

The font family to use on the Payment Form. Can list one or more font names, separated by commas. The default value is “Verdana, Arial, Helvetica, sans-serif”.
 

100

Style_Form_BackgroundColor

The color to use for the Payment Form background color. The default value is “#FFF”.
 

7

Style_Heading_BackgroundColor

The background color for the heading sections of the Payment Form.
 

7

Style_Heading_FontColor

The color to use for heading text on the Payment Form. The default value is “#000”.
 

7

Style_Heading_FontSize

The size of the font to display for heading text on the Payment Form. The default value is “13”.
 

3

Style_Instruction_FontColor

The color to use for instruction text on the Payment Form. The default value is “#000”.
 

7

Style_Instruction_FontSize

The size of the font to display for instruction text on the Payment Form. The default value is “11”.
 

3

Style_Label_FontColor

The color to use for field label text on the Payment Form. The default value is “#000”.
 

7

Style_Label_FontSize

The size of the font to display for field label text on the Payment Form. The default value is “10”.
 

3

Style_Page_BackgroundColor

The color to use for the page background color. The default value is “#FFF”.
 

7

Style_Page_BackgroundImage

The URL to an image file to be included as the background image for the Payment Form.
 

255

SvcAmount

Service Fee - The service fee amount.
 

10,2

SvcDescription

Service Fee - A description of the service fee.
 

10,2

svclogin

Service Fee - User account for the user name associated with the service fee account. Used to acquire a purchase token for service fees.
 

56

svcpassword

Service Fee - User account for the user password associated with the service fee account. Used to acquire a purchase token for service fees.
 

56

svcPurchaseToken

Service Fee - Required pre-authentication token acquired for the Service Fee transaction. Provided in lieu of the svclogin and svcpassword.
 

36

The credit card CV number.

The credit card CV number.
 

4

Token

The credit card token used to process subsequent or recurring Sale transactions.
 

40

TotalAmt

The amount to charge for this transaction. Also required to acquire the purchase token.
 

10,2

TransCatCode

The transaction category code for this transaction. Supported values are: B (Bill Payment), R (Recurring), I (Installment), H (Healthcare).
 

1

TransIndustryType

The transaction industry type for this transaction. Valid values: EC, RE, DM, RS, LD, PT, WEB, TEL, PPD, CCD, POP.
 

3

TransSequenceNo

The transaction sequence number for this transaction. Required only for split transactions. Amount, PurchaseToken are required. Description and UserDefinedTransactionId are optional.
 

integer

TransType

The transaction type to perform. Sale|Return|Void| (Default is Sale).
 

10

UserDefinedTransactionId

An arbitrary transaction identifier that will be passed through WebLINK3. Useful for reconciling transactions in other systems, etc.
 

255

UseServerSidePostBacks

Provide a non empty string here to indicate that WebLINK3 should post back to ReceiptUrl and FailUrl from the server. This is more secure but only supports publicly available URLs.

1

 

 

Property of BridgePay Network Solution ©2024