Tokenization
To try a test and directly interact with the API endpoint click "Test It" and use an embedded API client to send requests with custom headers and variables, then see the live response; essentially letting you test this API directly within this page. When testing please use our Demo URL: https://demo-payments.frontstream.com/api/tokenize
access token
optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner
optional - Valid CharityId from Charity Search
internal use - Valid Panorama Organization Guid
internal use
Valid Credit card number
optional (max: 20) - "American Express", "Mastercard", "Visa", "Discover", "Diners Club" - will be set internally based on cardNum
example: "01" for January - required
example: "29" for 2029 - required
optional (max: 4) - valid CVV - please provide for CVV checks
required - Name on Card
required - valid contact email
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
required - please provide for best interchange and avs checks
required - please provide for best interchange and avs checks
optional - 2 char US state code, 3 char may be used for other non-US
required - 2 char country code
optional - 3 char currency code - Example for US - "USD", for CA - "CAD"
optional (max: 200) - ConstituentId per Product and merchant's internal customer/client ID.
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.
optional (max: 50) - billing First Name
optional (max: 50) - billing Last Name
client ip address (max: 40) where transaction originates
Returns the newly created token
This is "true" tokenization process was successful, and "false" if unsuccessful.
Get Token response message
Get Token Processor response message
Not currently used and may be null
The unique GUID associated with the credit card or bank token you created that is used with the api/paymentToken endpoint
ExternalCardToken if available to return - represents 3rd party gateway card token
ExternalCheckToken if available to return - represents 3rd party gateway check token
ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token
Partner's customer/constituent/donor id provided at tokenize time
Response Code - Successful = "OK" or "0", any other response code unsuccessful
If it fails to create a token
POST /api/tokenize HTTP/1.1
AccessToken: text
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 434
{
"ProcessorGuid": "text",
"CharityId": "text",
"OrganizationGuid": "text",
"IntegrationSource": "text",
"CardNum": "text",
"CardType": "text",
"ExpMonth": "text",
"ExpYear": "text",
"CVNum": "text",
"NameOnCard": "text",
"Email": "name@gmail.com",
"Zip": "text",
"Street": "text",
"City": "text",
"State": "text",
"Country": "text",
"Currency": "text",
"ExternalConstituentId": "text",
"ExternalCustomerId": "text",
"FirstName": "text",
"LastName": "text",
"IpAddress": "text"
}{
"Successful": true,
"Message": "text",
"ProcessorMessage": "text",
"TransactionId": "text",
"TokenGuid": "123e4567-e89b-12d3-a456-426614174000",
"ExternalCardToken": "text",
"ExternalCheckToken": "text",
"ExternalCustomerId": "text",
"ExternalConstituentId": "text",
"ResponseCode": "text"
}Tokenize bank data
access token
optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner
optional - Valid CharityId Guid from Charity Search
internal use - Valid Panorama Organization Guid
internal use - Identifies integrated Product
required - Valid Check Bank Routing Number - formats - US: Enter 9-digits, CA: Enter 9-digits (Format: 0YYYXXXXX: A mandatory leading zero. YYY: The 3-digit institution number. XXXXX: The 5-digit transit number), AU: Enter 6-digits - BSB Number (Bank State Branch) without hyphen
required - Valid Check Account Number - formats - US: Enter 8-12 digits, CA: Enter 7-12 digits, AU: Enter 3-9 digits
optional (max: 10) - Valid Check Number
required for Check ACH transactions - possible values - 1 - Checking, 2 - Saving
required for Check ACH transactions - possible values - 1 - Personal, 2 - Corporate, 3 - Government
required - Name on ACH Check Account
required - valid contact email
optional (max: 10) - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000
optional (max: 50) - billing street
optional (max: 50) - billing city
optional - 2 char US state code, 3 char may be used for other non-US
optional - 2 char country code
optional - 3 char currency code - Example for US - "USD", for CA - "CAD"
optional (max: 200) - ConstituentId per Product and merchant's internal customer/client ID.
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.
optional (max: 50) - billing First Name
optional (max: 50) - billing Last Name
client ip address (max: 40) where transaction originates
Returns the newly created token
This is "true" tokenization process was successful, and "false" if unsuccessful.
Get Token response message
Get Token Processor response message
Not currently used and may be null
The unique GUID associated with the credit card or bank token you created that is used with the api/paymentToken endpoint
ExternalCardToken if available to return - represents 3rd party gateway card token
ExternalCheckToken if available to return - represents 3rd party gateway check token
ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token
Partner's customer/constituent/donor id provided at tokenize time
Response Code - Successful = "OK" or "0", any other response code unsuccessful
If it fails to create a token
POST /api/tokenizeAch HTTP/1.1
AccessToken: text
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 476
{
"ProcessorGuid": "text",
"CharityId": "text",
"OrganizationGuid": "text",
"IntegrationSource": "text",
"CheckRoutingNumber": "text",
"CheckAccountNumber": "text",
"CheckNumber": "text",
"CheckAccountTypeId": "text",
"CheckTypeId": "text",
"NameOnCheck": "text",
"Email": "name@gmail.com",
"Zip": "text",
"Street": "text",
"City": "text",
"State": "text",
"Country": "text",
"Currency": "text",
"ExternalConstituentId": "text",
"ExternalCustomerId": "text",
"FirstName": "text",
"LastName": "text",
"IpAddress": "text"
}{
"Successful": true,
"Message": "text",
"ProcessorMessage": "text",
"TransactionId": "text",
"TokenGuid": "123e4567-e89b-12d3-a456-426614174000",
"ExternalCardToken": "text",
"ExternalCheckToken": "text",
"ExternalCustomerId": "text",
"ExternalConstituentId": "text",
"ResponseCode": "text"
}Process a Payment using newly created token
Request example: POST /api/paymentToken { "ProcessorGuid": "12345678-9012-3456-7890-dc84772c0032", "TokenGuid": "87654321-9012-3456-7890-123456789012", "Transactions": [ { "TransactionSourceGroupId": "12", "Amount": "1.00", } ] }
access token
optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner
optional - Valid CharityId Guid from Charity Search
internal use - Valid Panorama Organization Guid
internal use - Identifies integrated Product
optional if using ExternalCardToken or ExternalCheckToken instead of TokenGuid - Valid Token Guid from a Tokenized card through Payment API
internal use
internal use
optional (max: 100) - system unique id for Dup Checking per Integration Source transaction (where integration source has DupCheckEnabled) that will be checked against successfully processed prior TranIds for Duplicates
internal use - FrontStream unique Embedded Payment Form Session Id if available
optional (max: 22) - descriptor to show on bank statement
client ip address (max: 40) where transaction originates
optional (max: 9) - fee for shipping that will be added to the total amount
optional (max: 9) - If part of the donation being passed in is taxable, include that amount here. No calculations are performed using this value, it is simply a placeholder to be used for your own reporting; all commission and credit card fees still apply as normal.
optional (max: 10) to override zip created during token creation - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000
optional (max: 50) to override street created during token creation
optional (max: 50) to override city created during token creation
optional (max: 50) to override state created during token creation
optional (max: 2) to override country created during token creation
optional (max: 3) to override currency created during token creation
optional (max: 200) - Donor Identifier per Product
optional (max: 10) - Event Identifier per Product
optional - Event Guid per Product
optional (max: 500) - Event Name per Product
optional (max: 9) - calculated surcharge amount
Returns the newly created payment
See more response code definitions here: https://developers.frontstream.com/welcome-to-our-payment-api/api-references/test-payment-api-features/response-codes
As one would guess, this is "true" if the transaction was processed successfully, and "false" if the transaction was not processed successfully.
Payment Gateway response message
Response from the processing bank.
AuthCode from the processor.
Payment Gateway TransactionId
Payment API Payment GUID
Payment API Payment Id
Response Code - Approved = 0, Not processed = -100 with more possible values - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes
The total amount processed toward the cardholder's account.
The total surcharge amount if available.
Address Verification Street Status if available.
Address Verification Zip Status if available.
Address Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes
Card Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes
ExternalCardToken if available to return - represents 3rd party gateway card token
ExternalCheckToken if available to return - represents 3rd party gateway check token
ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token
ExternalConstituentId if available to return - merchant-supplied constituent/donor id linked to this token
Payment API Token GUID if available to return
internal use
ProcessorGuid used
last 4 digits of card
possible values if available: American Express, Mastercard, Visa, Discover, Diners Club, Undefined
possible values if available: None = 0, AmericanExpress = 1, MasterCard = 2, Visa = 3, Discover = 4, DinersClub = 5, ACH = 7, GOOGLEPAY = 8, APPLEPAY = 9
Was card used Surcharge eligible
last 4 digits of check account
unique tran id per Integration Source if available
FrontStream unique Embedded Payment Form Session Id if available
Payment Date of transaction
If it fails to create a payment
POST /api/paymentToken HTTP/1.1
AccessToken: text
Content-Type: application/json-patch+json
Accept: */*
Content-Length: 1274
{
"ProcessorGuid": "text",
"CharityId": "text",
"OrganizationGuid": "text",
"IntegrationSource": "text",
"TokenGuid": "text",
"ExternalCardToken": "text",
"ExternalCheckToken": "text",
"TranId": "text",
"EpfSessionId": "text",
"BillingDescriptor": "text",
"IpAddress": "text",
"ShippingFee": "text",
"TaxableBenefit": "text",
"Transactions": [
{
"TransactionSourceGroupId": "text",
"Amount": "text",
"PayFee": true,
"CommissionRateOverride": "text",
"CardProcessingFeeOverride": "text",
"ExternalLineId": "text",
"Tip": "text",
"Tax": "text"
}
],
"Zip": "text",
"Street": "text",
"City": "text",
"State": "text",
"Country": "text",
"Currency": "text",
"ExternalConstituentId": "text",
"ExternalEventId": "text",
"ExternalEventGuid": "text",
"ExternalEventName": "text",
"AFShieldAdditional": {
"ProductDescription": "text",
"ProductItem": "text",
"ProductType": "text",
"ProductQuantity": "text",
"SessionId": "text",
"BillToPhoneNumber": "text",
"ShippingAddressStreet1": "text",
"ShippingAddressStreet2": "text",
"ShippingAddressCountry": "text",
"ShippingAddressCity": "text",
"ShippingAddressEmail": "name@gmail.com",
"ShippingAddressName": "text",
"ShippingAddressZip": "text",
"ShippingAddressState": "text",
"ShipToPhoneNumber": "text",
"ShipToPremiseForUK": "text",
"ShipToStreetForUK": "text",
"BillToPremiseForUK": "text",
"BillToStreetForUK": "text"
},
"Surcharge": "text"
}{
"Successful": true,
"Message": "text",
"ProcessorMessage": "text",
"AuthCode": "text",
"TransactionId": "text",
"PaymentGuid": "123e4567-e89b-12d3-a456-426614174000",
"PaymentId": 1,
"ResponseCode": "text",
"PaymentResult": 1,
"ProcessStatus": 1,
"TotalAmount": 1,
"TotalSurcharge": 1,
"AVSStreetStatus": "text",
"AVSZipStatus": "text",
"AVSResponse": "text",
"CVVResponse": "text",
"ExternalCardToken": "text",
"ExternalCheckToken": "text",
"ExternalCustomerId": "text",
"ExternalConstituentId": "text",
"TokenGuid": "123e4567-e89b-12d3-a456-426614174000",
"TransactionFees": [
{
"TransactionSourceGroupId": "text",
"PaymentAmount": 1,
"CardFeeRate": 1,
"CardFeeAmount": 1,
"CardTypeFeeAmount": 1,
"TotalCommissionRate": 1,
"TotalCommissionAmount": 1,
"PartnerCommissionRate": 1,
"PartnerCommissionAmount": 1,
"FsCommissionRate": 1,
"FsCommissionAmount": 1,
"TotalFees": 1,
"MaxOverridePartnerCommissionRate": 1,
"MinOverridePartnerCommissionRate": 1,
"PerTransFee": 1,
"Tip": 1,
"CardFeeOnFeeAmount": 1,
"Tax": 1,
"AchFeeRate": 1,
"AchFeeAmount": 1
}
],
"OrganizationGuid": "123e4567-e89b-12d3-a456-426614174000",
"ProcessorGuid": "123e4567-e89b-12d3-a456-426614174000",
"FirstName": "text",
"LastName": "text",
"EmailAddress": "text",
"PostalCode": "text",
"AddressLine1": "text",
"City": "text",
"ProvinceCode": "text",
"CountryCode": "text",
"CardNum": "text",
"CardType": "text",
"ExpMonth": "text",
"ExpYear": "text",
"Currency": "text",
"PaymentMethodTypeId": 1,
"IsSurchargeEligible": true,
"CheckAccountNum": "text",
"TranId": "text",
"EpfSessionId": "text",
"PaymentDate": "2026-01-01T00:00:00.000Z"
}Tokenize Example
Take a look at how you might call this method:
Last updated