Take paymentsHosted FieldsExtend your integration

Update a customer's payment details

View as Markdown

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

If a customer uses Hosted Fields to change their payment details, our gateway returns a single-use token that represents the updated payment details. To update the customer’s saved payment details, send the single-use token to our gateway to update the secure token.

You can use a single-use token to update only the payment details linked to a secure token. To update the customer’s contact details or the merchant-initiated transaction (MIT) agreement, go to Update a secure token.

Before you begin

Make sure that you’ve set up your integration to save payment details.

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

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.
$-H "Content-Type: application/json"
$-H "Authorization: <Bearer token>"
$-H "Idempotency-Key: <UUID v4>"

To create the header of each GET request, include the Authorization header parameter.

$-H "Authorization: <Bearer token>"

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. List secure tokens.
  2. Generate a session token.
  3. Update the JavaScript library.
  4. Update the secure token.

Step 1. List secure tokens

Before you update the customer’s payment details, you need the secureTokenId of the secure token that represents the customer’s payments details.

To search for the secureTokenId, use our List Secure Tokens method to view all the secure tokens associated with the processing terminal. You can use query parameters to filter your search, for example, you can filter by the customer’s name or email address.

To view the secure tokens associated with the processing terminal, send a GET request to our Secure Tokens endpoint.

Request parameters

To create your request, use the following parameters:

Path parameters

processingTerminalIdstringRequired4-50 characters
Unique identifier that we assigned to the terminal.

Query parameters

secureTokenIdstringOptional1-200 characters
Unique identifier that the merchant assigned to the secure token.
customerNamestringOptional1-50 characters
Filter by the customer's name.
phonestringOptional1-15 characters
Filter by the customer's phone number.
emailstringOptional1-100 characters
Filter by the customer's email address.
tokenstringOptional12-19 characters
Filter by the token that the merchant used in a transaction to represent the customer's payment details.
first6stringOptionalformat: "[0-9]{6}"
Filter by the first six digits of the card number.
last4stringOptionalformat: "[0-9]{4}"
Filter by the last four digits of the card or account number.
beforestringOptional
Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter.
afterstringOptional
Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter.
limitintegerOptional<=100Defaults to 10
Limit the maximum number of results that we return for each page.

Example request

GET
/v1/processing-terminals/:processingTerminalId/secure-tokens
1curl -G https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens \
2     -H "Authorization: Bearer <token>" \
3     -d after=8516 \
4     -d before=2571 \
5     --data-urlencode customerName=Sarah%20Hazel%20Hopper \
6     --data-urlencode [email protected] \
7     -d first6=453985 \
8     -d last4=7062 \
9     -d limit=25 \
10     -d phone=2025550165 \
11     -d secureTokenId=MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa \
12     -d token=296753123456
Try it

Response fields

If your request is successful, we return a list of secure tokens associated with the processing terminal. The response contains the following fields:

Response

limitintegerRequired
Maximum number of results that we return for each page.
countintegerRequired
Number of results we returned on this page. **Note:** This might not be the total number of results that match your query.
hasMorebooleanRequired
Indicates whether there is another page of results available.
datalist of objectsRequired
Array of saved payment details.

Example response

