Overview
Capturing credit card details through the Assembly platform is a straightforward task, which can be accomplished by utilizing the PromisePay.js package. Through this integration, it is possible to capture card details and generate an accompanying token through a variety of different measures, including secure iFrame transport layers and custom forms.
Walkthrough
Before you start
Capturing credit card information utilises the PromisePay.js package. Please make sure that you have properly set up the PromisePay.js integration on your platform before continuing.
If you have not yet set up PromisePay.js within your platform, please follow the instructions laid out in our guide for Integrating PromisePay.js.
Capturing Credit Card Details
Capturing credit card details through the front-end will mean data can be securely sent to Assembly with minimal PCI compliance impact. There are a couple of methods which can be used to capture credit card details.
Generating a Card Token
A card token is used to authorize the passing of credit card details through the client-side libraries. The generating of the card token occurs server-side, so that the generated token can be passed into the client-side for authentication. There are two use cases for generating a card token;
- Capturing credit card details of an existing user. This will involve passing the
user_idparameter when generating the card token. This token will expire as soon as a valid credit card is added or after 2 hours. - Capturing credit card details for an anonymous or new user (using the Charge API). This will involve not passing the
user_idparameter when generating the card token. This token will expire as soon as a valid credit card is added or after 2 hours.
Use Generate Token to generate the card token.
Direct Javascript
Capturing credit card details using the Direct Javascript has two steps:
- Generating a card token to authenticate the creation of a credit card in Assembly
- Sending the credit card details to Assembly through the Javascript method
Sending the card information to Assembly will return a successful or failure response. You may wish to provide feedback once the request has been made. Callback functions will need to be created to handle these.
If the request is successful, you will receive a JSON response just as if you had created the card using the Create Card Account method. This will provide a card account_id which can be used to make a payment. This account ID can also be fetched using the Show Card Account User method in the API.
|
// Create your callback methods
success = function(data) {
console.log(data);
}
fail = function(data) {
console.log(data);
}/**
* @param {string} cardToken
* @param {string} cardData
* @param {string} successFunction
* @param {string} failFunction
*/
promisepay.createCardAccount("CARD_TOKEN", {
full_name: "Bella Buyer",
number: "4111111111111111",
expiry_month: "02",
expiry_year: "2022",
cvv: "123"
}, success, fail)
|
Creating a custom HTML form
Capturing credit card details using a Custom Form has three steps;
- Generating a card token to authenticate the creation of a credit card in Assembly
- Setting up your credit card form
- Sending the credit card details to Assembly through your form
Sending the card information to Assembly will return a successful or failure response. You may wish to provide feedback once the request has been made. Callback functions will need to be created to handle these.
If the request is successful, you will receive a JSON response just as if you had created the card using the Create Card Account method. This will provide a card account id which can be used to make a payment. This account ID can also be fetched using the Show Card Account User method in the API.
Creating the HTML Form
|
<form id="promisepay-form" autocomplete="on">
<p>
<input type="text" placeholder="Full Name" data-promisepay-encrypted-name="cardName">
</p>
<p>
<input type="tel" placeholder="card number" data-promisepay-encrypted-name="cardNumber">
</p>
<p>
<input type="tel" data-promisepay-encrypted-name="cardExpiryDate">
</p>
<p>
<input type="text" autocomplete="off" data-promisepay-encrypted-name="cardCVC">
</p>
<p>
<input type="hidden" data-promisepay-card-token='cardToken'>
</p>
<p class="promisepay-server-error" style="display: none"></p>
<input type="submit">
</form>
|
Key notes
- Ensure no
nameattributes are passed through for any credit card inputs. This is to avoid any of the information being passed to your back-end service. - The element with class
promisepay-server-errorcan be used to return any server errors with credit card creation. - Upon successful submission, the form will submit with a new hidden input which contains the card account id.
Sending the data to Assembly
|
$(document).ready(function () {
promisepay.createCardAccountForm("promisepay-form", success, fail);
})
|
Callback functions
|
createCardAccountForm(formId, successFunction, failFunction, errorStrings);
|
| Function | Requirement | Default value | Description |
| successFunction | optional | none | Function that will handle results upon success |
| failFunction | optional | none | Function to handle any cause of failure |
| errorStrings | optional | See below | An customisable object which you can feed to the method to customize the errors shown in the form |
Error strings
| {
“CARD_NAME”: “<span class=’promisepay-form-error’> Please enter a valid name </span>”, “CARD_NUMBER”: “<span class=’promisepay-form-error’> Please enter a valid card number </span>”, “CARD_DATE”: “<span class=’promisepay-form-error’> Please enter a valid credit card expiry date </span>”, “CARD_CVC”: “<span class=’promisepay-form-error’> Please enter a valid CVC </span>”,
“BANK_NAME”:”<span class=’promisepay-form-error’> Please enter a valid Bank Name </span>”, “BANK_ACCOUNT_NAME”:”<span class=’promisepay-form-error’> Please enter a valid Account Name </span>”, “BANK_ROUTING_NUMBER”:”<span class=’promisepay-form-error’> Please enter a valid Routing Number </span>”, “BANK_ACCOUNT_NUMBER”:”<span class=’promisepay-form-error’> Please enter a valid Account Number </span>”, “BANK_ACCOUNT_TYPE”:”<span class=’promisepay-form-error’> Please enter a valid Account Type </span>”, “BANK_HOLDER_TYPE”:”<span class=’promisepay-form-error’> Please enter a valid Holder Type </span>”, “BANK_COUNTRY”:”<span class=’promisepay-form-error’> Please enter a valid Country </span>”, “PAYOUT_CURRENCY”:”<span class=’promisepay-form-error’> Please enter a valid Currency </span>”, “CARD_TOKEN”: { “UNAUTHORIZED”: “Card Token unauthorized” }, “BANK_TOKEN”:{ “UNAUTHORIZED”: “Bank Token unauthorized”, “RECORD”:”Bank Token not authorized to access that record” }, “BASE”: { “PAYMENT_FAILED”: “Credit card payment failed: Unable to process the purchase transaction.” }, }; |
Diagnosing Issues
Pass the following function into the “promisepay.createCardAccountForm” method as the failFunction parameter. Errors should be descriptive enough to provide a diagnosis.
|
fail = function (data) {
console.log(data);
}
|
At this point, if the card token was attached to a user, they will have a card account attached to their user in Assembly.
Comments
2 comments
Great doco, but hit an error using the credit card provided. Assuming this is because it has expired.
Worked with the following:
The payload example has two fields for credit card expiry date - expiry_month and expiry_year. The html form example has only one input field - <input type="tel" data-promisepay-encrypted-name="cardExpiryDate">.
What will be the data attribute names if I have two separate input fields for expiry year and expiry month?
Please sign in to leave a comment.