Creating payment forms
Use these guidelines as you build the payment form you’ll use to collect payment details.
Your payment form must:
- Gather cardholder details. Collect all the required and recommended cardholder details.
- 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.
- Include options for entering both credit card and Automated Clearing House (ACH) payment methods, if you support both.
Gather cardholder details
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.|
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> <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.