Skip to content
payrocdevelopers

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

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:

Note: For more information about secure tokens, go to Tokenization.

Before you begin

Authenticate your requests before making API calls. If your request fails, see 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 or Run a sale with bank account details.

Save payment details

To save a customer’s payment details without running a sale, send a POST request to:

EnvironmentURL
Testhttps://api.uat.payroc.com/v1/processing-terminals/{processingTerminalId}/secure-tokens
Productionhttps://api.payroc.com/v1/processing-terminals/{processingTerminalId}/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

Example request

Request

POST https://api.payroc.com/v1/processing-terminals/{processingTerminalId}/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 <token>" \
     -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 <token>",
    "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 <token>',
    '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 <token>")
	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 <token>'
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<String> response = Unirest.post("https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens")
  .header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
  .header("Authorization", "Bearer <token>")
  .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
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->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 <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
  ],
]);

echo $response->getBody();

Secure Token

C#
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 <token>");
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 <token>",
  "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

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"
    }
  ]
}

Browse guides

Search documentation

API reference169
Guides118
Knowledge38
legal1
Solutions32
Workflows74
↑↓highlight↵openView all search results

Menu

Theme

Sign out

Your saved plans remain in your organization. This browser’s private draft and account view will be cleared.

Talk to an engineer