> For the complete documentation index, see [llms.txt](https://developers.frontstream.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.frontstream.com/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/tokenization.md).

# Tokenization

## Update an existing card or ACH token

> Provide one of TokenGuid, ExternalCardToken, or ExternalCheckToken to identify the token.
> \
> Only include the fields you want to update — all fields are optional.
> \
> Card fields (CardNum, ExpMonth, ExpYear, CVNum, NameOnCard) are only valid for card tokens.
> \
> ACH fields (CheckRoutingNumber, CheckAccountNumber, etc.) are only valid for ACH tokens.

```json
{"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/token":{"put":{"tags":["Tokenization"],"summary":"Update an existing card or ACH token","description":"Provide one of TokenGuid, ExternalCardToken, or ExternalCheckToken to identify the token.\r\nOnly include the fields you want to update — all fields are optional.\r\nCard fields (CardNum, ExpMonth, ExpYear, CVNum, NameOnCard) are only valid for card tokens.\r\nACH fields (CheckRoutingNumber, CheckAccountNumber, etc.) are only valid for ACH tokens.","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/UpdateTokenRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTokenRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/UpdateTokenRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/UpdateTokenRequest"}}}},"responses":{"200":{"description":"Returns the updated token details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTokenResponse"}}}},"400":{"description":"If the update fails","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"UpdateTokenRequest":{"type":"object","properties":{"TokenGuid":{"type":"string","description":"Token identifier - provide one of: TokenGuid, ExternalCardToken, or ExternalCheckToken","nullable":true},"ExternalCardToken":{"maxLength":200,"type":"string","description":"optional (max: 200) - 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"maxLength":200,"type":"string","description":"optional (max: 200) - 3rd party gateway check/ACH token","nullable":true},"CardNum":{"maxLength":30,"type":"string","description":"optional (max: 30) - updated credit card number","nullable":true},"ExpMonth":{"maxLength":2,"minLength":2,"type":"string","description":"optional - example: \"01\" for January","nullable":true},"ExpYear":{"maxLength":2,"minLength":2,"type":"string","description":"optional - example: \"29\" for 2029","nullable":true},"CVNum":{"maxLength":4,"type":"string","description":"optional (max: 4) - CVV","nullable":true},"NameOnCard":{"maxLength":25,"type":"string","description":"optional (max: 25) - updated name on card","nullable":true},"CheckRoutingNumber":{"maxLength":9,"type":"string","description":"optional (max: 9) - updated bank routing number","nullable":true},"CheckAccountNumber":{"maxLength":20,"type":"string","description":"optional (max: 20) - updated bank account number","nullable":true},"CheckNumber":{"maxLength":10,"type":"string","description":"optional (max: 10) - check number","nullable":true},"CheckAccountTypeId":{"type":"string","description":"optional - 1=Checking, 2=Saving","nullable":true},"CheckTypeId":{"type":"string","description":"optional - 1=Personal, 2=Corporate, 3=Government","nullable":true},"NameOnCheck":{"maxLength":25,"type":"string","description":"optional (max: 25) - updated name on check","nullable":true},"Email":{"maxLength":100,"type":"string","description":"optional (max: 100) - updated billing email","format":"email","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing first name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing last name","nullable":true},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - billing zip/postal code","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing street address","nullable":true},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing city","nullable":true},"State":{"maxLength":50,"type":"string","description":"optional (max: 50) - 2 char US state code or non-US equivalent","nullable":true},"Country":{"maxLength":2,"type":"string","description":"optional - 2 char country code","nullable":true},"Currency":{"maxLength":3,"type":"string","description":"optional - 3 char currency code, e.g. \"USD\", \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - constituent id from partner system","nullable":true},"IsDefault":{"type":"boolean","description":"optional - when true, designates this token as the default payment method for the constituent;\r\nclears IsDefault on all other tokens for the same constituent and processor","nullable":true},"IntegrationSource":{"type":"string","description":"optional - internal use - Identifies integrated Product; validated against the integration source that created the token","nullable":true}},"additionalProperties":false},"UpdateTokenResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"True if the token update was successful"},"Message":{"type":"string","description":"Update token response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Processor response message","nullable":true},"TokenGuid":{"type":"string","description":"The TokenGuid identifying this token","format":"uuid"},"ExternalCardToken":{"type":"string","description":"Updated ExternalCardToken - may differ from the original if the card number was changed on a processor that requires a new token (e.g. Stripe)","nullable":true},"ExternalCheckToken":{"type":"string","description":"Updated ExternalCheckToken - may differ from the original if the bank account was changed on a processor that requires a new token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId - 3rd party gateway customer id tied to the token","nullable":true},"ExternalConstituentId":{"type":"string","description":"Partner's customer/constituent/donor id stored on the token record","nullable":true},"ResponseCode":{"type":"string","description":"Response Code - \"0\" on success, any other value indicates an error","nullable":true}},"additionalProperties":false},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}}
```

## Cancel/delete a payment token by TokenGuid, ExternalCardToken, or ExternalCheckToken

> Removes the token from the payment gateway and soft-deletes the token record. The IntegrationSource that created the token must match.

```json
{"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/token":{"delete":{"tags":["Tokenization"],"summary":"Cancel/delete a payment token by TokenGuid, ExternalCardToken, or ExternalCheckToken","description":"Removes the token from the payment gateway and soft-deletes the token record. The IntegrationSource that created the token must match.","parameters":[{"name":"TokenGuid","in":"query","description":"Token identifier - provide one of: TokenGuid, ExternalCardToken, or ExternalCheckToken","schema":{"type":"string"}},{"name":"ExternalCardToken","in":"query","description":"optional (max: 200) - 3rd party gateway card token","schema":{"maxLength":200,"type":"string"}},{"name":"ExternalCheckToken","in":"query","description":"optional (max: 200) - 3rd party gateway check/ACH token","schema":{"maxLength":200,"type":"string"}},{"name":"IntegrationSource","in":"query","description":"optional - internal use - Identifies integrated Product; validated against the integration source that created the token","schema":{"type":"string"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Token successfully deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteTokenResponse"}}}},"400":{"description":"If the delete fails","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"DeleteTokenResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"True if the token was successfully cancelled/deleted"},"TokenGuid":{"type":"string","description":"The TokenGuid that was deleted","format":"uuid"},"ExternalCardToken":{"type":"string","description":"3rd party gateway card token that was deleted (null for ACH tokens)","nullable":true},"ExternalCheckToken":{"type":"string","description":"3rd party gateway check/ACH token that was deleted (null for card tokens)","nullable":true},"ExternalCustomerId":{"type":"string","description":"3rd party gateway customer id associated with the deleted token","nullable":true},"ExternalConstituentId":{"type":"string","description":"Partner's constituent/donor id stored on the deleted token record","nullable":true},"Message":{"type":"string","description":"Response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Processor response message","nullable":true},"ResponseCode":{"type":"string","description":"Response code - \"0\" on success, any other value indicates an error","nullable":true}},"additionalProperties":false},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}}
```

## POST /api/tokenize

> Tokenize a credit card

```json
{"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/tokenize":{"post":{"tags":["Tokenization"],"summary":"Tokenize a credit card","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/GetTokenRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/GetTokenRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/GetTokenRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/GetTokenRequest"}}}},"responses":{"201":{"description":"Returns the newly created token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTokenResponse"}}}},"400":{"description":"If it fails to create a token","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"GetTokenRequest":{"required":["CardNum","City","Country","Email","ExpMonth","ExpYear","NameOnCard","Street"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSource":{"type":"string","description":"internal use","nullable":true},"CardNum":{"maxLength":30,"type":"string","description":"Valid Credit card number"},"CardType":{"maxLength":20,"type":"string","description":"optional (max: 20) - \"American Express\", \"Mastercard\", \"Visa\", \"Discover\", \"Diners Club\" - will be set internally based on cardNum","nullable":true},"ExpMonth":{"maxLength":2,"minLength":2,"type":"string","description":"example: \"01\" for January - required"},"ExpYear":{"maxLength":2,"minLength":2,"type":"string","description":"example: \"29\" for 2029 - required"},"CVNum":{"maxLength":4,"type":"string","description":"optional (max: 4) - valid CVV - please provide for CVV checks","nullable":true},"NameOnCard":{"maxLength":25,"type":"string","description":"required - Name on Card"},"Email":{"maxLength":100,"type":"string","description":"required - valid contact email","format":"email"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - please provide for best interchange and avs checks - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"required - please provide for best interchange and avs checks"},"City":{"maxLength":50,"type":"string","description":"required - please provide for best interchange and avs checks"},"State":{"maxLength":50,"type":"string","description":"optional - 2 char US state code, 3 char may be used for other non-US","nullable":true},"Country":{"maxLength":2,"type":"string","description":"required - 2 char country code"},"Currency":{"maxLength":3,"type":"string","description":"optional - 3 char currency code - Example for US - \"USD\", for CA - \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ConstituentId per Product and merchant's internal customer/client ID.","nullable":true},"ExternalCustomerId":{"maxLength":200,"type":"string","description":"optional (max: 200) - 3rd party gateway Customer Key for pre-existing customers without a Payment API token record. When provided with ExternalConstituentId, links the payment session to the existing processor customer record instead of creating a new one.","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing First Name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing Last Name","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"client ip address (max: 40) where transaction originates","nullable":true}},"additionalProperties":false,"description":""},"GetTokenResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"This is \"true\" tokenization process was successful, and \"false\" if unsuccessful."},"Message":{"type":"string","description":"Get Token response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Get Token Processor response message","nullable":true},"TransactionId":{"type":"string","description":"Not currently used and may be null","nullable":true},"TokenGuid":{"type":"string","description":"The unique GUID associated with the credit card or bank token you created that is used with the api/paymentToken endpoint","format":"uuid"},"ExternalCardToken":{"type":"string","description":"ExternalCardToken if available to return - represents 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"type":"string","description":"ExternalCheckToken if available to return - represents 3rd party gateway check token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token","nullable":true},"ExternalConstituentId":{"type":"string","description":"Partner's customer/constituent/donor id provided at tokenize time","nullable":true},"ResponseCode":{"type":"string","description":"Response Code - Successful = \"OK\" or \"0\", any other response code unsuccessful","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}}
```

## POST /api/tokenizeAch

> Tokenize ACH/check account

```json
{"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/tokenizeAch":{"post":{"tags":["Tokenization"],"summary":"Tokenize ACH/check account","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/GetTokenAchRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/GetTokenAchRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/GetTokenAchRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/GetTokenAchRequest"}}}},"responses":{"201":{"description":"Returns the newly created token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTokenResponse"}}}},"400":{"description":"If it fails to create a token","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"GetTokenAchRequest":{"required":["CheckAccountNumber","CheckAccountTypeId","CheckRoutingNumber","CheckTypeId","City","Country","Email","NameOnCheck","Street"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"CheckRoutingNumber":{"maxLength":9,"type":"string","description":"required - Valid Check Bank Routing Number - formats -\r\nUS: Enter 9-digits,\r\nCA: Enter 9-digits (Format: 0YYYXXXXX: A mandatory leading zero. YYY: The 3-digit institution number. XXXXX: The 5-digit transit number),\r\nAU: Enter 6-digits - BSB Number (Bank State Branch) without hyphen"},"CheckAccountNumber":{"maxLength":20,"type":"string","description":"required - Valid Check Account Number - formats -\r\nUS: Enter 8-12 digits,\r\nCA: Enter 7-12 digits,\r\nAU: Enter 3-9 digits"},"CheckNumber":{"maxLength":10,"type":"string","description":"optional (max: 10) - Valid Check Number","nullable":true},"CheckAccountTypeId":{"type":"string","description":"required for Check ACH transactions - possible values -\r\n        1 - Checking,\r\n        2 - Saving"},"CheckTypeId":{"type":"string","description":"required for Check ACH transactions - possible values -\r\n        1 - Personal,\r\n        2 - Corporate,\r\n        3 - Government"},"NameOnCheck":{"maxLength":25,"type":"string","description":"required - Name on ACH Check Account"},"Email":{"maxLength":100,"type":"string","description":"required - valid contact email","format":"email"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing street"},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing city"},"State":{"maxLength":50,"type":"string","description":"optional - 2 char US state code, 3 char may be used for other non-US","nullable":true},"Country":{"maxLength":2,"type":"string","description":"optional - 2 char country code"},"Currency":{"maxLength":3,"type":"string","description":"optional - 3 char currency code - Example for US - \"USD\", for CA - \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ConstituentId per Product and merchant's internal customer/client ID.","nullable":true},"ExternalCustomerId":{"maxLength":200,"type":"string","description":"optional (max: 200) - 3rd party gateway Customer Key for pre-existing customers without a Payment API token record. When provided with ExternalConstituentId, links the payment session to the existing processor customer record instead of creating a new one.","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing First Name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing Last Name","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"client ip address (max: 40) where transaction originates","nullable":true}},"additionalProperties":false},"GetTokenResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"This is \"true\" tokenization process was successful, and \"false\" if unsuccessful."},"Message":{"type":"string","description":"Get Token response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Get Token Processor response message","nullable":true},"TransactionId":{"type":"string","description":"Not currently used and may be null","nullable":true},"TokenGuid":{"type":"string","description":"The unique GUID associated with the credit card or bank token you created that is used with the api/paymentToken endpoint","format":"uuid"},"ExternalCardToken":{"type":"string","description":"ExternalCardToken if available to return - represents 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"type":"string","description":"ExternalCheckToken if available to return - represents 3rd party gateway check token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token","nullable":true},"ExternalConstituentId":{"type":"string","description":"Partner's customer/constituent/donor id provided at tokenize time","nullable":true},"ResponseCode":{"type":"string","description":"Response Code - Successful = \"OK\" or \"0\", any other response code unsuccessful","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.frontstream.com/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/tokenization.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.