Skip to content
payrocdevelopers

Save payment details when running a sale

Save card or bank account payment details when running a sale by sending a POST request to the Payments or Bank Transfer Payments endpoint with a credentialOnFile object.

Prerequisites: Authentication · Run a sale

Save payment details when running a sale

You can use the single-use token from your existing Hosted Fields integration to save a customer's payment details at the same time that you run a sale.

If you save a customer's payment details during a sale, our gateway uses the single-use token from Hosted Fields to charge the customer, and then saves the customer's payment details as a secure token. You can use the secure token multiple times, and it doesn't expire.

To tokenize payment details during a sale, you need to send some additional parameters in your request to our API. You don't need to change the JavaScript configuration or authentication for your existing Hosted Fields integration.

Before you begin

Make sure that you've set up your Hosted Fields integration to run a sale with the single-use token from the submissionSuccess event. For more information, go to Run a sale.

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

Integration steps

The steps that you need to follow depend on whether your single-use token represents card details or bank account details:

Save card details when you run a sale

To run a sale and tokenize the card details, you need to update your POST request to our Payments endpoint.

EnvironmentURL
Testhttps://api.uat.payroc.com/v1/payments
Productionhttps://api.payroc.com/v1/payments

Request parameters

Important: The request includes parameters for functions and features that we don't cover in this guide. These functions and features might require additional integration effort and cost. For more information, contact our Integrations Team at integrationsupport@payroc.com.

To save a customer's card details when you run a sale, update your request to our Payments endpoint. Send the single-use token from Hosted Fields in the paymentMethod object, and include the following parameters in the credentialOnFile object:

  • tokenize - Send a value of true.
  • secureTokenId - Assign a unique identifier to the secure token.

Note: If you want to use the stored payment details to run repeat payments with your own software, include the standingInstructions object in your request. For more information about repeat payments with Hosted Fields, go to Repeat payments with Hosted Fields.

Schema (request.body)

Request body schema for POST /payments

Example request

Request

POST https://api.payroc.com/v1/payments

Card sale with single-use token that we convert to a secure token

curl
curl -X POST https://api.payroc.com/v1/payments \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "channel": "web",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "amount": 4999,
    "currency": "USD",
    "description": "Large Pepperoni Pizza"
  },
  "paymentMethod": {
    "type": "singleUseToken",
    "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  },
  "operator": "Jane",
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "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"
      }
    }
  },
  "credentialOnFile": {
    "tokenize": true,
    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}'

Card sale with single-use token that we convert to a secure token

Python
import requests

url = "https://api.payroc.com/v1/payments"

payload = {
    "channel": "web",
    "processingTerminalId": "1234001",
    "order": {
        "orderId": "OrderRef6543",
        "amount": 4999,
        "currency": "USD",
        "description": "Large Pepperoni Pizza"
    },
    "paymentMethod": {
        "type": "singleUseToken",
        "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
    },
    "operator": "Jane",
    "customer": {
        "firstName": "Sarah",
        "lastName": "Hopper",
        "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"
            }
        }
    },
    "credentialOnFile": {
        "tokenize": True,
        "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
    },
    "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())

Card sale with single-use token that we convert to a secure token

JavaScript
const url = 'https://api.payroc.com/v1/payments';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"channel":"web","processingTerminalId":"1234001","order":{"orderId":"OrderRef6543","amount":4999,"currency":"USD","description":"Large Pepperoni Pizza"},"paymentMethod":{"type":"singleUseToken","token":"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"},"operator":"Jane","customer":{"firstName":"Sarah","lastName":"Hopper","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"}}},"credentialOnFile":{"tokenize":true,"secureTokenId":"MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"},"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);
}

Card sale with single-use token that we convert to a secure token

