How To Configure and Use Payment Forms

Overview

Payment forms are used to enable the using of BillingPlatform payment objects to obtain information directly from a customer's host website and store them directly into BillingPlatform to minimize the risk of PCI compliance on the part of the customer/owner of the host site.

The following information is needed before BillingPlatform can be configured to enable this feature:

  1. Payment options - The payment options that the host website will need to support. Any options available in BillingPlatform (e.g. Credit Card, ACH, etc.) can be used by the host website.
  2. Success URL - Redirect URL that BillingPlatform will use when a payment process succeeds.
  3. Failure URL - Redirect URL that BillingPlatform will use if the payment process fails.

In order for the the payment form to be configured and enabled in the host website, the following are needed:

  1. Knowledge in web scripting (e.g. javascript).
  2. CSS knowledge for updating the look and feel of the payment form and make it consistent with the look and feel of the host website.

Procedures

Configure BillingPlatform

1. Go to the Payment Form configuration page.

Go to Setup > Develop > Payment Form. The payment form profiles are displayed. If there is only one profile available, it will automatically be opened.

2. Create a new Payment Form profile

Click New to create a new profile or click the Edit link beside an existing profile to update it. The payment form profile details page is displayed.

Fill in the necessary configuration parameters depending on the behavior that is expected from the payment form.

Field Definition

Table 1
Field Definition
Status Indicates if the profile is active or inactive. Setting it to inactive will return an error when the host website tries to use the profile.
Payment Option

Checkboxes that allows for the selection of one or more payment types to be supported by the payment form. The standard options are:

  • ACH
  • CREDIT CARD
User for Login A picklist of all the available billing application users in the system. Select the appropriate login that will be used when processing payments from the host website.
Success URL URL where a redirect will be made when a payment is successful. This will be passed to the callback script that will be configured later during the widget setup activity.
Failure URL URL where a redirect will be made when a payment fails. This will be passed to the callback script that will be configured later during the widget setup activity.
Recreate Secret Key?

Available only when updating an existing profile. This forces the regenreation of a new secret key.

Note: The host website's configuration will need to be updated with the new key if this field is enabled and the profile saved.

Allow Update Indicates if updating payment data for the account in BillingPlatform will be allowed. Enabling this will allow the payment details to be updated in the account's billing profile for future recurring payments that are initiated by BillingPlatform.
Account Identifier

Indicates the key/field that will be used to determine the account within BillingPlatform that the payment will be associated with. Common fields for this are:

  • Account record ID.
  • Billing Profile record ID.

Any custom fields under the Account entity that is configured to be an external key field.

Additional Fields

Additional fields that need to have information captured when making payments can be added here. These are not necessarily used for payments but may be used to update other Account-related fields.

The table can be filled up using the field definitions below:

Field Definition
Field Field that will be made available and can be displayed on the payment form.
Access Level

Access permission of the field. Available options are:

  • READ - Information will only be displayed.
  • EDIT - Information can be displayed and updated. Updates will be saved in the appropriate record in BillingPlatform.
Order

Indicates the order where the field appears on the payment form.

 3. Save the changes

Click Submit to save the changes to the profile. At this point, the secret key is generated and made available on the UI.

Configure the Host website to use the payment form

As mentioned above, knowledge in web scripting is needed in order to add the payment form widgets as well as configure the different parameters in order for the host's webpage to communicate with BillingPlatform's payment form. The following table needs to be defined as part of the options block when initializing and installing the payment form widget.

Term Definition
<application_url>

This is the URL of the BillingPlatform org of the customer.

Example: https://sandbox.billingplatform.com/your_org/

appId

This is the payment form profile Id in BillingPlatform that was created in the previous section.

accountId

Identifier of the account in BillingPlatform where the payment will be made against. This is equivalent to the value of the field defined in the Account Identifier field of the BillingPlatform payment form configuration page.

token

