Creating payment forms

Use these guidelines as you build the payment form you’ll use to collect payment details.

Your payment form must:

Check out our sample payment form and handler.

Requirements for credit card payment forms

For credit card payments, it’s important that you gather the appropriate cardholder details in your payment form. Cardholder details fall into one or more of the following categories:

Cardholder dataWhy collect it?
card numberRequired for successful transaction
card expirationRequired for successful transaction
card CVVRequired payment field for merchants; required payment field for partners. Collecting CVV helps prevent fraud and reduce the probability of chargebacks. If you don’t collect CVV and the cardholder disputes a charge, the chargeback committee will likely rule in favor of the cardholder and return funds.
cardholder nameOptional. If you’re using an external system to manage customers, be sure to map the “name” field in that system to the name property on card or bank objects in the AffiniPay system; otherwise, transactions will show up in the AffiniPay system without a name.
emailOptional
address 1Required payment field for merchants. If you don’t submit this information, you may not get the best processing rate.
address 2Optional
cityOptional
stateOptional
postal codeRequired payment field for merchants; required payment field for partners (for manually-keyed transactions). If you don’t submit this information, you may not get the best processing rate.
countryOptional
phoneOptional

Requirements for eCheck payment forms

Electronic check (eCheck) payments move funds electronically between banks using routing and account numbers.

Before a merchant can take eCheck payments in your application, they must be eCheck-enabled in LawPay/CPACharge/AffiniPay. To verify that a merchant can take eCheck payments, send a GET request to the https://api.chargeio.com/api/v1/merchant endpoint.

For eCheck payments, your form must include:

By clicking “Submit Payment”, I am authorizing <Merchant Name> to initiate a single or recurring ACH/electronic debit in the amount indicated from the bank account I designed above. I understand that this Authorization will remain in full force and effect until the transaction is cancelled by me by contacting <Merchant Name>, or the ACH/electronic debit is processed from the designed account. I certify that (1) I am authorized to debit the bank account above and (2) that the ACH/electronic payment I am authorizing complies with all applicable laws.

Secure payment details with tokens

To secure sensitive payment details, exchange them for a non-sensitive one-time payment token and then use the one-time token to make a payment.

To enable payments on a web page:

  1. Include the tokenization library. Add the following script include to your web page:
    <script type="text/javascript" src="https://api.chargeio.com/assets/api/v1/chargeio.min.js"></script>

  2. Initialize the tokenization library. The library needs to know the merchant’s identity to handle requests from your payment form. Provide the merchant’s public key, which is safe to expose in web pages (as opposed to secret keys, which must be safeguarded).
    <script type="text/javascript">ChargeIO.init({public_key: 'your merchant public key'});</script>

    Note: You must add this <script> element after the script include element from the previous step.

  3. Define a JavaScript function (event handler) in the page to collect the payment details from the payment form, pass them to the create_token() function, and handle the tokenization response.
  4. Connect the JavaScript function to the payment form’s submit button to send the payment details to the AffiniPay Payment Gateway.

The event handler must:

Sample payment form

The following HTML is a basic payment form example based on the Bootstrap front-end framework.

<div class="row">
  <h2>Enter your payment information:</h2>

  <div id="messages" class="alert alert-danger" style="display: none">
    <ul></ul>
  </div>

  <form>
    <div class="form-group">
      <label>Name</label>
      <input type="text" name="name">
    </div>
    <div class="form-group">
      <label>Card Number</label>
      <input type="text" name="number">
    </div>
    <div class="form-group">
      <label>CVV</label>
      <input type="text" name="cvv">
    </div>
    <div class="form-group">
      <label>Exp Month</label>
      <input type="text" name="exp_month">
    </div>
    <div class="form-group">
      <label>Exp Year</label>
      <input type="text" name="exp_year">
    </div>
    <div class="form-group">
      <label>Zip Code</label>
      <input type="text" name="postal_code">
    </div>

    <button type="submit" id="pay" disabled>Submit</button>
  </form>
</div>

Sample event handler

Here’s an sample payment form event handler that works with the sample payment form.

In this example, we’re binding the event handler to the button with ID “pay” click event. The variable you pass this function is composed of the payment form’s field values. The function that sets this variable assumes your form field names match the token API properties.

01 <script type="text/javascript" src="https://api.affinipay.com/assets/api/v1/chargeio.min.js"></script>
02 <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
03 <script type="text/javascript">
04  ChargeIO.init({ public_key: 'your merchant public key' });
05
06   function processErrorMessages(messages) {
07     var msgList = $('#messages ul');
08     $(msgList).empty();
09     $.each(messages, function(index, item) {
10       $(msgList).append("<li>" + item.message + "</li>");
11     });
12	  
13     $('#messages').show();
14     $('#pay').prop("disabled", false);
15   }
16
17   ChargeIO.ready(function() {
18     $('#pay').prop("disabled", false);
19     $('#pay').click(function(event) {
20       event.preventDefault();
21       $('#pay').prop("disabled", true);
22       var amount = parseInt($('#total').text().replace(/\D/g,''));
23       var paymentJson = ChargeIO.payment_params($('form'));
24       ChargeIO.create_token(paymentJson, function(token) {
25         $.post('<add your URL here>', { 'amount': amount, 'token_id': token.id }).done(function(data) {
26           if (data.messages) {
27             processErrorMessages(data.messages);
28           }
29           else {
30             window.location = '<add your URL here>';
31           }
32         }).fail(function(xhr) {
33           processErrorMessages([ { "message": "An unexpected error occurred" } ]);
34         });
35       });
36     });
37   });
38 </script>

Code Comments

Next step

Once you have a payment form, you can create a charge.