go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payroc.com/v1/payments"

	payload := strings.NewReader("{\n  \"channel\": \"web\",\n  \"processingTerminalId\": \"1234001\",\n  \"order\": {\n    \"orderId\": \"OrderRef6543\",\n    \"amount\": 4999,\n    \"currency\": \"USD\",\n    \"description\": \"Large Pepperoni Pizza\"\n  },\n  \"paymentMethod\": {\n    \"type\": \"singleUseToken\",\n    \"token\": \"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\"\n  },\n  \"operator\": \"Jane\",\n  \"customer\": {\n    \"firstName\": \"Sarah\",\n    \"lastName\": \"Hopper\",\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  },\n  \"credentialOnFile\": {\n    \"tokenize\": true,\n    \"secureTokenId\": \"MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa\"\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))

}

Card sale with single-use token that we convert to a secure token

ruby
require 'uri'
require 'net/http'

url = URI("https://api.payroc.com/v1/payments")

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  \"channel\": \"web\",\n  \"processingTerminalId\": \"1234001\",\n  \"order\": {\n    \"orderId\": \"OrderRef6543\",\n    \"amount\": 4999,\n    \"currency\": \"USD\",\n    \"description\": \"Large Pepperoni Pizza\"\n  },\n  \"paymentMethod\": {\n    \"type\": \"singleUseToken\",\n    \"token\": \"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\"\n  },\n  \"operator\": \"Jane\",\n  \"customer\": {\n    \"firstName\": \"Sarah\",\n    \"lastName\": \"Hopper\",\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  },\n  \"credentialOnFile\": {\n    \"tokenize\": true,\n    \"secureTokenId\": \"MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa\"\n  },\n  \"customFields\": [\n    {\n      \"name\": \"yourCustomField\",\n      \"value\": \"abc123\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

Card sale with single-use token that we convert to a 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/payments")
  .header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"channel\": \"web\",\n  \"processingTerminalId\": \"1234001\",\n  \"order\": {\n    \"orderId\": \"OrderRef6543\",\n    \"amount\": 4999,\n    \"currency\": \"USD\",\n    \"description\": \"Large Pepperoni Pizza\"\n  },\n  \"paymentMethod\": {\n    \"type\": \"singleUseToken\",\n    \"token\": \"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\"\n  },\n  \"operator\": \"Jane\",\n  \"customer\": {\n    \"firstName\": \"Sarah\",\n    \"lastName\": \"Hopper\",\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  },\n  \"credentialOnFile\": {\n    \"tokenize\": true,\n    \"secureTokenId\": \"MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa\"\n  },\n  \"customFields\": [\n    {\n      \"name\": \"yourCustomField\",\n      \"value\": \"abc123\"\n    }\n  ]\n}")
  .asString();

Card sale with single-use token that we convert to a secure token

PHP
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.payroc.com/v1/payments', [
  'body' => '{
  "channel": "web",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "amount": 4999,
    "currency": "USD",
    "description": "Large Pepperoni Pizza"
  },
  "paymentMethod": {
    "type": "singleUseToken",
    "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  },
  "operator": "Jane",
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "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"
      }
    }
  },
  "credentialOnFile": {
    "tokenize": true,
    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
  ],
]);

echo $response->getBody();

Card sale with single-use token that we convert to a secure token

C#
using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/payments");
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  \"channel\": \"web\",\n  \"processingTerminalId\": \"1234001\",\n  \"order\": {\n    \"orderId\": \"OrderRef6543\",\n    \"amount\": 4999,\n    \"currency\": \"USD\",\n    \"description\": \"Large Pepperoni Pizza\"\n  },\n  \"paymentMethod\": {\n    \"type\": \"singleUseToken\",\n    \"token\": \"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\"\n  },\n  \"operator\": \"Jane\",\n  \"customer\": {\n    \"firstName\": \"Sarah\",\n    \"lastName\": \"Hopper\",\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  },\n  \"credentialOnFile\": {\n    \"tokenize\": true,\n    \"secureTokenId\": \"MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa\"\n  },\n  \"customFields\": [\n    {\n      \"name\": \"yourCustomField\",\n      \"value\": \"abc123\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Card sale with single-use token that we convert to a secure token

