Credit Card Integration

Overview

Prime Trust provides a credit card embeddable widget for credit card processing integration.

Widget features:

  • Securely handles and processes credit card events using an iframe
  • Handles card linking, one-time, and recurring purchases
  • Handles processing requirements (including CVV codes verification)
  • Uses Prime Trust Indemnity services to provide fraud protection (3DS challenge)

Prerequisites

  • You have an API user and have worked with your account manager to enable your Prime Trust services and environments.
  • You have provided the Prime Trust with your organization’s user email for both the sandbox and production environments.
  • Prime Trust provided you with an id value for the production version of the Purchase Protection script.
  • Your crypto purchase flow is a “two-click” process; one to load the Prime Trust account, and a separate step to purchase the crypto.

IMPORTANT: You must use a two-click flow. A one-click flow that executes two backend transactions is incompatible with indemnity.

Flows overview

The credit card embeddable widget provides the ability to link and process card contributions using 3DS challenge.

  1. Card-linking with 3DS challenge using widget
  2. Process card contribution with 3DS challenge using widget
  3. Cancel contribution

Integrators can also pre-create contributions. In this case, integrators may prefer to create a token linked to a “pre-created” token that can ONLY be used to complete/process the pre-created contribution.

  1. Create pre-contribution
  2. Process pre-contribution with 3DS challenge

End users can make recurring contributions based on an initial contribution. The initial contribution requires CVV code validation, but subsequent contributions do not.

Indemnity overview

Prime Indemnity offers purchase protection for integrators using the Prime Trust card widget through frontend JavaScript and issue a 3 Domain Secure (3DS) challenge. 3DS purchase protection enables additional fraud prevention for merchants by presenting a validation check within the card purchase flow.

Purchase Protection is required for all cryptocurrency purchase integrations.

For Prime Trust card integrations, the 3DS validation can occur within two steps of the flow:

  • Card linking, when adding a card for payment
  • Purchase processing

During the card linking flow, the issuing bank of the card being linked can request a 3DS challenge/verification on the transaction. In that case, the script launches the 3DS challenge to validate the card holder’s authority to add and use the card. The purchase processing flow, which is called from your frontend application using the Prime Trust widget, relies upon the challengeId returned from the script.

Purchase Protection script

Setup the purchase protection script first before setting up the credit card script, which is the next step.

Prime Trust provides code for both sandbox and production environments, as well as the value for id used in the production script. Use the following id value for sandbox testing: d5a2c18b661d

Production script

<script type="text/javascript" src="https://bootstrapper.primetrust-cdn.com/purchaseProtection.js" id="<id>" defer></script>

Sandbox script

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

Place the script tag on all checkout pages in your <head> or before your </body> tag. It's preferable to use the defer or async tag to make sure that it will not impact the loading of your code.

Credit card widget setup

The widget frontend application reads the TOKEN, checks it against the API, and handles the user experience and the API requests needed to link a new card and create a card contribution.

Credit card script tag

Use either the production or sandbox script code for your environment.

<!-- 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 the script tag on your website, you'll need to create the code that will bootstrap this application and render the iframe.

The code is 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 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>

The widget provides an fail error for failed contributions.

Event name: onContributionFailed

Event objects: error: an object containing the error object received from the backend

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 is securely transmitted to Prime Trust by using the CreditCardResource object. You must first create the CreditCardResource* using an authenticated user. The only attribute required to create a new CreditCardResource is the ID of an existing Contact.

Request

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

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 (option 1: using credit card resource token)

Retrieve the credit card resource ID linked to the credit card 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

Launch the credit card 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);
}
}
});

Optional parameters

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

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

Contribution flow (option 2: pre-create contribution)

High-level steps

  • Create contribution using POST /v2/contributions/token to return a contribution in “pending” status and a token
  • Collect CVV code and process/complete contribution using the token (returned in the contribution call) to launch the credit card embeddable widget from the client application
  1. Create contribution using POST /v2/contributions/token.

Request

{
"data": {
"type": "contributions",
"attributes": {
"amount": "string",
"account-id": "string",
"contact-id": "string",
"funds-transfer-method-id": "string"
}
}
}

Response

{
"data": {
"type": "contributions",
"id": "string",
"attributes": {
"amount": "string",
"currency-type": "string",
"amount-expected": "string",
"contributor-email": "string",
"contributor-name": "string",
"created-at": "2021-10-22T18:15:27Z",
"funds-transfer-details": "string",
"funds-transfer-type": "string",
"message": "string",
"private-memo": "string",
"reference": "string",
"signet-deposit-address": "string",
"special-instructions": "string",
"special-type": "string",
"status": "string",
"payment-details": "string",
"payment-type": "string",
"reference-number": "string",
"transaction-number": "string",
"resource-token-hash": "CONTRIBUTION_TOKEN"
},
"relationships": {...},
"links": {...}
},
"included": [...]
}
  1. Use the pre-created contribution token to process to existing contribution.

Launch the credit card embeddable widget.

pt.launchCreditCard({
target: document.getElementById("contribution"),
resourceTokenHash: <CONTRIBUTION_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);
}
}
});

Cancel pre-created contribution

Use POST /v2/contributions/token/<token-hash>/cancelto cancel a pre-created credit card contribution:

  • Used if the Contribution is in Pending status and there is no funds transfer associated with it (meaning it hasn’t been fully processed)

  • Canceling prevents the token from working

If the contribution has been processed, the system returns a 403 response with the message, “Funds transfer has already been processed and cannot be cancelled.”

Webhooks

An “update” webhook is sent once the contribution has been completed.

Sample webhook payload

{
"id": "string",
"account-id": "string",
"action": "update",
"data": {
"created_at": "2021-11-30T21:47:17Z",
"completed_at": "2021-11-30T21:47:58Z",
"funds_transfer_id": "0b34f7ee-22bf-4e6b-8d52-36019924c2e0"
]
},
"resource-id": "string",
"resource-type": "contributions",
"account_id": "string",
"resource_id": "CONTRIBUTION_ID",
"resource_type": "contributions"
}

Sandbox testing

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

Card TypeCard NumberSecret
MasterCard5111330000000006123456
Visa4457000100000009secret

Content Security Policy (CSP) considerations

If your website enforces a CSP, please do the following:

  • If the site CSP restricts inline Javascript tags (required by Prime Trust) - please ask your Account Manager for the hash you can use to whitelist the integration tag in the CSP script-src directive.
Last updated on