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.
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>"
To create the header of each GET request, include the Authorization header parameter.
1
-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
List secure tokens.
Generate a session token.
Update the JavaScript library.
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.
Version of the Hosted Fields JavaScript library that you are using.
The current production version is ` 1.7.0.261471`.
scenarioenumRequired
Indicates if a merchant wants to take a payment or tokenize a customer's payment details:
- `payment` - The merchant wants to run a sale or run a sale and tokenize in the same transaction.
- `tokenization` - The merchant wants to save the customer's payment details to take a payment later or to update a customer's payment details that they've already saved.
Allowed values:
secureTokenIdstringOptional1-200 characters
Unique identifier that represents a customer's payment details.
If a merchant wants to update a customer's payment details that are linked to a secure token, include the secureTokenId in your request.
If your request is successful, our gateway generates a session token. The response contains the following fields:
Response
processingTerminalIdstringRequired
Unique identifier that we assigned to the terminal.
tokenstringRequired
Token that our gateway assigned to the Hosted Fields session.
Include this session token in the config file for Hosted Fields.
The session token expires after 10 minutes.
expiresAtdatetimeRequiredRead-only
Date and time that the token expires. We return this value in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.
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.
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.
If your request is successful, we update the payment details associated with the secure token. The response contains the following fields:
Response
secureTokenIdstringRequired0-200 characters
Unique identifier that the merchant created for the secure token that represents the customer's payment details.
processingTerminalIdstringRequired4-50 characters
Unique identifier that we assigned to the terminal.
sourceobjectRequired
Polymorphic object that contains the payment method that we tokenized.
The value of the type parameter determines which variant you should use:
- `ach` - Automated Clearing House (ACH) details
- `pad` - Pre-authorized debit (PAD) details
- `card` - Payment card details
tokenstringRequired12-19 characters
Token that the merchant can use in future transactions to represent the customer's payment details. The token:
- Begins with the six-digit identification number **296753**.
- Contains up to 12 digits.
- Contains a single check digit that we calculate using the Luhn algorithm.
statusenumRequired
Outcome of a security check on the status of the customer's payment card or bank account.
**Note:** Depending on the merchant's account settings, this feature may be unavailable.
mitAgreementenumOptional
Indicates how the merchant can use the customer's card details, as agreed by the customer:
- `unscheduled` - Transactions for a fixed or variable amount that are run at a certain pre-defined event.
- `recurring` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Recurring transactions don't have a fixed duration and run until the customer cancels the agreement.
- `installment` - Transactions for a fixed amount that are run at regular intervals, for example, monthly. Installment transactions have a fixed duration.
Allowed values:
customerobjectOptional
Object that contains the customer's contact details and address information.