swift
import Foundation

let headers = [
  "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "channel": "web",
  "processingTerminalId": "1234001",
  "order": [
    "orderId": "OrderRef6543",
    "amount": 4999,
    "currency": "USD",
    "description": "Large Pepperoni Pizza"
  ],
  "paymentMethod": [
    "type": "singleUseToken",
    "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  ],
  "operator": "Jane",
  "customer": [
    "firstName": "Sarah",
    "lastName": "Hopper",
    "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"
      ]
    ]
  ],
  "credentialOnFile": [
    "tokenize": true,
    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
  ],
  "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/payments")! 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, our gateway runs the sale and converts the single-use token into a secure token that we return in the response. You need to store the token so that you can use it in follow-up requests.

The response also contains the following fields:

Schema (response.body)

Response body schema for POST /payments

Example response

Response (201)

JSON
{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "order": {
    "orderId": "OrderRef6543",
    "amount": 4999,
    "currency": "USD",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza"
  },
  "card": {
    "type": "Visa Credit",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1230",
    "cardholderName": "Sarah Hopper",
    "secureToken": {
      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
      "customerName": "Sarah Hopper",
      "token": "296753123456",
      "status": "notValidated",
      "link": {
        "rel": "self",
        "method": "GET",
        "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
      }
    },
    "securityChecks": {
      "cvvResult": "M",
      "avsResult": "Y"
    }
  },
  "transactionResult": {
    "status": "ready",
    "responseCode": "A",
    "type": "sale",
    "approvalCode": "OK3",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseMessage": "OK3",
    "cardSchemeReferenceId": "ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"
  },
  "operator": "Jane",
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "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"
      }
    }
  },
  "supportedOperations": [
    "capture",
    "fullyReverse",
    "partiallyReverse",
    "incrementAuthorization",
    "adjustTip",
    "setAsPending"
  ],
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

Save bank account details when you run a sale

To run a sale and tokenize the bank account details, you need to update your POST request to our Bank Transfer Payments endpoint.

EnvironmentURL
Testhttps://api.uat.payroc.com/v1/bank-transfer-payments
Productionhttps://api.payroc.com/v1/bank-transfer-payments

Request parameters

Important: The request includes parameters for functions and features that we don't cover in this guide. These functions and features might require additional integration effort and cost. For more information, contact our Integrations Team at integrationsupport@payroc.com.

To save a customer's bank account details when you run a sale, update your request to our Bank Transfer Payments endpoint. Send the single-use token from Hosted Fields in the paymentMethod object, and include the following parameters in the credentialOnFile object:

  • tokenize - Send a value of true.
  • secureTokenId - Assign a unique identifier to the secure token.

Schema (request.body)

Request body schema for POST /bank-transfer-payments

Example request

Request

POST https://api.payroc.com/v1/bank-transfer-payments

Bank transfer sale with single-use token that we convert to a secure token

curl
curl -X POST https://api.payroc.com/v1/bank-transfer-payments \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "processingTerminalId": "1234001",
  "order": {
    "amount": 4999,
    "currency": "USD",
    "orderId": "OrderRef6543",
    "description": "Large Pepperoni Pizza"
  },
  "paymentMethod": {
    "type": "singleUseToken",
    "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "accountType": "checking",
    "secCode": "web"
  },
  "customer": {
    "notificationLanguage": "en",
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ]
  },
  "credentialOnFile": {
    "tokenize": true,
    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}'

Bank transfer sale with single-use token that we convert to a secure token

Python
import requests

url = "https://api.payroc.com/v1/bank-transfer-payments"

