Creating payment forms
Use these guidelines as you build the payment form you’ll use to collect payment details.
Your payment form must:
- Gather payment details for one or both of the following:
- Secure payment details. Tokenize your payment details to secure them and provide a method to submit and handle payment requests. Your payment form shouldn’t include any other actions.
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:
- Required for successful transaction. These fields are required for every transaction. If you omit them, your transactions will fail.
- Required payment field for merchants. These fields are in the default list of required payment fields for merchants. Each merchant can customize their own list in the AffiniPay web application. To see the list of required payment fields for a merchant, send a GET request to the https://api.chargeio.com/api/v1/merchant endpoint.
- Required payment field for partners. These fields are in the default list of required payment fields for partners. When policies are enabled for a partner and a merchant makes a payment through the partner’s application, these required fields override the required fields set in the merchant’s account.
- Optional. This information makes it easier to contact a cardholder if there are transaction issues.
|Cardholder data||Why collect it?|
|card number||Required for successful transaction|
|card expiration||Required for successful transaction|
|card CVV||Required 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 name||Optional. 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.|
|address 1||Required payment field for merchants. If you don’t submit this information, you may not get the best processing rate.|
|postal code||Required 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.|
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.
- If the ach_accounts section contains one or more accounts, the merchant is enabled for eCheck.
- If the ach_accounts section does not contain any accounts, the merchant is not enabled for eCheck. Direct them to the appropriate web application (LawPay, CPACharge, or AffiniPay), where the business owner can enable eCheck.
For eCheck payments, your form must include:
- The following eCheck fields:
- account holder type: individual or business
- name (for business account holder type only)
- given name and (optional) surname (for individual account holder type only)
- routing number
- account number
- account type
See the token object type for descriptions of these fields.
- The following text (with <Merchant Name> replaced with the name of the Merchant) above the Submit button:
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:
- Include the tokenization library. Add the following script include to your web page:
- 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).
Note: You must add this <script> element after the script include element from the previous step.
create_token()function, and handle the tokenization response.
The event handler must:
- Exchange payment details for a token from the AffiniPay Payment Gateway using the
ChargeIO.create_token()function. One-time tokens expire five minutes after creation.
- POST the token and payment amount to your server, which must submit the charge to the AffiniPay Payment Gateway using your protected secret key.
- Handle the payment response returned from your web server, displaying any errors or updating the page with a receipt.
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: Include tokenization library
- 02: Include jQuery
- 04: Initialize library
- 06-15: Display messages for any errors received processing the payment and re-enable form submit button for retry.
- 17: Ensure tokenization library is ready before binding event handlers and enabling the submit button.
- 18: Enable payment submit button in form.
- 19: Add click event to payment form button.
- 20: Prevent event propagation to ensure form content is not POSTed back to the hosting page.
- 21: Disable submit button to prevent duplicate payment attempts.
- 22: Define the payment amount.
- 23: Use the payment form fields to create the ‘token’ JSON request object. The ChargeIO.payment_params() function assumes your form field names match the ‘token’ API properties. If this isn’t the case in your form, you need to programmatically create this JSON object.
- 23: Request a token from the AffiniPay Payment Gateway API.
- 25: POST the received token ID and amount to your web server.
- 26-28: Process error messages that were returned.
- 29-31: Transition to receipt page on success.
- 32-34: Handle failures to run the payment from the web server.
Once you have a payment form, you can create a charge.