Response
1{
2  "limit": 2,
3  "count": 2,
4  "hasMore": true,
5  "data": [
6    {
7      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
8      "processingTerminalId": "1234001",
9      "source": {
10        "type": "card",
11        "cardNumber": "453985******7062",
12        "cardholderName": "Sarah Hopper",
13        "expiryDate": "1230"
14      },
15      "token": "296753123456",
16      "status": "notValidated",
17      "mitAgreement": "unscheduled",
18      "customer": {
19        "firstName": "Sarah",
20        "lastName": "Hopper",
21        "dateOfBirth": "1990-07-15",
22        "referenceNumber": "Customer-12",
23        "billingAddress": {
24          "address1": "1 Example Ave.",
25          "address2": "Example Address Line 2",
26          "address3": "Example Address Line 3",
27          "city": "Chicago",
28          "state": "Illinois",
29          "country": "US",
30          "postalCode": "60056"
31        },
32        "shippingAddress": {
33          "recipientName": "Sarah Hopper",
34          "address": {
35            "address1": "1 Example Ave.",
36            "address2": "Example Address Line 2",
37            "address3": "Example Address Line 3",
38            "city": "Chicago",
39            "state": "Illinois",
40            "country": "US",
41            "postalCode": "60056"
42          }
43        }
44      }
45    },
46    {
47      "secureTokenId": "MREF_fe0d9876-cba5-432f-e10d-9cb87654a3f2e1",
48      "processingTerminalId": "1234001",
49      "source": {
50        "type": "card",
51        "cardNumber": "500165******0000",
52        "cardholderName": "Sarah Hazel Hopper",
53        "expiryDate": "0328"
54      },
55      "token": "307864234567",
56      "status": "notValidated",
57      "mitAgreement": "unscheduled",
58      "customer": {
59        "firstName": "Sarah",
60        "lastName": "Hopper",
61        "dateOfBirth": "1990-07-15",
62        "referenceNumber": "Customer-12",
63        "billingAddress": {
64          "address1": "1 Example Ave.",
65          "address2": "Example Address Line 2",
66          "address3": "Example Address Line 3",
67          "city": "Chicago",
68          "state": "Illinois",
69          "country": "US",
70          "postalCode": "60056"
71        },
72        "shippingAddress": {
73          "recipientName": "Sarah Hopper",
74          "address": {
75            "address1": "1 Example Ave.",
76            "address2": "Example Address Line 2",
77            "address3": "Example Address Line 3",
78            "city": "Chicago",
79            "state": "Illinois",
80            "country": "US",
81            "postalCode": "60056"
82          }
83        }
84      },
85      "customFields": [
86        {
87          "name": "yourCustomField",
88          "value": "abc123"
89        }
90      ]
91    }
92  ],
93  "links": [
94    {
95      "rel": "next",
96      "method": "get",
97      "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens?limit=2&after=MREF_fe0d9876-cba5-432f-e10d-9cb87654a3f2e1"
98    },
99    {
100      "rel": "previous",
101      "method": "get",
102      "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens?limit=2&before=MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
103    }
104  ]
105}

Step 2. Generate a session token

When you generate the session token, you need to include the secureTokenId of the secure token that you want to update.

To generate a session token, send a POST request to our Processing Terminals endpoint.

Request parameters

To create the body of your request, use the following parameters:

Request

Example request

POST
/v1/processing-terminals/:processingTerminalId/hosted-fields-sessions
1curl -X POST https://api.payroc.com/v1/processing-terminals/1234001/hosted-fields-sessions \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{
6  "libVersion": "1.1.0.123456",
7  "scenario": "payment"
8}'
Try it

Response fields

If your request is successful, our gateway generates a session token. The response contains the following fields:

Response

Example response

Response
1{
2  "processingTerminalId": "1234001",
3  "token": "abcdef1234567890abcdef1234567890",
4  "expiresAt": "2025-07-02T15:30:00.000+02:00"
5}

Step 3. Update the JavaScript library

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</script>

Step 4. Update the secure token

After the customer submits their new payment details and you receive the single-use token from the submissionSuccess event, send the single-use token to our gateway to update the secure token.

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

Request parameters

To create the body of your request, use the following parameters:

Request

Example request

POST
/v1/processing-terminals/:processingTerminalId/secure-tokens/:secureTokenId/update-account
1curl -X POST https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa/update-account \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{
6  "type": "singleUseToken",
7  "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
8}'
Try it

Response fields

If your request is successful, we update the payment details associated with the secure token. The response contains the following fields:

Note: When we update the payment details associated with the secure token, we change only the payment details that the secure token represents. The values for the secureTokenId parameter and the token parameter stay the same.

Response

Example response

Response
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}