payload = {
    "processingTerminalId": "1234001",
    "order": {
        "amount": 4999,
        "currency": "USD",
        "orderId": "OrderRef6543",
        "description": "Large Pepperoni Pizza"
    },
    "paymentMethod": {
        "type": "singleUseToken",
        "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "accountType": "checking",
        "secCode": "web"
    },
    "customer": {
        "notificationLanguage": "en",
        "contactMethods": [
            {
                "type": "email",
                "value": "sarah.hopper@example.com"
            }
        ]
    },
    "credentialOnFile": {
        "tokenize": True,
        "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
    },
    "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())

Bank transfer sale with single-use token that we convert to a secure token

JavaScript
const url = 'https://api.payroc.com/v1/bank-transfer-payments';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"processingTerminalId":"1234001","order":{"amount":4999,"currency":"USD","orderId":"OrderRef6543","description":"Large Pepperoni Pizza"},"paymentMethod":{"type":"singleUseToken","token":"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890","accountType":"checking","secCode":"web"},"customer":{"notificationLanguage":"en","contactMethods":[{"type":"email","value":"sarah.hopper@example.com"}]},"credentialOnFile":{"tokenize":true,"secureTokenId":"MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"},"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);
}

Bank transfer sale with single-use token that we convert to a secure token

go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payroc.com/v1/bank-transfer-payments"

	payload := strings.NewReader("{\n  \"processingTerminalId\": \"1234001\",\n  \"order\": {\n    \"amount\": 4999,\n    \"currency\": \"USD\",\n    \"orderId\": \"OrderRef6543\",\n    \"description\": \"Large Pepperoni Pizza\"\n  },\n  \"paymentMethod\": {\n    \"type\": \"singleUseToken\",\n    \"token\": \"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\",\n    \"accountType\": \"checking\",\n    \"secCode\": \"web\"\n  },\n  \"customer\": {\n    \"notificationLanguage\": \"en\",\n    \"contactMethods\": [\n      {\n        \"type\": \"email\",\n        \"value\": \"sarah.hopper@example.com\"\n      }\n    ]\n  },\n  \"credentialOnFile\": {\n    \"tokenize\": true,\n    \"secureTokenId\": \"MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa\"\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))

}

Bank transfer sale with single-use token that we convert to a secure token

ruby
require 'uri'
require 'net/http'

url = URI("https://api.payroc.com/v1/bank-transfer-payments")

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  \"processingTerminalId\": \"1234001\",\n  \"order\": {\n    \"amount\": 4999,\n    \"currency\": \"USD\",\n    \"orderId\": \"OrderRef6543\",\n    \"description\": \"Large Pepperoni Pizza\"\n  },\n  \"paymentMethod\": {\n    \"type\": \"singleUseToken\",\n    \"token\": \"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\",\n    \"accountType\": \"checking\",\n    \"secCode\": \"web\"\n  },\n  \"customer\": {\n    \"notificationLanguage\": \"en\",\n    \"contactMethods\": [\n      {\n        \"type\": \"email\",\n        \"value\": \"sarah.hopper@example.com\"\n      }\n    ]\n  },\n  \"credentialOnFile\": {\n    \"tokenize\": true,\n    \"secureTokenId\": \"MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa\"\n  },\n  \"customFields\": [\n    {\n      \"name\": \"yourCustomField\",\n      \"value\": \"abc123\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

Bank transfer sale with single-use token that we convert to a 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/bank-transfer-payments")
  .header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"processingTerminalId\": \"1234001\",\n  \"order\": {\n    \"amount\": 4999,\n    \"currency\": \"USD\",\n    \"orderId\": \"OrderRef6543\",\n    \"description\": \"Large Pepperoni Pizza\"\n  },\n  \"paymentMethod\": {\n    \"type\": \"singleUseToken\",\n    \"token\": \"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\",\n    \"accountType\": \"checking\",\n    \"secCode\": \"web\"\n  },\n  \"customer\": {\n    \"notificationLanguage\": \"en\",\n    \"contactMethods\": [\n      {\n        \"type\": \"email\",\n        \"value\": \"sarah.hopper@example.com\"\n      }\n    ]\n  },\n  \"credentialOnFile\": {\n    \"tokenize\": true,\n    \"secureTokenId\": \"MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa\"\n  },\n  \"customFields\": [\n    {\n      \"name\": \"yourCustomField\",\n      \"value\": \"abc123\"\n    }\n  ]\n}")
  .asString();

