Credit Card Integration

Credit card process overview

  1. As an API user, create a Contact
  2. As an API user, create a CreditCardResource and token for the Contact
  3. Load the Prime Trust front-end application into your website
  4. Initialize the Prime Trust front-end application using the CreditCardResource token
  5. Link a credit card:
    • Create a new Credit Card Resource.
    • Use the resource-token-hash from prior step to launch the Credit Card embeddable widget. Include the token via parameter resourceTokenHash.
    • Credit Card linking iframe will display to submit credit card details securely.
  6. Create credit card contribution (repeat as needed):
    • Retrieve the Credit Card Resource ID linked to the Credit Card Funds Transfer Method.
    • Generate a new token using POST /v2/credit-card-resources/:id/token.
    • Use the token to launch the Credit Card embeddable widget. Include the amount of the contribution and token via parameters amount and resourceTokenHash.
    • CVV Iframe will display for input of CVV and submission of the contribution.

Credit card frontend widget setup

For convenience, Prime Trust has created a frontend application that reads a TOKEN, checks it against the API, and handles the user experience and API requests needed to link a new card and create a card contribution.

Script tag

Get the script code for your environment, depending on if you're working in our Sandbox or in Production.

<!-- production -->
<script type="text/javascript" src="https://bootstrapper.primetrust-cdn.com/bootstrap.js" defer></script>
<!-- sandbox -->
<script type="text/javascript" src="https://sandbox.bootstrapper.primetrust-cdn.com/bootstrap.js" defer></script>

You can place this script tag in your <head> or before your </body> tag. It's preferred to use the defer or async tag to make sure that it will not impact the loading of your code.

Initialization

Once you've included this script on your website, you'll need to create the code that will bootstrap this application and render the iframe.

The code will be available through the variables window.PrimeTrustEmbeds or window.pt.

If using Async loading, there will be a few options for listening for it to be ready. window.onPrimeTrustEmbedsReady, and window.onBootstrapReady are specific to this library, while window.primeTrustReady will trigger when all prime trust scripts are finished loading (if using multiple ones, otherwise will run at the same time as the other two).

All can be set to a function, accepting one argument, primeTrustReady will use the pt object (the combined object of all scripts) the other two using PrimeTrustEmbeds which is just the object from this script.

Following is an example of initializing our credit card application / embeddable:

<script
type="text/javascript"
src="https://bootstrapper.primetrust-cdn.com/bootstrap.js"
defer
></script>
<script type="text/javascript">
console.log("[primetrust] Loading Prime Trust Embedding API");
window.primeTrustReady = function (pt) {
console.log("[primetrust] Loading embeddables...");
pt.launchCreditCard({
//Attributes depend on whether you want to link a card or create a contribution.
//See code snippet samples below for each flow
});
};
</script>

Event cleanup

If the launched application is closed without completion (such as when using a modal and the user closes it), each launch function returns a function to remove the event listeners.

Example of checking for cleanup before launching:

var launchCreditCardCleanup;
function launchCreditCard() {
// before launching the widget, make sure any previous instances are cleaned up
if (launchCreditCardCleanup) {
launchCreditCardCleanup();
}
// or launchCreateCompany, launchCreateNaturalPerson
launchCreditCardCleanup = pt.launchCreditCard({
//Attributes depend on whether you want to link a card or create a contribution.
//See code snippet samples below for each flow
});
});
}

Link new credit card flow

Sensitive credit card information can be transmitted to us via the CreditCardResource object, which must first be created by the API integrator using an authenticated user. The only attribute required to create a new CreditCardResource is the ID of an existing Contact:

// POST /v2/credit-card-resources
{
"data": {
"type": "credit-card-resource",
"attributes": {
"contact-id": "YOUR_CONTACT_ID"
}
}
}

This should return the following response:

// Status: 201
{
"data": {
"type": "credit-card-resources",
"id": "CREDIT_CARD_RESOURCE_ID",
"attributes": {
"status": "pending",
"contact-id": "YOUR_CONTACT_ID",
"funds-transfer-method-id": null,
"resource-token-hash": "TOKEN"
}
}
}

Launch the Credit Card embeddable widget:

Optional Parameters:

  • theme: An object containing alternative color options.
    • attributes:
      • background: #ffffff,
      • foreground: #000000,
      • primary: #1890ff,
      • success: #69e2a0,
      • error: #f5222d
pt.launchCreditCard({
target: document.getElementById("verification"),
resourceTokenHash: token,
theme: {
//theme attributes
},
events: {
cardVerified: function (contactId, fundsTransferMethodId) {
console.log("[primetrust] Funds transfer method created with ID:", fundsTransferMethodId);
console.log("[primetrust] Created for Contact: :", contactId);
},
}
});

Contribution flow

Retrieve the Credit Card Resource ID linked to the CC Funds Transfer Method

Request:

GET /v2/funds-transfer-methods/:id?include=credit-card-resource

Response:

{
"data": {
"type": "funds-transfer-methods",
"id": "FUNDS_TRANSFER_METHOD_ID",
"attributes": {
...
},
"relationships": {
...
"credit-card-resource": {
"data": {
"type": "credit-card-resources",
"id": "CREDIT_CARD_RESOURCE_ID"
}
},
...
}
},
"included": [
{
"type": "credit-card-resources",
"id": "CREDIT_CARD_RESOURCE_ID",
"attributes": {
...
},
"links": {
}
}
]
}

Refresh the credit card resource token

Request:

POST /v2/credit-card-resources/:id/token

Response:

{
"data": {
"type": "credit-card-resources",
"id": "CREDIT_CARD_RESOURCE_ID",
"attributes": {
"status": "verified",
"contact-id": "YOUR_CONTACT_ID",
"funds-transfer-method-id": "YOUR_FUNDS_TRANSFER_METHOD_ID",
"resource-token-hash": "TOKEN"
}
}
}

Collect CVV and submit contribution

Optional Parameters:

  • hideAmount: Amount shows by default. Set to true to hide the amount of the contribution above the CVV field

Launch the CC embeddable/widget

pt.launchCreditCard({
amount: amount,
target: document.getElementById("contribution"),
resourceTokenHash: <TOKEN>,
hideAmount: true, // this hides the contribution amount on the CVV form
events:{
onContribution: function (contributionId, fundsTransferMethodId){
//contribution was successful
console.log("[primetrust] Contribution created with ID:", contributionId);
console.log("[primetrust] Contribution using FTM ID:", fundsTransferMethodId);
},
onContributionError: function (error){
//contribution failed
console.log("[primetrust] Error:", error.name);
console.log("[primetrust] Error:", error.message);
}
}
});

Screenshot of the iFrame/embeddable that collects the CVV and submits the contribution: cvv

For sandbox testing, use the following test card numbers and secrets:

Card TypeCard NumberSecret
MasterCard5111330000000006123456
Visa4457000100000009secret
Last updated on