What are the different types of Tokens?

Home/Developers / Knowledge Base / FAQs / What are the different types of Tokens?

Tokens are a way to work with cards and transactions without actually having the card number. They can allow you to void transactions, repeat a sale, look up info, or save a card for later use.
However, there are a few different types of tokens you may encounter. Below are a list of the different kinds of tokens and what you can do with them.

Transaction Reference Number (Transaction Token)

This is the token that is returned with any transaction. You may also see this refered to as the PN Reference Number (PNRef). These tokens open up a range of functionality such as voiding, refunding, and capturing.
Gateway accounts can also be grouped together for Reference Number sharing. This will allow a call from one account to utilize tokens from the other. For instance, if a customer bought something from Store A but went to return them item at Store B, Store B would be able to use the original sale token to run a refund, so long as the two locations were "grouped" with each other. This allows a business to provide a customer with a unified commerce experience between different store locations and any online stores they may have.


Reference Number Use: Merchantware 4.5

To make use of a Reference Number in the MerchantWare 4.5 API, you need to define the Source tag as PREVIOUSTRANSACTION and the Token tag as the Reference Number you want to use inside the PaymentData object of your transaction request.

Example Previous Transaction SOAP Request
Sample Request Packet (raw)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Refund xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>PreviousTransaction</Source>
            
            <!--Previous Transaction Field-->
            <Token>608957</Token>
         </PaymentData>
         <Request>
            <InvoiceNumber>1703</InvoiceNumber>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>165902</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
         </Request>
      </Refund>
   </soap:Body>
</soap:Envelope>

Below are the calls that use a Reference Number.
Method Description
 Capture Captures on a previous Authorization.
 Void Voids out a previous transaction. This is used when the transaction in question is still in the open batch.
 Refund Refunds the transaction.
 TransactionsByReference Retrieves transaction information for the token used.
 DetailedTransactionByReference  Retrieves detailed transaction information for the token used.
 VaultBoardCredit Uses a Reference Number to create a Vault Token.
For more information, see the MerchantWare 4.5 documentation.

Vault Token

The Vault is a way to store a card so it can be later used through the Vault Token generated, unlocking Card on File functionality for a business.
 

Vault Token Use: Merchantware 4.5

To make use of a Reference Number in the MerchantWare 4.5 API, you need to define the Source tag as VAULT and the Token tag as the Vault Token you want to use inside the PaymentData object of your transaction request.

Example Vault SOAP Request
Sample Request Packet (raw)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <Sale xmlns="http://schemas.merchantwarehouse.com/merchantware/v45/">
         <Credentials>
            <MerchantName>Zero Inc</MerchantName>
            <MerchantSiteId>00000000</MerchantSiteId>
            <MerchantKey>00000-00000-00000-00000-00000</MerchantKey>
         </Credentials>
         <PaymentData>
            <Source>Vault</Source>
            
            <!--Vault Fields-->
            <VaultToken>1000000000002AVGMM7Z</VaultToken>
         </PaymentData>
         <Request>
            <Amount>1.83</Amount>
            <CashbackAmount>0.00</CashbackAmount>
            <SurchargeAmount>0.00</SurchargeAmount>
            <TaxAmount>0.00</TaxAmount>
            <InvoiceNumber>1559</InvoiceNumber>
            <PurchaseOrderNumber>17809</PurchaseOrderNumber>
            <CustomerCode>23</CustomerCode>
            <RegisterNumber>35</RegisterNumber>
            <MerchantTransactionId>166909</MerchantTransactionId>
            <CardAcceptorTerminalId>3</CardAcceptorTerminalId>
            <EnablePartialAuthorization>False</EnablePartialAuthorization>
            <ForceDuplicate>False</ForceDuplicate>
         </Request>
      </Sale>
   </soap:Body>
</soap:Envelope>

Below are the calls that use a Vault Token.
Feature Description
 BoardCredit Saves a swiped card into the Vault and returns a Vault Token to be used in future transactions.

 UpdateBoardedCard 

Updates the expiration date of a card stored in the Vault.
 Sale Uses a Vault Token to run a Sale.
 Refund Uses a Vault Token to run a Refund.
 Authorize Uses a Vault Token to run an Authorization.
 FindBoardedCard Returns the card info that is tied to a Vault Token.
 UnboardCard Removes a Vault Token and the associated card from the Vault.
For more information, see the MerchantWare 4.5 documentation.

One Time Use Cayan Checkout Token

The Cayan Checkout Single Use Token functions a bit differently from the other token types. This token is not tied to a card number or a completed transaction, this token is tied to a transaction that has yet to be run. It is meant to be used only once to run the transaction it was created for, much like a Transport Key, and will expire in two minutes. While the format of a Checkout token will be the same as a Vault token, know that they are separate and will only function as per their actual source.

For more information, https://cayan.com/developers/e-commerce.aspx#overview