Card URL Keys

A card can be generated from an API URL. Card URL Keys “unlock” a card record so that it may accept certain dynamic variables through a URL string. This IS NOT required if you are passing variables through the API or uploading them via CSV. This is required if you are using a third party email system and want to add variables into the card via a “Mail Merge” technology.

Create Card URL Keys

1. In order to use Card URL Keys, select the “# Keys” link for a card template in the Card Templates page.

Add url keys to card template

2. Once you are redirected to the Card URL Keys page, press the “Import URL Keys” button to begin the import process.

Import card URL keys

3. Once you are redirected to the Import Keys page, press the “Upload CSV/TSV” button to upload your list.

Import card URL keys with a CSV or TSV file

In your CSV/TSV file, there should be one column:

  • Custom Card ID: A random key that cannot be guessed. It should be unique per issued card.

This column is required for the import and is used to validate the dynamic URL when requesting a card. Also note the instructions for uploading a CSV/TSV file.

4. Map the expected URL Keys to the corresponding columns of your CSV/TSV file.

Imported card URL keys column mapping

5. There is one setting:

  • Skip the first row when importing the URL param file: If the first row of you uploaded file is made up of column headers (in this case, the custom pass ID), check this setting.

Url parameters

Once you are done with the settings, press the “Import Card Data” button to complete the import.

6. You will be redirected back to the Card URL Keys page, where you will see your imported custom card IDs at the bottom.

Review imported card URL keys

7. To test a card URL, an example URL is provided within the platform. A valid dynamic URL must always consist of the custom card ID, customer reference, and ctid i.e. the template identifier in order to generate the card.

In the URL, replace the {RandomKey} with the custom card ID and the {CustomerReference} with the customer reference (this includes removing the curly braces {}). Then enter the URL in a web browser.

Example URL:

Card URL key mobile wallet example

In the Card Templates page, if you click the “# Records” in the Card Data column, you will see that a new card data has been added.

Mobile wallet card data records

View mobile wallet card data

Card URL Keys FAQs

How can I pass dynamic data to the card?

During mail merge, additional optional parameters can be added to the dynamic URL. The fields must be set to dynamic in the card template builder. The parameters correspond to the fields in the card template builder. Below is the list of parameters and corresponding fields:

  • bval: Barcode value
  • btxt: Barcode text
  • hv1: Header value
  • pv1, pv2: Primary Value1, Primary Value 2
  • sv1, sv2, sv3, sv4: Secondary Value 1, Secondary Value 2, etc.
  • av1, av2, av3, av4: Auxiliary Value 1, Auxiliary Value 2, etc.
  • bv1, bv2, bv3, bv4: Back Value 1, Back Value 2, etc.

The format for the dynamic URL is{templateID}&customcardid={customCardID}&customerref={customerReference}&bval={barcodeValue}&btxt={barcodeText}&hv1={headerValue1}…

Example URL:

Example pass with dynamic card data

In this example, “&av1=Becky+Heart&av2=3-14” is appended to the URL. The “Auxiliary Value 1” field of the card, which corresponds to the name, is passed with the value “Becky Heart”. The “Auxiliary Value 2” field of the card, which corresponds to the row & seat number, is passed with the value “3-14”.

Here’s the card data record.

imported card data record

in Mobile Wallet