> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://beta-docs.payabli.com/api-reference/tokenstorage/update-a-payment-method/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://beta-docs.payabli.com/_mcp/server.

# Update tokenized payment method

PUT https://api-sandbox.payabli.com/api/TokenStorage/{methodId}
Content-Type: application/json

Updates a saved payment method.

Reference: https://beta-docs.payabli.com/api-reference/tokenstorage/update-a-payment-method

## Authentication

- `requestToken` header (required) — API Key authentication via header

## Servers

- `https://api-sandbox.payabli.com/api` (Sandbox, default)
- `https://api.payabli.com/api` (Production)

## Request

### Path parameters

- `methodId` (string, required) — The saved payment method ID.

### Query parameters

- `achValidation` (boolean, optional) — When `true`, enables real-time validation of ACH account and routing numbers. This is an add-on feature, contact Payabli for more information.

### Body (application/json)

This endpoint expects a RequestTokenStorage.

- `customerData` (PayorData, optional) — Object describing the Customer/Payor owner of payment method. Required for POST requests. Which fields are required depends on the paypoint's custom identifier settings. See [PayorData Object Model](/api-reference/schemas/payordata) for a complete reference.
- `entryPoint` (string, optional) — Entrypoint identifier. Required for POST requests.
- `fallbackAuth` (boolean, optional, default: false) — When `true`, if tokenization fails, Payabli will attempt an authorization transaction to request a permanent token for the card. If the authorization is successful, the card will be tokenized and the authorization will be voided automatically.
- `fallbackAuthAmount` (integer, optional, default: 100) — The amount for the `fallbackAuth` transaction. Defaults to one dollar (`100`).
- `methodDescription` (string, optional) — Custom description for stored payment method.
- `paymentMethod` (RequestTokenStoragePaymentMethod, optional) — Information about the payment method for the transaction.
- `source` (string, optional) — Custom identifier to indicate the source for the request
- `subdomain` (string, optional) — Refers to the payment page identifier. If provided, then the transaction is linked to the payment page.

## Response

### 200

Success

- `isSuccess` (boolean, optional) — Boolean indicating whether the operation was successful. A `true` value indicates success. A `false` value indicates failure.
- `responseData` (PayabliApiResponsePaymethodDeleteResponseData, optional)
- `responseText` (string, optional) — Response text for operation: 'Success' or 'Declined'.

## Errors

### 400 Bad Request Error

Bad request/ invalid data

- `any`

### 401 Unauthorized Error

Unauthorized request.

- `any`

### 500 Internal Server Error

Internal API Error

- `any`

### 503 Service Unavailable Error

Database connection error

- `isSuccess` (boolean, optional) — Boolean indicating whether the operation was successful. A `true` value indicates success. A `false` value indicates failure.
- `responseData` (map from string to any, optional) — The object containing the response data.
- `responseText` (string, optional) — Response text for operation: 'Success' or 'Declined'.

## Types

### PayorData

Customer information. May be required, depending on the paypoint's settings. Required for subscriptions. See [PayorData object Model](/api-reference/schemas/payordata) for a complete reference.

- `additionalData` (map from string to map from string to any, optional) — Custom dictionary of key:value pairs. You can use this field to store any data related to the object or for your system. If you are using [custom identifiers](/developer-guides/entities-custom-identifiers), pass those in this object. Example usage: ```json { "additionalData": { "key1": "value1", "key2": "value2", "key3": "value3" } } ```
- `billingAddress1` (string, optional) — Billing address.
- `billingAddress2` (string, optional) — Additional line for the billing address.
- `billingCity` (string, optional) — Billing city.
- `billingCountry` (string, optional) — Billing address country.
- `billingEmail` (string, optional) — Email address.
- `billingPhone` (string, optional) — Phone number.
- `billingState` (string, optional) — Billing state. Must be 2-letter state code for address in US.
- `billingZip` (string, optional) — Customer's billing ZIP code. For Pay In functions, this field supports 5-digit and 9-digit ZIP codes and alphanumeric Canadian postal codes. For example: "37615-1234" or "37615".
- `company` (string, optional) — Customer's company name.
- `customerId` (long, optional) — The Payabli-generated unique ID for the customer.
- `customerNumber` (string, optional) — User-provided unique identifier for the customer. This is typically the customer ID from your own system.
- `firstName` (string, optional) — Customer/Payor first name.
- `identifierFields` (list of string, optional) — List of fields acting as customer identifiers, to be used instead of CustomerNumber.
- `lastName` (string, optional) — Customer/Payor last name.
- `shippingAddress1` (string, optional) — The shipping address.
- `shippingAddress2` (string, optional) — Additional line for shipping address.
- `shippingCity` (string, optional) — Shipping city.
- `shippingCountry` (string, optional) — Shipping address country.
- `shippingState` (string, optional) — Shipping state or province.
- `shippingZip` (string, optional) — Shipping ZIP code. For Pay In functions, this field supports 5-digit and 9-digit ZIP codes and alphanumeric Canadian postal codes. For example: "37615-1234" or "37615".