Random string used as token. This is related to the signature that is generated by the host. In the same manner, this is generated by the host.

signature

Signature to be used with the payment page. Refer to the Signature Generation section for more information.

baseUri

Combination of the baseUrl value and the payment form widget's path.

initParams

Optional parameter. The supported options are:

  • inheritCss - Boolean value that instructs the widget to inherit the styles of the host's page.
accountSectionTitle

Optional parameter. This is the alternative section name to replace "Account Details". Otherwise, "Account Details" will be used as the default label.

paymentSectionTitle Optional parameter. This is the alternative section name to replace "Payment Details". Otherwise, "Payment Details" will be used as the default label.

The widget will need to be added into the source code of the webpage that will host the payment form. For instance:

<script src="<application_url>/js/components/BP.js"></script>

This is then followed by the invoking of the payment form along with passing the account-related parameters

$(document).ready(function () {
       var baseUrl = ;
       var options = {
           appId: "101",
           accountId: "10201",
           token:"1429717973",
           signature:"27IXguSAg6B9HjNHG8tpMJjObPSHLic3RQLP5manml5Yyfab8TzPhgTmTaifKDzRe
			ZkAzLUll67hsCPaVxAMwgWVO6ZKlFZ8ZPJTTVHjjMgUsR27jLx6rvIRuHQrh4qV",
           expires:"300",
           initParams: {
               inheritCss: true
           },
           baseUri: baseUrl+"/pciCompliance.jsp"
       };
       BP.init(options);
	...

We then make an ajax request to get the field data from the BillingPlatform application.

			...
        	$.ajax({
            	url: baseUrl+"/fields",
            	data:{appid:options.appId,accountId:options.accountId,locale:options.language},
            	dataType: 'json',
            	crossDomain: true,
            	success: function (res) {
                	$('#test').removeAttr("hidden");
                	console.log(res);
                	BP.fields = res;
			BP.createIframe(document.getElementById("payment_form"));
            	}
        	});
    	})

The BP.createIframe(element) line creates the actual iframe. Note that the parameter of this BP.createIframe function is the DOM element in where the iframe will be created.

Signature Generation

