Save a customer's payment details

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

1. Update the JavaScript configuration.
2. 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.

1
<script
2
  src="https://cdn.uat.payroc.com/js/hosted-fields/hosted-fields-1.7.0.261457.js"
3
  integrity="sha384-m1A0nfFYa8sAfpDN0d60o4ztd/aCPC2xDVaOT31Urrmn4xypfHqgHQMayZeIK1PM"
4
  crossorigin="anonymous"
5
></script>
6
7
<script>
8
  const cardForm = new Payroc.hostedFields({
9
    sessionToken: YOUR_SESSION_TOKEN,
10
    mode: "tokenization",
11
    fields: {
12
      card: {
13
        cardholderName: {
14
          target: ".card-holder-name",
15
          errorTarget: ".card-holder-name-error",
16
          placeholder: "Cardholder Name",
17
        },
18
        cardNumber: {
19
          target: ".card-number",
20
          errorTarget: ".card-number-error",
21
          placeholder: "1234 5678 1234 1211",
22
        },
23
        cvv: {
24
          wrapperTarget: ".card-cvv-wrapper",
25
          target: ".card-cvv",
26
          errorTarget: ".card-cvv-error",
27
          placeholder: "CVV",
28
        },
29
        expiryDate: {
30
          target: ".card-expiry",
31
          errorTarget: ".card-expiry-error",
32
          placeholder: "MM/YY",
33
        },
34
        submit: {
35
          target: ".submit-button",
36
          value: "Submit",
37
        },
38
      },
39
    },
40
  });
41
  padForm.initialize();
42
</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.

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.

Example request

1
curl -X POST https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens \
2
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3
     -H "Authorization: Bearer <token>" \
4
     -H "Content-Type: application/json" \
5
     -d '{
6
  "source": {
7
    "type": "singleUseToken",
8
    "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
9
  },
10
  "operator": "Jane",
11
  "mitAgreement": "unscheduled",
12
  "customer": {
13
    "firstName": "Sarah",
14
    "lastName": "Hopper",
15
    "dateOfBirth": "1990-07-15",
16
    "referenceNumber": "Customer-12",
17
    "billingAddress": {
18
      "address1": "1 Example Ave.",
19
      "city": "Chicago",
20
      "state": "Illinois",
21
      "country": "US",
22
      "postalCode": "60056",
23
      "address2": "Example Address Line 2"
24
    },
25
    "contactMethods": [
26
      {
27
        "type": "email",
28
        "value": "[email protected]"
29
      }
30
    ],
31
    "notificationLanguage": "en"
32
  },
33
  "ipAddress": {
34
    "type": "ipv4",
35
    "value": "104.18.24.203"
36
  },
37
  "customFields": [
38
    {
39
      "name": "yourCustomField",
40
      "value": "abc123"
41
    }
42
  ]
43
}'

Response fields

If your request is successful, our gateway converts the single-use token into a secure token. Our gateway returns the secure token in the token field. The response also contains the following fields:

Response example

1
{
2
  "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
3
  "processingTerminalId": "1234001",
4
  "source": {
5
    "type": "card",
6
    "cardNumber": "453985******7062",
7
    "cardholderName": "Sarah Hazel Hopper",
8
    "expiryDate": "1230"
9
  },
10
  "token": "296753123456",
11
  "status": "notValidated",
12
  "mitAgreement": "unscheduled",
13
  "customer": {
14
    "firstName": "Sarah",
15
    "lastName": "Hopper",
16
    "dateOfBirth": "1990-07-15",
17
    "referenceNumber": "Customer-12",
18
    "billingAddress": {
19
      "address1": "1 Example Ave.",
20
      "address2": "Example Address Line 2",
21
      "city": "Chicago",
22
      "state": "Illinois",
23
      "country": "US",
24
      "postalCode": "60056"
25
    },
26
    "contactMethods": [
27
      {
28
        "type": "email",
29
        "value": "[email protected]"
30
      }
31
    ],
32
    "notificationLanguage": "en"
33
  },
34
  "customFields": [
35
    {
36
      "name": "yourCustomField",
37
      "value": "abc123"
38
    }
39
  ]
40
}

Using the secure token

After you receive the secure token that represents the customer’s payment details, you can use it in follow-up requests to our API, including:

• Create a card payment
• Create a bank transfer payment
• Update a customer’s payment details with Hosted Fields