# 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](/api/authentication) · [Run a sale](/guides/payments/hosted-fields/run-a-sale)

<a id="save-payment-details-when-running-a-sale"></a>
## 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.

<a id="before-you-begin"></a>
## 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](/guides/payments/hosted-fields/run-a-sale).

[Authenticate your requests](/api/authentication) before making API calls. If your request fails, see [Errors](/api/errors).

<a id="integration-steps"></a>
## Integration steps

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

- If the single-use token represents card details, go to [Save card details when you run a sale](#save-card-details-when-you-run-a-sale).
- If the single-use token represents bank account details, go to [Save bank account details when you run a sale](#save-bank-account-details-when-you-run-a-sale).

<a id="save-card-details-when-you-run-a-sale"></a>
## 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.

| Environment | URL |
| --- | --- |
| Test | [https://api.uat.payroc.com/v1/payments](https://api.uat.payroc.com/v1/payments) |
| Production | [https://api.payroc.com/v1/payments](https://api.payroc.com/v1/payments) |

<a id="request-parameters"></a>
### 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](mailto: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](/guides/payments/hosted-fields/repeat-payments-with-hosted-fields).

<a id="schema-requestbody"></a>
### Schema (`request.body`)

[Request body schema for `POST /payments`](/api/payment)

<a id="example-request"></a>
### Example request

<a id="request"></a>
### Request

POST [https://api.payroc.com/v1/payments](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`**

```csharp
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()
```

<a id="response-fields"></a>
### 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:

<a id="schema-responsebody"></a>
### Schema (`response.body`)

[Response body schema for `POST /payments`](/api/payment)

<a id="example-response"></a>
### Example response

<a id="response-201"></a>
### 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"
    }
  ]
}
```

<a id="save-bank-account-details-when-you-run-a-sale"></a>
## 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.

| Environment | URL |
| --- | --- |
| Test | [https://api.uat.payroc.com/v1/bank-transfer-payments](https://api.uat.payroc.com/v1/bank-transfer-payments) |
| Production | [https://api.payroc.com/v1/bank-transfer-payments](https://api.payroc.com/v1/bank-transfer-payments) |

<a id="request-parameters-1"></a>
### 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](mailto: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.

<a id="schema-requestbody-1"></a>
### Schema (`request.body`)

[Request body schema for `POST /bank-transfer-payments`](/api/bank-transfer-payment)

<a id="example-request-1"></a>
### Example request

<a id="request-1"></a>
### Request

POST [https://api.payroc.com/v1/bank-transfer-payments](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`**

```csharp
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()
```

<a id="response-fields-1"></a>
### 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:

<a id="schema-responsebody-1"></a>
### Schema (`response.body`)

[Response body schema for `POST /bank-transfer-payments`](/api/bank-transfer-payment)

<a id="example-response-1"></a>
### Example response

<a id="response-201-1"></a>
### 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"
    }
  ]
}
```

<a id="using-the-secure-token"></a>
## 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:

- [Create a card payment](/guides/payments/run-a-card-sale)
- [Create a bank transfer payment](/guides/payments/run-sale-using-bank-details)
- [Update a customer's payment details with Hosted Fields](/guides/payments/hosted-fields/update-payment-details)

**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](mailto:integrationsupport@payroc.com).


---