Save a customer's payment details

An AI skill is available for this guide, get it on the Skills Marketplace (GitHub).

You can update your Hosted Fields integration to save a customer's payment details as a secure token without charging the customer.

To tokenize the customer's payment details, you need to update the Hosted Fields JavaScript configuration, and then send a request to our Secure Tokens endpoint.

You don't need to change your authentication process for your existing Hosted Fields integration.

Before you begin

Make sure that you've set up your Hosted Fields integration to handle the single-use token from the submissionSuccess event. For more information, go to Run a sale.

Authenticate your requests before making API calls. If your request fails, see Errors.

Integration steps

Update the JavaScript configuration.
Convert the single-use token into a secure token.

Step 1. Update the JavaScript configuration

In the JavaScript configuration, change the value for the mode parameter from payment to tokenization.

Card

JavaScript

<script
  src="https://cdn.uat.payroc.com/js/hosted-fields/hosted-fields-1.7.0.261457.js"
  integrity="sha384-m1A0nfFYa8sAfpDN0d60o4ztd/aCPC2xDVaOT31Urrmn4xypfHqgHQMayZeIK1PM"
  crossorigin="anonymous"
></script>

<script>
  const cardForm = new Payroc.hostedFields({
    sessionToken: YOUR_SESSION_TOKEN,
    mode: "tokenization",
    fields: {
      card: {
        cardholderName: {
          target: ".card-holder-name",
          errorTarget: ".card-holder-name-error",
          placeholder: "Cardholder Name",
        },
        cardNumber: {
          target: ".card-number",
          errorTarget: ".card-number-error",
          placeholder: "1234 5678 1234 1211",
        },
        cvv: {
          wrapperTarget: ".card-cvv-wrapper",
          target: ".card-cvv",
          errorTarget: ".card-cvv-error",
          placeholder: "CVV",
        },
        expiryDate: {
          target: ".card-expiry",
          errorTarget: ".card-expiry-error",
          placeholder: "MM/YY",
        },
        submit: {
          target: ".submit-button",
          value: "Submit",
        },
      },
    },
  });
  padForm.initialize();
</script>

ACH

JavaScript

<script
  src="https://cdn.uat.payroc.com/js/hosted-fields/hosted-fields-1.7.0.261457.js"
  integrity="sha384-m1A0nfFYa8sAfpDN0d60o4ztd/aCPC2xDVaOT31Urrmn4xypfHqgHQMayZeIK1PM"
  crossorigin="anonymous"
></script>

<script>
  const achForm = new Payroc.hostedFields({
    sessionToken: YOUR_SESSION_TOKEN,
    mode: "tokenization",
    fields: {
      ach: {
        nameOnAccount: {
          target: ".ach-account-holder",
          errorTarget: ".ach-account-holder-error",
          placeholder: "Accountholder Name",
        },
        accountType: {
          target: ".ach-account-type",
          errorTarget: ".ach-account-type-error",
        },
        achAccountNumber: {
          target: ".ach-account-number",
          errorTarget: ".ach-account-number-error",
          placeholder: "Account Number",
        },
        routingNumber: {
          target: ".ach-routing-number",
          errorTarget: ".ach-routing-number-error",
          placeholder: "Routing Number",
        },
        submit: {
          target: ".submit-button",
          value: "Submit",
        },
      },
    },
  });
</script>

PAD

JavaScript

<script
  src="https://cdn.uat.payroc.com/js/hosted-fields/hosted-fields-1.7.0.261457.js"
  integrity="sha384-m1A0nfFYa8sAfpDN0d60o4ztd/aCPC2xDVaOT31Urrmn4xypfHqgHQMayZeIK1PM"
  crossorigin="anonymous"
></script>

<script>
  const padForm = new Payroc.hostedFields({
    sessionToken: YOUR_SESSION_TOKEN,
    mode: "tokenization",
    fields: {
      pad: {
        nameOnAccount: {
          target: ".pad-account-holder",
          errorTarget: ".pad-account-holder-error",
          placeholder: "Accountholder Name",
        },
        padAccountNumber: {
          target: ".pad-account-number",
          errorTarget: ".pad-account-number-error",
          placeholder: "Account Number",
        },
        institutionNumber: {
          target: ".pad-institution-number",
          errorTarget: ".pad-institution-number-error",
          placeholder: "Institution Number",
        },
        transitNumber: {
          target: ".pad-transit-number",
          errorTarget: ".pad-transit-number-error",
          placeholder: "Transit Number",
        },
        submit: {
          target: ".submit-button",
          value: "Submit",
        },
      },
    },
  });
</script>

Step 2. Convert the single-use token into a secure token

To convert the single-use token into a secure token, send a POST request to our Secure Tokens endpoint.

Environment	URL
Test	https://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/secure-tokens
Production	https://api.payroc.com/v1/processing-terminals/{processingTerminalId}/secure-tokens

Request parameters

In the body of your request, include the singleUseToken from the submissionSuccess event in the source object. We also recommend that you assign a secureTokenId.

Schema (`request.body`)

Request body schema for POST /processing-terminals/{processingTerminalId}/secure-tokens