Bank transfer sale with single-use token that we convert to a secure token

PHP
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.payroc.com/v1/bank-transfer-payments', [
  'body' => '{
  "processingTerminalId": "1234001",
  "order": {
    "amount": 4999,
    "currency": "USD",
    "orderId": "OrderRef6543",
    "description": "Large Pepperoni Pizza"
  },
  "paymentMethod": {
    "type": "singleUseToken",
    "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "accountType": "checking",
    "secCode": "web"
  },
  "customer": {
    "notificationLanguage": "en",
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ]
  },
  "credentialOnFile": {
    "tokenize": true,
    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
  ],
]);

echo $response->getBody();

Bank transfer sale with single-use token that we convert to a secure token

C#
using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/bank-transfer-payments");
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  \"processingTerminalId\": \"1234001\",\n  \"order\": {\n    \"amount\": 4999,\n    \"currency\": \"USD\",\n    \"orderId\": \"OrderRef6543\",\n    \"description\": \"Large Pepperoni Pizza\"\n  },\n  \"paymentMethod\": {\n    \"type\": \"singleUseToken\",\n    \"token\": \"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\",\n    \"accountType\": \"checking\",\n    \"secCode\": \"web\"\n  },\n  \"customer\": {\n    \"notificationLanguage\": \"en\",\n    \"contactMethods\": [\n      {\n        \"type\": \"email\",\n        \"value\": \"sarah.hopper@example.com\"\n      }\n    ]\n  },\n  \"credentialOnFile\": {\n    \"tokenize\": true,\n    \"secureTokenId\": \"MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa\"\n  },\n  \"customFields\": [\n    {\n      \"name\": \"yourCustomField\",\n      \"value\": \"abc123\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Bank transfer sale with single-use token that we convert to a secure token

swift
import Foundation

let headers = [
  "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "processingTerminalId": "1234001",
  "order": [
    "amount": 4999,
    "currency": "USD",
    "orderId": "OrderRef6543",
    "description": "Large Pepperoni Pizza"
  ],
  "paymentMethod": [
    "type": "singleUseToken",
    "token": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "accountType": "checking",
    "secCode": "web"
  ],
  "customer": [
    "notificationLanguage": "en",
    "contactMethods": [
      [
        "type": "email",
        "value": "sarah.hopper@example.com"
      ]
    ]
  ],
  "credentialOnFile": [
    "tokenize": true,
    "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
  ],
  "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/bank-transfer-payments")! 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, our gateway runs the sale and converts the single-use token into a secure token that we return in the response. You need to store the token so that you can use it in follow-up requests.

The response also contains the following fields:

Schema (response.body)

Response body schema for POST /bank-transfer-payments

Example response

Response (201)

JSON
{
  "paymentId": "E29U8OU8Q4",
  "processingTerminalId": "1234001",
  "order": {
    "amount": 4999,
    "currency": "USD",
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza"
  },
  "bankAccount": {
    "type": "ach",
    "accountNumber": "****1591",
    "nameOnAccount": "Sarah Hazel Hopper",
    "routingNumber": "063100277",
    "secCode": "web",
    "secureToken": {
      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
      "customerName": "Sarah Hazel Hopper",
      "token": "296753123456",
      "status": "notValidated",
      "link": {
        "rel": "self",
        "method": "GET",
        "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa"
      }
    }
  },
  "transactionResult": {
    "type": "payment",
    "status": "ready",
    "responseCode": "A",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseMessage": "NoError",
    "processorResponseCode": "0"
  },
  "customer": {
    "notificationLanguage": "en",
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ]
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

Using the secure token

After you receive the secure token that represents the customer's payment details, you can use it in follow-up requests to our API, including:

Note: You can also use the secure token to set up repeat payments with our gateway, which requires more integration effort and cost. For more information, contact our Integrations Team at integrationsupport@payroc.com.

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