# Save payment details
Save a customer's payment details to the vault by sending a POST request to the secure-tokens endpoint, returning a secureTokenId for use in follow-on card or bank transfer transactions.
**Prerequisites:** [Authentication](/api/authentication)
Integrate with our API to create a secure token to represent a customer’s payment details. There are two ways to save the payment details in our vault and get a secure token:
- Save the payment details when running a sale.
- Save the payment details without running a sale.
When you create your request, you can assign an ID to the secure token. If you don’t, our gateway assigns an ID to the secure token. We return the secureTokenID and the token in the response, which the merchant uses in follow-on transactions, including:
- Create a payment with [card details](/api/payment) or [bank account details](/api/bank-transfer-payment).
- Create a refund with [card details](/api/refund-payment) or [bank account details](/api/refund-bank-transfer-payment).
- [Look up BIN information](/api/bin-lookup).
**Note:** For more information about secure tokens, go to [Tokenization](/knowledge/payments/tokenization).
## Before you begin
[Authenticate your requests](/api/authentication) before making API calls. If your request fails, see [Errors](/api/errors).
## Run a sale and save payment details
To run a sale and save the payment details, send a Create a Payment request. In the request, include a credentialOnFile object and set the tokenize parameter to true.
Our gateway runs the sale and saves the customer’s payment details in our vault. In the response, we return a secureTokenId and the token that the merchant can use for follow-on transactions.
Note: For more information about how to run a sale, go to [Run a card sale](/guides/payments/run-a-card-sale) or [Run a sale with bank account details](/guides/payments/run-sale-using-bank-details).
## Save payment details
To save a customer’s payment details without running a sale, send a POST request to:
| Environment | URL |
| --- | --- |
| Test | [https://api.uat.payroc.com/v1/processing-terminals/\{processingTerminalId\}/secure-tokens](https://api.uat.payroc.com/v1/processing-terminals/%7BprocessingTerminalId%7D/secure-tokens) |
| Production | [https://api.payroc.com/v1/processing-terminals/\{processingTerminalId\}/secure-tokens](https://api.payroc.com/v1/processing-terminals/%7BprocessingTerminalId%7D/secure-tokens) |
### Request parameters
To create the body of your request, use the following parameters:
### Schema (`request.body`)
[Request body schema for `POST /processing-terminals/{processingTerminalId}/secure-tokens`](/api/create-secure-token)
### Example request
### Request
POST [https://api.payroc.com/v1/processing-terminals/\{processingTerminalId\}/secure-tokens](https://api.payroc.com/v1/processing-terminals/%7BprocessingTerminalId%7D/secure-tokens)
**`Secure Token`**
```curl
curl -X POST https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens \
-H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"source": {
"type": "card",
"cardDetails": {
"entryMethod": "keyed",
"keyedData": {
"dataFormat": "plainText",
"cardNumber": "4539858876047062",
"cvv": "234",
"expiryDate": "1230"
},
"cardholderName": "Sarah Hazel Hopper"
}
},
"operator": "Jane",
"mitAgreement": "unscheduled",
"customer": {
"firstName": "Sarah",
"lastName": "Hopper",
"dateOfBirth": "1990-07-15",
"referenceNumber": "Customer-12",
"billingAddress": {
"address1": "1 Example Ave.",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3"
},
"shippingAddress": {
"recipientName": "Sarah Hopper",
"address": {
"address1": "1 Example Ave.",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3"
}
},
"contactMethods": [
{
"type": "email",
"value": "sarah.hopper@example.com"
}
],
"notificationLanguage": "en"
},
"ipAddress": {
"type": "ipv4",
"value": "104.18.24.203"
},
"customFields": [
{
"name": "yourCustomField",
"value": "abc123"
}
]
}'
```
**`Secure Token`**
```python
import requests
url = "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens"
payload = {
"source": {
"type": "card",
"cardDetails": {
"entryMethod": "keyed",
"keyedData": {
"dataFormat": "plainText",
"cardNumber": "4539858876047062",
"cvv": "234",
"expiryDate": "1230"
},
"cardholderName": "Sarah Hazel Hopper"
}
},
"operator": "Jane",
"mitAgreement": "unscheduled",
"customer": {
"firstName": "Sarah",
"lastName": "Hopper",
"dateOfBirth": "1990-07-15",
"referenceNumber": "Customer-12",
"billingAddress": {
"address1": "1 Example Ave.",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3"
},
"shippingAddress": {
"recipientName": "Sarah Hopper",
"address": {
"address1": "1 Example Ave.",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3"
}
},
"contactMethods": [
{
"type": "email",
"value": "sarah.hopper@example.com"
}
],
"notificationLanguage": "en"
},
"ipAddress": {
"type": "ipv4",
"value": "104.18.24.203"
},
"customFields": [
{
"name": "yourCustomField",
"value": "abc123"
}
]
}
headers = {
"Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
"Authorization": "Bearer ",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
**`Secure Token`**
```javascript
const url = 'https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens';
const options = {
method: 'POST',
headers: {
'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324',
Authorization: 'Bearer ',
'Content-Type': 'application/json'
},
body: '{"source":{"type":"card","cardDetails":{"entryMethod":"keyed","keyedData":{"dataFormat":"plainText","cardNumber":"4539858876047062","cvv":"234","expiryDate":"1230"},"cardholderName":"Sarah Hazel Hopper"}},"operator":"Jane","mitAgreement":"unscheduled","customer":{"firstName":"Sarah","lastName":"Hopper","dateOfBirth":"1990-07-15","referenceNumber":"Customer-12","billingAddress":{"address1":"1 Example Ave.","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056","address2":"Example Address Line 2","address3":"Example Address Line 3"},"shippingAddress":{"recipientName":"Sarah Hopper","address":{"address1":"1 Example Ave.","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056","address2":"Example Address Line 2","address3":"Example Address Line 3"}},"contactMethods":[{"type":"email","value":"sarah.hopper@example.com"}],"notificationLanguage":"en"},"ipAddress":{"type":"ipv4","value":"104.18.24.203"},"customFields":[{"name":"yourCustomField","value":"abc123"}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
```
**`Secure Token`**
```go
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens"
payload := strings.NewReader("{\n \"source\": {\n \"type\": \"card\",\n \"cardDetails\": {\n \"entryMethod\": \"keyed\",\n \"keyedData\": {\n \"dataFormat\": \"plainText\",\n \"cardNumber\": \"4539858876047062\",\n \"cvv\": \"234\",\n \"expiryDate\": \"1230\"\n },\n \"cardholderName\": \"Sarah Hazel Hopper\"\n }\n },\n \"operator\": \"Jane\",\n \"mitAgreement\": \"unscheduled\",\n \"customer\": {\n \"firstName\": \"Sarah\",\n \"lastName\": \"Hopper\",\n \"dateOfBirth\": \"1990-07-15\",\n \"referenceNumber\": \"Customer-12\",\n \"billingAddress\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n },\n \"shippingAddress\": {\n \"recipientName\": \"Sarah Hopper\",\n \"address\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n }\n },\n \"contactMethods\": [\n {\n \"type\": \"email\",\n \"value\": \"sarah.hopper@example.com\"\n }\n ],\n \"notificationLanguage\": \"en\"\n },\n \"ipAddress\": {\n \"type\": \"ipv4\",\n \"value\": \"104.18.24.203\"\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
req.Header.Add("Authorization", "Bearer ")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
```
**`Secure Token`**
```ruby
require 'uri'
require 'net/http'
url = URI("https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '8e03978e-40d5-43e8-bc93-6894a57f9324'
request["Authorization"] = 'Bearer '
request["Content-Type"] = 'application/json'
request.body = "{\n \"source\": {\n \"type\": \"card\",\n \"cardDetails\": {\n \"entryMethod\": \"keyed\",\n \"keyedData\": {\n \"dataFormat\": \"plainText\",\n \"cardNumber\": \"4539858876047062\",\n \"cvv\": \"234\",\n \"expiryDate\": \"1230\"\n },\n \"cardholderName\": \"Sarah Hazel Hopper\"\n }\n },\n \"operator\": \"Jane\",\n \"mitAgreement\": \"unscheduled\",\n \"customer\": {\n \"firstName\": \"Sarah\",\n \"lastName\": \"Hopper\",\n \"dateOfBirth\": \"1990-07-15\",\n \"referenceNumber\": \"Customer-12\",\n \"billingAddress\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n },\n \"shippingAddress\": {\n \"recipientName\": \"Sarah Hopper\",\n \"address\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n }\n },\n \"contactMethods\": [\n {\n \"type\": \"email\",\n \"value\": \"sarah.hopper@example.com\"\n }\n ],\n \"notificationLanguage\": \"en\"\n },\n \"ipAddress\": {\n \"type\": \"ipv4\",\n \"value\": \"104.18.24.203\"\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body
```
**`Secure Token`**
```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse response = Unirest.post("https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens")
.header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
.header("Authorization", "Bearer ")
.header("Content-Type", "application/json")
.body("{\n \"source\": {\n \"type\": \"card\",\n \"cardDetails\": {\n \"entryMethod\": \"keyed\",\n \"keyedData\": {\n \"dataFormat\": \"plainText\",\n \"cardNumber\": \"4539858876047062\",\n \"cvv\": \"234\",\n \"expiryDate\": \"1230\"\n },\n \"cardholderName\": \"Sarah Hazel Hopper\"\n }\n },\n \"operator\": \"Jane\",\n \"mitAgreement\": \"unscheduled\",\n \"customer\": {\n \"firstName\": \"Sarah\",\n \"lastName\": \"Hopper\",\n \"dateOfBirth\": \"1990-07-15\",\n \"referenceNumber\": \"Customer-12\",\n \"billingAddress\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n },\n \"shippingAddress\": {\n \"recipientName\": \"Sarah Hopper\",\n \"address\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n }\n },\n \"contactMethods\": [\n {\n \"type\": \"email\",\n \"value\": \"sarah.hopper@example.com\"\n }\n ],\n \"notificationLanguage\": \"en\"\n },\n \"ipAddress\": {\n \"type\": \"ipv4\",\n \"value\": \"104.18.24.203\"\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}")
.asString();
```
**`Secure Token`**
```php
request('POST', 'https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens', [
'body' => '{
"source": {
"type": "card",
"cardDetails": {
"entryMethod": "keyed",
"keyedData": {
"dataFormat": "plainText",
"cardNumber": "4539858876047062",
"cvv": "234",
"expiryDate": "1230"
},
"cardholderName": "Sarah Hazel Hopper"
}
},
"operator": "Jane",
"mitAgreement": "unscheduled",
"customer": {
"firstName": "Sarah",
"lastName": "Hopper",
"dateOfBirth": "1990-07-15",
"referenceNumber": "Customer-12",
"billingAddress": {
"address1": "1 Example Ave.",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3"
},
"shippingAddress": {
"recipientName": "Sarah Hopper",
"address": {
"address1": "1 Example Ave.",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3"
}
},
"contactMethods": [
{
"type": "email",
"value": "sarah.hopper@example.com"
}
],
"notificationLanguage": "en"
},
"ipAddress": {
"type": "ipv4",
"value": "104.18.24.203"
},
"customFields": [
{
"name": "yourCustomField",
"value": "abc123"
}
]
}',
'headers' => [
'Authorization' => 'Bearer ',
'Content-Type' => 'application/json',
'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
],
]);
echo $response->getBody();
```
**`Secure Token`**
```csharp
using RestSharp;
var client = new RestClient("https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324");
request.AddHeader("Authorization", "Bearer ");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"source\": {\n \"type\": \"card\",\n \"cardDetails\": {\n \"entryMethod\": \"keyed\",\n \"keyedData\": {\n \"dataFormat\": \"plainText\",\n \"cardNumber\": \"4539858876047062\",\n \"cvv\": \"234\",\n \"expiryDate\": \"1230\"\n },\n \"cardholderName\": \"Sarah Hazel Hopper\"\n }\n },\n \"operator\": \"Jane\",\n \"mitAgreement\": \"unscheduled\",\n \"customer\": {\n \"firstName\": \"Sarah\",\n \"lastName\": \"Hopper\",\n \"dateOfBirth\": \"1990-07-15\",\n \"referenceNumber\": \"Customer-12\",\n \"billingAddress\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n },\n \"shippingAddress\": {\n \"recipientName\": \"Sarah Hopper\",\n \"address\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n }\n },\n \"contactMethods\": [\n {\n \"type\": \"email\",\n \"value\": \"sarah.hopper@example.com\"\n }\n ],\n \"notificationLanguage\": \"en\"\n },\n \"ipAddress\": {\n \"type\": \"ipv4\",\n \"value\": \"104.18.24.203\"\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```
**`Secure Token`**
```swift
import Foundation
let headers = [
"Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
"Authorization": "Bearer ",
"Content-Type": "application/json"
]
let parameters = [
"source": [
"type": "card",
"cardDetails": [
"entryMethod": "keyed",
"keyedData": [
"dataFormat": "plainText",
"cardNumber": "4539858876047062",
"cvv": "234",
"expiryDate": "1230"
],
"cardholderName": "Sarah Hazel Hopper"
]
],
"operator": "Jane",
"mitAgreement": "unscheduled",
"customer": [
"firstName": "Sarah",
"lastName": "Hopper",
"dateOfBirth": "1990-07-15",
"referenceNumber": "Customer-12",
"billingAddress": [
"address1": "1 Example Ave.",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3"
],
"shippingAddress": [
"recipientName": "Sarah Hopper",
"address": [
"address1": "1 Example Ave.",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3"
]
],
"contactMethods": [
[
"type": "email",
"value": "sarah.hopper@example.com"
]
],
"notificationLanguage": "en"
],
"ipAddress": [
"type": "ipv4",
"value": "104.18.24.203"
],
"customFields": [
[
"name": "yourCustomField",
"value": "abc123"
]
]
] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```
### Response fields
If your request is successful, we return a token that you can use instead of the customer’s payment details in follow-on transactions.
### Schema (`response.body`)
[Response body schema for `POST /processing-terminals/{processingTerminalId}/secure-tokens`](/api/create-secure-token)
### Example response
### Response (201)
```json
{
"secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
"processingTerminalId": "1234001",
"source": {
"type": "card",
"cardNumber": "453985******7062",
"cardholderName": "Sarah Hazel Hopper",
"expiryDate": "1230"
},
"token": "296753123456",
"status": "notValidated",
"mitAgreement": "unscheduled",
"customer": {
"firstName": "Sarah",
"lastName": "Hopper",
"dateOfBirth": "1990-07-15",
"referenceNumber": "Customer-12",
"billingAddress": {
"address1": "1 Example Ave.",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"shippingAddress": {
"recipientName": "Sarah Hopper",
"address": {
"address1": "1 Example Ave.",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
}
},
"contactMethods": [
{
"type": "email",
"value": "sarah.hopper@example.com"
}
],
"notificationLanguage": "en"
},
"customFields": [
{
"name": "yourCustomField",
"value": "abc123"
}
]
}
```