### RequestTokenStoragePaymentMethod

Information about the payment method for the transaction.

### PayabliApiResponsePaymethodDeleteResponseData

- `referenceId` (string, optional) — The method's reference ID.
- `resultCode` (integer, optional) — Result code for the operation. Value 1 indicates a successful operation, values 2 and 3 indicate errors. A value of 10 indicates that an operation has been initiated and is pending.
- `resultText` (string, optional) — Text describing the result. If `ResultCode` = 1, will return 'Approved' or a general success message. If `ResultCode`` = 2 or 3, will contain the cause of the error or decline.

### TokenizeCard

- `method` (string, required) — The type of payment method to tokenize. For cards, this is always `card`.
- `cardexp` (string, required) — Card expiration date in format MMYY or MM/YY. Required for card transactions.
- `cardHolder` (string, required) — Cardholder name.
- `cardnumber` (string, required) — The card number. Required when method is `card` and a `storedMethodId` isn't included.
- `cardcvv` (string, optional) — Card Verification Value (CVV) associated with the card number. We **strongly recommend** that you include this field when using `card` as a method.
- `cardzip` (string, optional) — ZIP code for the billing address of cardholder. We **strongly recommend** that you include this field when using `card` as a method.

### TokenizeACH

- `method` (string, required) — The type of payment method to tokenize. For ACH, this is always `ach`.
- `achAccount` (string, required) — Bank account number.
- `achAccountType` (enum, required) — Bank account type: Checking or Savings.
  - Allowed values: `Checking`, `Savings`
- `achHolder` (string, required) — Bank account holder. This field is **required** for `method` = 'ach' and `method` = 'check'.
- `achRouting` (string, required) — ABA/routing number of Bank account.
- `achCode` (string, optional) — Standard Entry Class (SEC) code is a a three letter code that describes how an ACH payment was authorized. Supported values are: - PPD (Prearranged Payment and Deposit) - Used for credits or debits where an accountholder authorizes a company to initiate either a single or recurring transaction to their personal bank account. Common examples include direct deposit of payroll, mortgage payments, or utility bills. This is the default value for subscription payments. - WEB (Internet-Initiated/Mobile Entry) - Used for debit entries when authorization is obtained from an accountholder via the internet or a wireless network. Common examples are online bill payments, ecommerce purchases, and mobile app payments where the consumer enters their banking information online. - TEL (Telephone-Initiated Entry) - Used for one-time debit entries where authorization is obtained from a consumer via telephone. Common examples are phone-based purchases or bill payments where the consumer provides their banking information over the phone. - CCD (Corporate Credit or Debit) - Used for fund transfers between business accounts. This code is specifically for business-to-business transactions. Common examples include vendor payments and other business-to-business payments.
- `achHolderType` (enum, optional, default: personal) — The bank's accountholder type: personal or business.
  - Allowed values: `personal`, `business`
- `device` (string, optional) — Identifier of registered cloud device used in the transaction.

### ConvertToken

Object containing the information needed to convert a temporary token to a permanent token.

- `method` (string, required) — The type of payment method to tokenize. When converting a temp token to a permanent token, this should match the `method` set for the temporary token, either `ach` or `card`.
- `tokenId` (string, required) — A temporary stored token ID to be converted to permanent.

## Examples

### UpdateCardMethod

**Request**

```json
{
  "customerData": {
    "customerId": 4440
  },
  "entryPoint": "f743aed24a",
  "fallbackAuth": true,
  "paymentMethod": {
    "cardcvv": "123",
    "cardexp": "02/25",
    "cardHolder": "John Doe",
    "cardnumber": "4111111111111111",
    "cardzip": "12345",
    "method": "card"
  }
}
```

**Response**

```json
{
  "isSuccess": true,
  "responseData": {
    "referenceId": "1b502b79-e319-4159-8c29-a9f8d9f105c8-1323",
    "resultCode": 1,
    "resultText": "Updated"
  },
  "responseText": "Success"
}
```

**SDK Code**

```python UpdateCardMethod
import requests

url = "https://api-sandbox.payabli.com/api/TokenStorage/32-8877drt00045632-678"

