Save a customer's payment details

When you use Hosted Fields to capture a customer’s payment details, we return a single-use token. You can use the single-use token only once, and it expires 30 minutes after we return it.

If you want to run a sale later or run multiple sales, you need to convert the single-use token into a secure token. You can use the secure token multiple times, and it doesn’t expire.

Before you begin

Make sure you have set up your integration to run a sale.

Headers

To create the header of each POST request, you must include the following parameters:

• Content-Type: Include application/json as the value for this parameter.
• Authorization: Include your Bearer token in this parameter.
• Idempotency-Key: Include a UUID v4 to make the request idempotent.

1
-H "Content-Type: application/json"
2
-H "Authorization: <Bearer token>"
3
-H "Idempotency-Key: <UUID v4>"

Errors

Make sure that your integration can handle errors. If a request is unsuccessful, we return an error that follows the RFC 7807 format. For more information about errors, go to Errors.

Integration steps

1. Update the JavaScript configuration
2. Convert the single-use token into a secure token.
3. (Optional) Run a sale with the 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

To create the body of your request, send the single-use token in the source object.

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": "card",
8
    "cardDetails": {
9
      "entryMethod": "keyed",
10
      "keyedData": {
11
        "dataFormat": "plainText",
12
        "cardNumber": "4539858876047062",
13
        "cvv": "234",
14
        "expiryDate": "1230"
15
      },
16
      "cardholderName": "Sarah Hazel Hopper"
17
    }
18
  },
19
  "operator": "Jane",
20
  "mitAgreement": "unscheduled",
21
  "customer": {
22
    "firstName": "Sarah",
23
    "lastName": "Hopper",
24
    "dateOfBirth": "1990-07-15",
25
    "referenceNumber": "Customer-12",
26
    "billingAddress": {
27
      "address1": "1 Example Ave.",
28
      "city": "Chicago",
29
      "state": "Illinois",
30
      "country": "US",
31
      "postalCode": "60056",
32
      "address2": "Example Address Line 2",
33
      "address3": "Example Address Line 3"
34
    },
35
    "shippingAddress": {
36
      "recipientName": "Sarah Hopper",
37
      "address": {
38
        "address1": "1 Example Ave.",
39
        "city": "Chicago",
40
        "state": "Illinois",
41
        "country": "US",
42
        "postalCode": "60056",
43
        "address2": "Example Address Line 2",
44
        "address3": "Example Address Line 3"
45
      }
46
    },
47
    "contactMethods": [
48
      {
49
        "type": "email",
50
        "value": "[email protected]"
51
      }
52
    ],
53
    "notificationLanguage": "en"
54
  },
55
  "ipAddress": {
56
    "type": "ipv4",
57
    "value": "104.18.24.203"
58
  },
59
  "customFields": [
60
    {
61
      "name": "yourCustomField",
62
      "value": "abc123"
63
    }
64
  ]
65
}'

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
      "address3": "Example Address Line 3",
22
      "city": "Chicago",
23
      "state": "Illinois",
24
      "country": "US",
25
      "postalCode": "60056"
26
    },
27
    "shippingAddress": {
28
      "recipientName": "Sarah Hopper",
29
      "address": {
30
        "address1": "1 Example Ave.",
31
        "address2": "Example Address Line 2",
32
        "address3": "Example Address Line 3",
33
        "city": "Chicago",
34
        "state": "Illinois",
35
        "country": "US",
36
        "postalCode": "60056"
37
      }
38
    },
39
    "contactMethods": [
40
      {
41
        "type": "email",
42
        "value": "[email protected]"
43
      }
44
    ],
45
    "notificationLanguage": "en"
46
  },
47
  "customFields": [
48
    {
49
      "name": "yourCustomField",
50
      "value": "abc123"
51
    }
52
  ]
53
}

Step 3. (Optional) Run a sale with the secure token

To run a sale with the secure token, the method that you need to follow depends on whether the secure token represents card details or bank account details.

Use the same methods that you used in Run a Sale, but update the following parameters in the paymentMethod object:

• type - Change the value to secureToken.
• token - Include the secure token that you received in Step 2.