Generation of the signature must conform with the OAuth 1.0 specification (http://oauth.net/core/1.0). To generate a valid signature, the following steps can be performed.

  1. Build query style parameters with values:
    • accountId
    • appId
    • expires
    • timestamp
    • token

Note that these parameters are sorted in lexicographic order. Because of this, the result we will get are strings of pair.

Example:

    • accountId=10205
    • appId=101
    • expires=300
    • timestamp=1429717973
    • token=1429717973skuej238jsh2
  1. Concatenate the parameters from step 1 using the & symbol.

Example:

accountId=10205&appId=101&expires=300&timestamp=1429717973&token=1429717973skuej238jsh2

  1. Perform URL encoding of the value obtained from step 2.

Example:

accountId%3D10205%26appId%3D101%26expires%3D300%26timestamp%3D1429717973%26token%3D1429717973skuej238jsh2

  1. Perform URL encoding of the baseUri parameter. Refer to the table in the previous section on how this is obtained.

Example:

If the baseUri value is https://sandbox.billingplatform.com/your_org/pciCompliance.jsp, then the encoded value will be https%3A%2F%2Fsandbox.billingplatform.com%2Fyour_org%2FpciCompliance.jsp.

  1. Concatenate the HTTP method, encoded baseUri and encoded parameters using & symbol.

Example:

GET&https%3A%2F%2Fsandbox.billingplatform.com%2Fyour_org%2FpciCompliance.jsp&accountId%3D10205%26appId%3D101%26expires%3D300%26timestamp%3D1429717973%26token%3D1429717973skuej238jsh2

  1. Calculate HMAC-SHA256 of concatenated string using secret key given in Billing Platform Application configuration. Encode this digest value as base64 string.

Example:

If the secret key that was given in the BillingPlatform configuration is '1234512345', the calculation can be done using the following:

HMAC-SHA256(1234512345, GET&https%3A%2F%2Fsandbox.billingplatform.com%2Fyour_org%2FpciCompliance.jsp&accountId%3D10205%26appId%3D101%26expires%3D300%26timestamp%3D1429717973%26token%3D1429717973skuej238jsh2)

This will yield a result similar to this: ZjU4OWNlNGE5NzMxNmU3MzY4MmJjNTAzNDNkMjQzMTVhMzRjMDRlOWQ3YzczMmY4NTA3MWJmMTYwZjliNzdlOAo=

This is the signature that will be used when installing the payment form onto the host page.

Important: The ability to generate this signature must be done everytime the payment page is invoked. As such, it is recommended that an HMAC function library be used and can be invoked automatically before requesting for the BillingPlatform payment page to be used by the website.

Update the look and feel of the payment form

Using CSS, the look and feel of the host page and embedded page can be changed to confirm with the overall design structure of the host's website. The following sample customization can be used as reference:

Host Page Look and Feel

This covers the host page, or the website that where the payment form will sit on top of. This is NOT the iframe/embedded page.

<div id="paymentModal" class="modal fade" aria-hidden="false">
 <div class="modal-dialog">
  <div class="modal-content">
   <div class="modal-header">
    <button type="button" class="close" data-dismiss="modal" aria-hidden="true">×</button>
    <div class="header">
     <img src="images/logo.png"/>
    </div>
    <h4 class="modal-title">Confirmation</h4>
    <input type="hidden" name="option" value="" id="btn-input">
     <div id="alert" class="alert" style="display:none" role="alert"/>
     <div class="radio-buttons">
      <div class="radio">
       <label>
        <input id="CC" type="radio" name="optradio" checked=""
               onclick="BP.ccForm=true;BP.ahcForm=false;BP.drawForm();">CC Form</label>
      </div>
      <div class="radio">
       <label>
        <input id="ACH" type="radio" name="optradio" 
               onclick="BP.ccForm=false;BP.ahcForm=true;BP.drawForm();">ACH Form</label>
      </div>
     </div>
   </div>
   <div class="modal-body">
    <div id="pci_compliance" class="modal-form" style="width: auto;">
     <iframe id="bp_pci_compliance_iframe" overflow="visible" scrolling="no" frameborder="0" 
             allowtransparency="true" class="billing_iframe" width="100%" height="100%"/>
    </div>
   </div>
   <div class="modal-footer">
    <button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
    <button id="apply" type="button" class="btn btn-primary" onclick="BP.submitForm();">Apply</button>
   </div>
  </div>
 </div>
</div>

The structure of the page can also be updated by inheriting the CSS of the hosting page.

Embedded Page Look and Feel

For the embedded page/iframe where the actual data fields are located in will use the following structure:

<form name="BPpaymentForm" id="BPpaymentForm">
  <div class="clear">&nbsp;</div>
  <div id="account-section" class="section-title">
    <span>Account Details</span>
  </div>
  <div name="Name" class="row field-size">
    <label for="Name">Test</label>
    <input type="text" name="Name">
   <div name="NameError"></div>
  </div>
  <div id="payment-section" class="section-title">
   <span>Payment Details</span>
  </div>
  <div name="Amount" class="row field-size">
    <label for="Amount">Payment Amount</label>
    <input type="text" name="Amount">
    <div name="AmountError"></div>
  </div>
</form>

Putting this together into an example embedded page code with actual values:

<form name="BPpaymentForm" id="BPpaymentForm" action="javascript:void(0)">
 <div class="clear">&nbsp;</div>
 <div id="account-section" class="section-title">
   <span>Account Details</span>
 </div>
 <div name="Name" class="row field-size">
   <label for="Name">Test</label>
   <input type="text" group="ACCOUNT_FIELD" entity="ACCOUNT" id="1381" rowid="undefined"
          name="Name">
   <div iderror="1381" name="NameError"></div>
 </div>
 <div name="Id" class="row field-size">
   <label for="Id">Company ID</label>
   <input type="text" group="ACCOUNT_FIELD" entity="ACCOUNT" id="325" rowid="undefined" name="Id"
          readonly="">
   <div iderror="325" name="IdError"></div>
 </div>
 <div name="AccountBalance" class="row field-size">
   <label for="AccountBalance">Balance</label>
   <input type="text" group="ACCOUNT_FIELD" entity="BILLING_PROFILE" id="5091" rowid="undefined"
          name="AccountBalance" readonly="">
   <div iderror="5091" name="AccountBalanceError"></div>
 </div>
 <div name="BillTo" class="row field-size">
   <label for="BillTo">Bill To</label>
   <input type="text" group="ACCOUNT_FIELD" entity="BILLING_PROFILE" id="1411" rowid="undefined"
          name="BillTo" readonly="">
   <div iderror="1411" name="BillToError"></div>
 </div>
 <div name="Id" class="row field-size">
   <label for="Id">Account Number</label>
   <input type="text" group="ACCOUNT_FIELD" entity="BILLING_PROFILE" id="1513" rowid="undefined"
          name="Id">
   <div iderror="1513" name="IdError"></div>
 </div>
 <div class="clear">&nbsp;</div>
 <div id="payment-section" class="section-title">
   <span>Payment Details</span>
 </div>
 <div name="Amount" class="row field-size">
   <label for="Amount">Payment Amount</label>
   <input type="text" group="CC_FIELD" entity="PAYMENT" id="1426" rowid="undefined" name="Amount"
          readonly="">
   <div iderror="1426" name="AmountError"></div>
 </div>
 <div name="CreditCardNumber" class="row field-size">
   <label for="CreditCardNumber">Credit Card Number</label>
   <input type="text" group="CC_FIELD" entity="BILLING_PROFILE" id="1417" rowid="undefined"
          name="CreditCardNumber">
   <div iderror="1417" name="CreditCardNumberError"></div>
 </div>
 <div name="CreditCardExpDate" class="row field-size">
   <label for="CreditCardExpDate">Credit Card Exp Date (MM/YYYY)</label>
   <input type="text" group="CC_FIELD" entity="BILLING_PROFILE" id="1414" rowid="undefined"
          name="CreditCardExpDate">
   <div iderror="1414" name="CreditCardExpDateError"></div>
 </div>
 <div name="CreditCardCCV" class="row field-size">
   <label for="CreditCardCCV">Credit Card CCV</label>
   <input type="text" group="CC_FIELD" entity="BILLING_PROFILE" id="1418" rowid="undefined"
          name="CreditCardCCV">
   <div iderror="1418" name="CreditCardCCVError"></div>
 </div>
 <div name="CreditCardName" class="row field-size">
   <label for="CreditCardName">Card Holder Name</label>
   <input type="text" group="CC_FIELD" entity="BILLING_PROFILE" id="1416" rowid="undefined"
          name="CreditCardName">
   <div iderror="1416" name="CreditCardNameError"></div>
 </div>
 <div name="Address1" class="row field-size">
   <label for="Address1">Addr1</label>
   <input type="text" group="CC_FIELD" entity="BILLING_PROFILE" id="1395" rowid="undefined"
          name="Address1">
   <div iderror="1395" name="Address1Error"></div>
 </div>
 <div name="Country" class="row field-size">
   <label for="Country">Country</label>
   <input type="text" group="CC_FIELD" entity="BILLING_PROFILE" id="1397" rowid="undefined"
          name="Country">
   <div iderror="1397" name="CountryError"></div>
 </div>
 <div name="City" class="row field-size">
   <label for="City">City</label>
   <input type="text" group="CC_FIELD" entity="BILLING_PROFILE" id="1398" rowid="undefined"
          name="City">
   <div iderror="1398" name="CityError"></div>
 </div>
 <div name="State" class="row field-size">
   <label for="State">State</label>
   <input type="text" group="CC_FIELD" entity="BILLING_PROFILE" id="1399" rowid="undefined"
          name="State">
   <div iderror="1399" name="StateError"></div>
 </div>
 <div name="Zip" class="row field-size">
   <label for="Zip">Zip</label>
   <input type="text" group="CC_FIELD" entity="BILLING_PROFILE" id="1400" rowid="undefined"
          name="Zip">
   <div iderror="1400" name="ZipError"></div>
 </div>
</form>

Updating the CSS

The appearance of the embedded structure can be further modified by applying CSS to the elements as needed. By inheriting the CSS from the host page, the elements of the embedded page can be modified to change their appearances as well. For example, using the CSS below:

.section-title {
       background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyBpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMC1jMDYwIDYxLjEzNDc3NywgMjAxMC8wMi8xMi0xNzozMjowMCAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENTNSBXaW5kb3dzIiB4bXBNTTpJbnN0YW5jZUlEPSJ4bXAuaWlkOkUwNDMyM0U3RkE0MDExRTRBNkJCRDFGOTBFODMyRDFBIiB4bXBNTTpEb2N1bWVudElEPSJ4bXAuZGlkOkUwNDMyM0U4RkE0MDExRTRBNkJCRDFGOTBFODMyRDFBIj4gPHhtcE1NOkRlcml2ZWRGcm9tIHN0UmVmOmluc3RhbmNlSUQ9InhtcC5paWQ6RTA0MzIzRTVGQTQwMTFFNEE2QkJEMUY5MEU4MzJEMUEiIHN0UmVmOmRvY3VtZW50SUQ9InhtcC5kaWQ6RTA0MzIzRTZGQTQwMTFFNEE2QkJEMUY5MEU4MzJEMUEiLz4gPC9yZGY6RGVzY3JpcHRpb24+IDwvcmRmOlJERj4gPC94OnhtcG1ldGE+IDw/eHBhY2tldCBlbmQ9InIiPz6tF12mAAAAD0lEQVR42mJYvnw5QIABAAPuAfYgbRcMAAAAAElFTkSuQmCC');
       background-position:center center;
       background-repeat: repeat-x;
       margin:5px 0 8px;
       clear:both;
       color:#e0e4ee;
}

.section-title span {
       background-color:#222b43;
       padding:4px 8px;
       color:#dde0e9;
       border-radius:3px 3px 3px 3px;
}

This CSS can transform the Title section as:

From To

Another example but this time for form fields. The following CSS

div.row {
 padding: 0 0 0 0;
 margin:0;
}

div.field-size {
       width:47%;
       float:left;
       margin-right:3%
}

div.field-size input, div.field-size textarea{
}

div.row label {
       margin: 0;padding: 0;
       display: block;
       font-size: 90%;
       padding-top: .2em;
       width: 100%;
       text-align: left;
       float: left;
       line-height:20px;
       font-weight: bold;
}

div.row input,div.row textarea {
       padding: 0;
       font-size: 100%;
       width:100%;
       float: left;
}

This transforms the following form:

From To

Payment Form Sections

By default, the payment form is composed of two sections. One for Account data and the other for Payment data. The headings for these two sections can be updated/changed by overriding the following attributes to the options object when initializing the payment form widget:

accountSectionTitle: "Account Details",
paymentSectionTitle: "Payment Details",

Error Messages

The payment form provides the ability to customize error messages due to user inputs that are readily available for consumption from the platform. This is done by adding the errorMessages object when defining the options block for the widget. This provides a mapping between the system error message that is returned by BillingPlatform, the field that caused the error and the custom/overridden error message that is displayed on the host's webpage. For example, include the following lines as part of the errorMessages block when the messages need to be overridden to be more user friendly:

errorMessages: {
    "BAD_TRANSACTION_STATUS Missing/non mapped required field Name": { errorSource: "Name", errorMessage: "Please enter your name" },
    "BAD_TRANSACTION_STATUS Missing/non mapped required field BillTo": { errorSource: "BillTo", errorMessage: "Please enter bill recepient" },
    "BAD_TRANSACTION_STATUS Missing/non mapped required field Amount": { errorSource: "Amount", errorMessage: "Please enter payment amount" }
}

Common error messages that may need to be overridden to be more user friendly are:

errorMessages: {
	"BAD_TRANSACTION_STATUS Missing/non mapped required field Name": { errorSource: "Name", errorMessage: "Please enter your name" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field BillTo": { errorSource: "BillTo", errorMessage: "Please enter bill recepient" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field Amount": { errorSource: "Amount", errorMessage: "Please enter payment amount" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field AchBankAbaCode": { errorSource: "AchBankAbaCode", errorMessage: "Please enter ACH bank ABA code" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field AchBankAcctNum": { errorSource: "AchBankAcctNum", errorMessage: "Please enter ACH bank account number" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field AchBankAcctType": { errorSource: "AchBankAcctType", errorMessage: "Please enter ACH bank account type" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field AchBankName": { errorSource: "AchBankName", errorMessage: "Please enter ACH bank name" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field AchBankAcctName": { errorSource: "AchBankAcctName", errorMessage: "Please enter ACH bank account name" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field AchEcheckType": { errorSource: "AchEcheckType", errorMessage: "Please enter ACH ECheck type" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field CreditCardNumber": { errorSource: "CreditCardNumber", errorMessage: "Please enter credit card number" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field CreditCardExpDate": { errorSource: "CreditCardExpDate", errorMessage: "Please enter credit card expiration date" },
	 "BAD_TRANSACTION_STATUS Maximum field length exceeded for field CreditCardExpDate": { errorSource: "CreditCardExpDate", errorMessage: "Credit card expiration date length exceeded" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field CreditCardCCV": { errorSource: "CreditCardCCV", errorMessage: "Please enter credit card CCV" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field CreditCardName": { errorSource: "CreditCardName", errorMessage: "Please enter credit card holder name" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field Address1": { errorSource: "Address1", errorMessage: "Please enter your address" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field Country": { errorSource: "Country", errorMessage: "Please enter your country" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field City": { errorSource: "City", errorMessage: "Please enter your city" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field State": { errorSource: "State", errorMessage: "Please enter your state" },
	 "BAD_TRANSACTION_STATUS Missing/non mapped required field Zip": { errorSource: "Zip", errorMessage: "Please enter your zip" },
	 "UNKNOWN_EXCEPTION a non-numeric character was found where a numeric was expected": { errorMessage: "Please provide numeric value" }, 
	 "UNKNOWN_EXCEPTION a non-numeric character was found where a numeric was expected\nORA-06512: ": { errorMessage: "Please provide numeric value" },
	 "UNKNOWN_EXCEPTION not a valid month": { errorSource: "CreditCardExpDate", errorMessage: "Please enter valid month" },
	 "UNKNOWN_EXCEPTION not a valid month\nORA-06512: ": { errorSource: "CreditCardExpDate", errorMessage: "Please enter valid month" },
	 "UNKNOWN_EXCEPTION (full) year must be between -4713 and +9999, and not be 0": { errorSource: "CreditCardExpDate", errorMessage: "Please enter valid year" },
	 "UNKNOWN_EXCEPTION (full) year must be between -4713 and +9999, and not be 0\nORA-06512: ": { errorSource: "CreditCardExpDate", errorMessage: "Please enter valid year" },
	 "Invalid account number": { errorSource: "CreditCardNumber", errorMessage: "Please enter valid credit card number" }
 }

Data Customization

Using javascript, web developers have the ability to customize the data that is displayed to the end-user when serving the BillingPlatform payment form. This is done by modifying the data structure of the fields that are received from BillingPlatform.

During widget initialization, an ajax request was created to pull the data from BillignPlatform

$.ajax({
	url: baseUrl+"/fields",
	data:{appid:options.appId,accountId:options.accountId,locale:options.language},
	dataType: 'json',
	crossDomain: true,
	success: function (res) {
		$('#test').removeAttr("hidden");
		console.log(res);
		BP.fields = res;
		BP.createIframe(document.getElementById("payment_form"));
	}
});

Upon receiving the successful response from BillingPlatform, it can then be modified prior to the creation of the iframe. To illustrate, here is an example of an incoming response from BillingPlatform:

{
	"successUrl": "http://www.google.com",
	"failureUrl": "http://www.yahoo.com",
	"allowUpdate": true,
	"ccFields": [{
    	"id": "1426",
    	"name": "Amount",
    	"value": null,
    	"label": "Payment Amount",
    	"displayMethod": null,
    	"fieldGroup": "CC_FIELD",
    	"required": true
	}, {
    	"id": "1417",
    	"name": "CreditCardNumber",
    	"value": "************1111",
    	"label": "Credit Card Number",
    	"displayMethod": null,
    	"fieldGroup": "CC_FIELD",
    	"required": true
	}, {
    	"id": "1414",
    	"name": "CreditCardExpDate",
    	"value": "12/2018",
    	"label": "Credit Card Exp Date (MM/YYYY)",
    	"displayMethod": null,
    	"fieldGroup": "CC_FIELD",
    	"required": true
	}, {
    	"id": "1418",
    	"name": "CreditCardCCV",
    	"value": "****",
    	"label": "Credit Card CCV",
    	"displayMethod": null,
    	"fieldGroup": "CC_FIELD",
    	"required": true
	}, {
    	"id": "1416",
    	"name": "CreditCardName",
    	"value": "TestHolder",
    	"label": "Card Holder Name",
    	"displayMethod": null,
    	"fieldGroup": "CC_FIELD",
    	"required": true
	}, {
    	"id": "1395",
    	"name": "Address1",
    	"value": "7116 Diamond Tail Drive",
    	"label": "Addr1",
    	"displayMethod": null,
    	"fieldGroup": "CC_FIELD",
    	"required": true
	}, {
    	"id": "1397",
    	"name": "Country",
    	"value": "USA",
    	"label": "Country",
    	"displayMethod": null,
    	"fieldGroup": "CC_FIELD",
    	"required": true
	}, {
    	"id": "1398",
    	"name": "City",
    	"value": "Fort Collins",
    	"label": "City",
    	"displayMethod": null,
    	"fieldGroup": "CC_FIELD",
    	"required": true
	}, {
    	"id": "1399",
    	"name": "State",
    	"value": "COfgfgfg",
    	"label": "State",
    	"displayMethod": null,
    	"fieldGroup": "CC_FIELD",
    	"required": false
	}, {
    	"id": "1400",
    	"name": "Zip",
    	"value": "11111",
    	"label": "Zip",
    	"displayMethod": null,
    	"fieldGroup": "CC_FIELD",
    	"required": true
	}],
	"achFields": [{
    	"id": "1426",
    	"name": "Amount",
    	"value": null,
    	"label": "Payment Amount",
    	"displayMethod": null,
    	"fieldGroup": "ACH_FIELD",
    	"required": true
	}, {
    	"id": "1703",
    	"name": "AchBankAbaCode",
    	"value": null,
    	"label": "Routing Number",
    	"displayMethod": null,
    	"fieldGroup": "ACH_FIELD",
    	"required": true
	}, {
    	"id": "1704",
    	"name": "AchBankAcctNum",
    	"value": null,
    	"label": "Account Ledger Id",
    	"displayMethod": null,
    	"fieldGroup": "ACH_FIELD",
    	"required": true
	}, {
    	"id": "1705",
    	"name": "AchBankAcctType",
    	"value": null,
    	"label": "Account Type",
    	"displayMethod": null,
    	"fieldGroup": "ACH_FIELD",
    	"required": true
	}, {
    	"id": "1706",
    	"name": "AchBankName",
    	"value": null,
    	"label": "Bank Name",
    	"displayMethod": null,
    	"fieldGroup": "ACH_FIELD",
    	"required": true
	}, {
    	"id": "1707",
    	"name": "AchBankAcctName",
    	"value": null,
    	"label": "Name on Account",
    	"displayMethod": null,
    	"fieldGroup": "ACH_FIELD",
    	"required": true
	}, {
    	"id": "1708",
    	"name": "AchEcheckType",
    	"value": null,
    	"label": "ACH Echeck Type",
    	"displayMethod": null,
    	"fieldGroup": "ACH_FIELD",
    	"required": false
	}],
	"accountFields": [{
    	"id": "1381",
    	"name": "Name",
    	"value": "Blue Moon -- ATT",
    	"label": "Test",
    	"displayMethod": "EDIT",
    	"fieldGroup": "ACCOUNT_FIELD",
    	"required": false
	}, {
    	"id": "325",
    	"name": "Id",
    	"value": "10205",
    	"label": "Company ID",
    	"displayMethod": "READ",
    	"fieldGroup": "ACCOUNT_FIELD",
    	"required": false
	}, {
    	"id": "5091",
    	"name": "AccountBalance",
    	"value": "0.00",
    	"label": "Balance",
    	"displayMethod": "READ",
    	"fieldGroup": "ACCOUNT_FIELD",
    	"required": false
	}, {
    	"id": "1411",
    	"name": "BillTo",
    	"type": "TEXT",
    	"value": "Jeremy Johnson",
    	"label": "Bill To",
    	"displayMethod": "READ",
    	"fieldGroup": "ACCOUNT_FIELD",
    	"required": false
	}, {
    	"id": "1513",
    	"name": "Id",
    	"value": "40973",
    	"label": "Account Number",
    	"displayMethod": "EDIT",
    	"fieldGroup": "ACCOUNT_FIELD",
    	"required": false
	}]
}

Response Payload Definition

Field Description/Function
successUrl The URL that was set during the configuration of the payment form where the user will be redirected when a payment is processed successfully.
failureUrl The URL that was set during the configuration of the payment form where the user will be redirected when the payment fails.
allowUpdate Indicates if the data can be updated based on the configuration.
ccFields Array of fields that are used for processing credit card payments.
achFields Array of fields that are used for processing ACH payments.
accountFields Array of fields containing information on the account.
Field Elements
Field Description
id Internal field identifier.
name Name of the entity field.
value Value of the entity field.
label Display label/title of the entity field.
displayMethod

Indicates if the field is read-only or editable. Valid values are:

  • null - Editable
  • READ - Read-only
fieldGroup

Indicates the group that the field belongs to. Valid values are:

  • CC_FIELD
  • ACH_FIELD
  • ACCOUNT_FIELD
required

Indicates if the field is required for payment or not. Valid values are:

  • true
  • false

Let's say that we want to set the credit card Payment Amount field to the value of the Account Balance value and make the field read-only, the following Java code can be used:

BP.fields = res;
BP.fields.allowUpdate = true;
var balance = _(BP.fields.accountFields)
	   .where({ 'name' : 'AccountBalance' })
	   .pluck('value')
	   .first();
var paymentAmount = balance > 0 ? 0 : 0 - balance;
_(BP.fields.ccFields)
	   .concat(BP.fields.achFields)
	   .where({ 'name': 'Amount' })
	   .forEach(function(field) {
		   field.value = paymentAmount;
		   field.displayMethod = 'READ';
	   })
	   .commit();

At this point, the data can now be served and rendered on the web page.

Related Topics

Have more questions? Submit a request

Comments

Powered by Zendesk