payload = {
    "customerData": { "customerId": 4440 },
    "entryPoint": "f743aed24a",
    "fallbackAuth": True,
    "paymentMethod": {
        "cardcvv": "123",
        "cardexp": "02/25",
        "cardHolder": "John Doe",
        "cardnumber": "4111111111111111",
        "cardzip": "12345",
        "method": "card"
    }
}
headers = {
    "requestToken": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript UpdateCardMethod
const url = 'https://api-sandbox.payabli.com/api/TokenStorage/32-8877drt00045632-678';
const options = {
  method: 'PUT',
  headers: {requestToken: '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"customerData":{"customerId":4440},"entryPoint":"f743aed24a","fallbackAuth":true,"paymentMethod":{"cardcvv":"123","cardexp":"02/25","cardHolder":"John Doe","cardnumber":"4111111111111111","cardzip":"12345","method":"card"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go UpdateCardMethod
package main

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

func main() {

	url := "https://api-sandbox.payabli.com/api/TokenStorage/32-8877drt00045632-678"

	payload := strings.NewReader("{\n  \"customerData\": {\n    \"customerId\": 4440\n  },\n  \"entryPoint\": \"f743aed24a\",\n  \"fallbackAuth\": true,\n  \"paymentMethod\": {\n    \"cardcvv\": \"123\",\n    \"cardexp\": \"02/25\",\n    \"cardHolder\": \"John Doe\",\n    \"cardnumber\": \"4111111111111111\",\n    \"cardzip\": \"12345\",\n    \"method\": \"card\"\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("requestToken", "<apiKey>")
	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))

}
```

```ruby UpdateCardMethod
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.payabli.com/api/TokenStorage/32-8877drt00045632-678")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["requestToken"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customerData\": {\n    \"customerId\": 4440\n  },\n  \"entryPoint\": \"f743aed24a\",\n  \"fallbackAuth\": true,\n  \"paymentMethod\": {\n    \"cardcvv\": \"123\",\n    \"cardexp\": \"02/25\",\n    \"cardHolder\": \"John Doe\",\n    \"cardnumber\": \"4111111111111111\",\n    \"cardzip\": \"12345\",\n    \"method\": \"card\"\n  }\n}"

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

```java UpdateCardMethod
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api-sandbox.payabli.com/api/TokenStorage/32-8877drt00045632-678")
  .header("requestToken", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerData\": {\n    \"customerId\": 4440\n  },\n  \"entryPoint\": \"f743aed24a\",\n  \"fallbackAuth\": true,\n  \"paymentMethod\": {\n    \"cardcvv\": \"123\",\n    \"cardexp\": \"02/25\",\n    \"cardHolder\": \"John Doe\",\n    \"cardnumber\": \"4111111111111111\",\n    \"cardzip\": \"12345\",\n    \"method\": \"card\"\n  }\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api-sandbox.payabli.com/api/TokenStorage/32-8877drt00045632-678', [
  'body' => '{
  "customerData": {
    "customerId": 4440
  },
  "entryPoint": "f743aed24a",
  "fallbackAuth": true,
  "paymentMethod": {
    "cardcvv": "123",
    "cardexp": "02/25",
    "cardHolder": "John Doe",
    "cardnumber": "4111111111111111",
    "cardzip": "12345",
    "method": "card"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'requestToken' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp UpdateCardMethod
using RestSharp;

var client = new RestClient("https://api-sandbox.payabli.com/api/TokenStorage/32-8877drt00045632-678");
var request = new RestRequest(Method.PUT);
request.AddHeader("requestToken", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"customerData\": {\n    \"customerId\": 4440\n  },\n  \"entryPoint\": \"f743aed24a\",\n  \"fallbackAuth\": true,\n  \"paymentMethod\": {\n    \"cardcvv\": \"123\",\n    \"cardexp\": \"02/25\",\n    \"cardHolder\": \"John Doe\",\n    \"cardnumber\": \"4111111111111111\",\n    \"cardzip\": \"12345\",\n    \"method\": \"card\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift UpdateCardMethod
import Foundation

let headers = [
  "requestToken": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "customerData": ["customerId": 4440],
  "entryPoint": "f743aed24a",
  "fallbackAuth": true,
  "paymentMethod": [
    "cardcvv": "123",
    "cardexp": "02/25",
    "cardHolder": "John Doe",
    "cardnumber": "4111111111111111",
    "cardzip": "12345",
    "method": "card"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/TokenStorage/32-8877drt00045632-678")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
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()
```

### UpdateACHMethod

**Request**

```json
{
  "customerData": {
    "customerId": 4440
  },
  "entryPoint": "f743aed24a",
  "paymentMethod": {
    "achAccount": "1111111111111",
    "achAccountType": "Checking",
    "achCode": "WEB",
    "achHolder": "John Doe",
    "achHolderType": "personal",
    "achRouting": "123456780",
    "method": "ach"
  }
}
```

**Response**

```json
{
  "isSuccess": true,
  "responseData": {
    "referenceId": "1b502b79-e319-4159-8c29-a9f8d9f105c8-1323",
    "resultCode": 1,
    "resultText": "Updated"
  },
  "responseText": "Success"
}
```

**SDK Code**

```python UpdateACHMethod
import requests

url = "https://api-sandbox.payabli.com/api/TokenStorage/32-8877drt00045632-678"

payload = {
    "customerData": { "customerId": 4440 },
    "entryPoint": "f743aed24a",
    "paymentMethod": {
        "achAccount": "1111111111111",
        "achAccountType": "Checking",
        "achCode": "WEB",
        "achHolder": "John Doe",
        "achHolderType": "personal",
        "achRouting": "123456780",
        "method": "ach"
    }
}
headers = {
    "requestToken": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript UpdateACHMethod
const url = 'https://api-sandbox.payabli.com/api/TokenStorage/32-8877drt00045632-678';
const options = {
  method: 'PUT',
  headers: {requestToken: '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"customerData":{"customerId":4440},"entryPoint":"f743aed24a","paymentMethod":{"achAccount":"1111111111111","achAccountType":"Checking","achCode":"WEB","achHolder":"John Doe","achHolderType":"personal","achRouting":"123456780","method":"ach"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go UpdateACHMethod
package main

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

func main() {

	url := "https://api-sandbox.payabli.com/api/TokenStorage/32-8877drt00045632-678"

	payload := strings.NewReader("{\n  \"customerData\": {\n    \"customerId\": 4440\n  },\n  \"entryPoint\": \"f743aed24a\",\n  \"paymentMethod\": {\n    \"achAccount\": \"1111111111111\",\n    \"achAccountType\": \"Checking\",\n    \"achCode\": \"WEB\",\n    \"achHolder\": \"John Doe\",\n    \"achHolderType\": \"personal\",\n    \"achRouting\": \"123456780\",\n    \"method\": \"ach\"\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("requestToken", "<apiKey>")
	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))

}
```

```ruby UpdateACHMethod
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.payabli.com/api/TokenStorage/32-8877drt00045632-678")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["requestToken"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customerData\": {\n    \"customerId\": 4440\n  },\n  \"entryPoint\": \"f743aed24a\",\n  \"paymentMethod\": {\n    \"achAccount\": \"1111111111111\",\n    \"achAccountType\": \"Checking\",\n    \"achCode\": \"WEB\",\n    \"achHolder\": \"John Doe\",\n    \"achHolderType\": \"personal\",\n    \"achRouting\": \"123456780\",\n    \"method\": \"ach\"\n  }\n}"

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

```java UpdateACHMethod
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api-sandbox.payabli.com/api/TokenStorage/32-8877drt00045632-678")
  .header("requestToken", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customerData\": {\n    \"customerId\": 4440\n  },\n  \"entryPoint\": \"f743aed24a\",\n  \"paymentMethod\": {\n    \"achAccount\": \"1111111111111\",\n    \"achAccountType\": \"Checking\",\n    \"achCode\": \"WEB\",\n    \"achHolder\": \"John Doe\",\n    \"achHolderType\": \"personal\",\n    \"achRouting\": \"123456780\",\n    \"method\": \"ach\"\n  }\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api-sandbox.payabli.com/api/TokenStorage/32-8877drt00045632-678', [
  'body' => '{
  "customerData": {
    "customerId": 4440
  },
  "entryPoint": "f743aed24a",
  "paymentMethod": {
    "achAccount": "1111111111111",
    "achAccountType": "Checking",
    "achCode": "WEB",
    "achHolder": "John Doe",
    "achHolderType": "personal",
    "achRouting": "123456780",
    "method": "ach"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'requestToken' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp UpdateACHMethod
using RestSharp;

var client = new RestClient("https://api-sandbox.payabli.com/api/TokenStorage/32-8877drt00045632-678");
var request = new RestRequest(Method.PUT);
request.AddHeader("requestToken", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"customerData\": {\n    \"customerId\": 4440\n  },\n  \"entryPoint\": \"f743aed24a\",\n  \"paymentMethod\": {\n    \"achAccount\": \"1111111111111\",\n    \"achAccountType\": \"Checking\",\n    \"achCode\": \"WEB\",\n    \"achHolder\": \"John Doe\",\n    \"achHolderType\": \"personal\",\n    \"achRouting\": \"123456780\",\n    \"method\": \"ach\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift UpdateACHMethod
import Foundation

let headers = [
  "requestToken": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "customerData": ["customerId": 4440],
  "entryPoint": "f743aed24a",
  "paymentMethod": [
    "achAccount": "1111111111111",
    "achAccountType": "Checking",
    "achCode": "WEB",
    "achHolder": "John Doe",
    "achHolderType": "personal",
    "achRouting": "123456780",
    "method": "ach"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/TokenStorage/32-8877drt00045632-678")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
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()
```

> If you're a software company, you're a payments company™