Card Engine

The Card Engine is a place to save test cards. You save a card once in a workspace. Then every ISO request in that workspace can use it.

A request takes the card number, expiry date and other values from the saved card. You do not type them again in each request.

You keep cards in collections, and you give each collection a name. You can create, view, edit and delete cards. You can also make many chip cards at once from a BIN (the first digits of a card number).

For a chip card, PruTAN can make a new cryptogram each time you send. A cryptogram is a code that the chip makes for each payment. See A new cryptogram on every send.

Open the Card Engine

1. In Studio, open the ISO tab.
2. Look at the second column of icons. This is the sub menu.
3. Click the card icon. It is next to Spec.

The card icon shows only on the ISO tab.

The card list

A collection is a folder for cards. You give it a name, for example Visa Issuing - QA or Negative tests. Each card is in one collection. The list shows each collection and the names of its cards.

• To make a collection, click New at the top of the list.
• To work with a collection, move the mouse over it. Click + to add a card. Or click ⋮ to see New card, Generate cards, Rename and Delete.
• To work with a card, move the mouse over it and click ⋮. You see Edit and Delete. To view a card, click its name.

When you delete a collection, every card in it is deleted too. PruTAN asks you first. It tells you how many cards will be deleted.

Some cards were saved before PruTAN had collections. They are in a collection called Other. You can rename it. You can also move its cards to another collection with Edit.

View a card

Click a card to open it. The window has two tabs, Card details and EMV. It also has three buttons: Delete, Edit and Close. The top of the window shows the card's scheme (the card network), for example Visa.

Card details

ISO 8583 messages are made of numbered fields. Each field is called a data element, or DE for short. So DE2 means field 2.

EMV

EMV is the standard for chip cards. A chip card sends its data in field 55 (DE55). This data is written in hex. Hex shows each byte as two characters, from 0–9 and A–F.

The chip data is a list of tags. A tag is one item of chip data. Each tag has a tag number, a length and a value.

The EMV tab shows:

• EMV application, Key group and AID. See EMV settings.
• ATC (9F36), TVR (95) and TSI (9B). The ATC counts the card's payments. The TVR and TSI are status codes from the terminal.
• At send: what PruTAN changes in DE55 each time you send.
• Chip tags (DE55): a table with every tag's number, name, length and value.
• Cryptogram settings: the fixed settings of the EMV application. You cannot change them.
• Taken from the message at send: which tags PruTAN takes from the message, and from which field.

How Track 2 for chip is built

You do not type Track 2 for chip (DE35). PruTAN builds it from Track 2 (DE35) and the iCVV:

1. The = separator becomes D.
2. The iCVV replaces the CVV, at the CVV's position.

The result has the same number of characters as Track 2. This means it fits in DE35.

Example:

Track 2:            4111111111110196=30122010000045600000
iCVV (position 30): 451
Track 2 for chip:   4111111111110196D30122010000045100000

Here the CVV 456 starts at character 30 of Track 2. The iCVV 451 takes its place.

Create a card

1. Move the mouse over a collection and click +. A dialog opens with every field empty.
2. Start with Track 2 (DE35). It fills several other fields for you.
3. Fill in the rest of the fields you need.
4. For a chip card, open the EMV tab. See EMV settings.
5. Click Save.

If a value breaks a rule, a red message shows under that field.

Bad cards for negative tests

You can save a card that a real switch would refuse. Use it to check that the switch declines it. In these cases, PruTAN shows an amber note under the field. The card is still saved:

• The check digit is wrong. The check digit is the last digit of the card number. PruTAN works it out from the other digits. This test is called the Luhn check.
• The expiry month is not 01 to 12.
• Track 2 has a different card number from Card number (DE2).
• The CVV is not the same as the 3 digits at its position in Track 2.

CVV and its position

Track 2 has some spare digits after the service code. The CVV sits in those spare digits. When you enter a CVV or an iCVV:

• CVV position in Track 2 must point into those spare digits.
• If the CVV is not the same as the 3 digits at that position, you see an amber note. The card is still saved.
• If Track 2 ends right after the service code, it has no spare digits. You see an amber note, and the card is still saved. To put the CVV in, type the CVV again and leave the box: PruTAN adds the spare digits (see below).

Filled from Track 2

When you type or paste Track 2 (DE35), PruTAN fills these fields if they are empty:

• Card number (DE2)
• Expiry (YYMM)
• Service code
• CVV (the 3 digits at the CVV position)

A green note lists the fields it filled.

PruTAN never overwrites a value that you typed yourself. If you change Track 2 again, the filled values change with it.

Track 2 follows what you type

It also works the other way. When you change the Card number, Expiry, Service code or CVV and leave the box, PruTAN puts it into Track 2. Only that part of Track 2 changes.

• If Track 2 is empty, PruTAN builds it once the card number, expiry and service code are all typed.
• If Track 2 is too short for the CVV, PruTAN adds zeros to make it 37 characters long. Then it puts the CVV at its position. It does the same when you type an iCVV, so the chip Track 2 can be built.
• If you change the card number to one with a different number of digits, Track 2 stays as it is and an amber note shows. Change Track 2 yourself, or clear it and PruTAN builds it again.

For example, Track 2 is 4761739001010119=2812201 and you type the CVV 111. Track 2 becomes 4761739001010119=28122010000011100000.

To keep a Track 2 that differs from the boxes, for a negative test, change Track 2 last.

The PIN

• PruTAN stores the PIN encrypted. It shows **** until you click the eye button. In the PIN box, the eye button shows the saved PIN, or the PIN you typed.
• When you edit a card, leave PIN empty to keep the saved PIN. Type a new PIN to replace it.
• You cannot clear a saved PIN. You can only replace it.

EMV settings

Open the EMV tab of the card dialog.

When you type the ATC, TVR or TSI, the matching row in the tag table changes at once.

A new Visa card starts with Visa CVN 18. A new Mastercard card starts with Mastercard CVN 18. It also gets the first key group. This happens only if your workspace has a key group with an IMK.

Chip tags

• To load all tags at once, paste the DE55 hex into the box. Then click Load. The ATC, TVR and TSI boxes take their values from the pasted tags. If the hex is broken, a red message shows. Nothing changes.
• To add a tag, click + Add tag. The new row is highlighted. You can type in it right away.
• To change a tag, edit its number or value. The tag's name shows next to it.
• To remove a tag, click × on its row.

Edit or delete a card

Move the mouse over a card and click ⋮. Then click Edit or Delete. You can also click the card to open it. Then use the buttons in the window.

Edit opens the same dialog with the card's saved values. Change what you need, then click Save.

If you delete a card that a request uses, that request can no longer be sent. Pick another card for it (see When Send is refused).

Who can change cards

See Workspaces for the roles.

Use a card in a request

1. Open an ISO request.
2. Open the Settings tab.
3. Find the Card row. It is under Spec.
4. Pick a card. To remove the link, pick No card.
5. Save the request.

The link to the card is saved with the request.

Next to the card there is an (i) button. It opens a list of all card values, with this card's value for each one. If the card does not have a value, you see Not on this card in red.

Use a different card in each environment

Pick From environment instead of a card. Then the environment you select decides which card the request uses. The same request can use a Dev card in Dev and a QA card in QA. You do not need to change the request.

1. In each environment, add a variable. Its value is the name of a card. For example, visa_card = Visa_Dev in Dev, and visa_card = Visa_QA in QA.
2. Open the request's Settings tab. In the Card row, pick From environment.
3. In the Card variable row, type the variable with its braces, as you do anywhere else. For example, {{visa_card}}. If you leave out the braces, PruTAN adds them.
4. Save the request.

Below the variable name, PruTAN shows which card is picked, for example QA picks Visa_QA. or Global picks Visa_Default. The (i) button shows that card's values.

When you send the request, PruTAN reads the variable from the selected environment. If it is not there, PruTAN reads it from the Global environment. Then it finds the card with that name. It fills {{card.pan}} and the other card values from that card. For the card name, upper and lower case do not matter. For the variable name, they do matter. It must match exactly.

This also works when you run a collection or a suite. Every request uses the environment you pick for the run. Requests that need different cards can use different variables, for example visa_card, rupay_card and expired_card.

Card values

Card values (placeholders) work like environment variables. Write the name inside double braces, with the card. prefix, for example {{card.pan}}.

You can use them in the Body, the Pre-request Script and Validation rules. PruTAN fills in the card's values when the request is sent.

Which value goes in which field

For example, a chip request linked to the card Visa_Credit_Chip can use these fields:

<isomsg>
  <field id="0" value="0200"/>
  <field id="2" value="{{card.pan}}"/>
  <field id="14" value="{{card.expiry}}"/>
  <field id="35" value="{{card.track2Emv}}"/>
  <field id="55" value="{{card.de55}}"/>
</isomsg>

PIN transactions

A PIN transaction sends a PIN block in field 52 (DE52). A PIN block is the PIN, encrypted with a key. The Card Engine does not build PIN blocks. Build the PIN block in the Pre-request Script, with the fn.generatePinBlock function:

req.setBody("52", fn.generatePinBlock("{{card.pin}}", "{{card.pan}}", 0, "YOUR_KEY"));

YOUR_KEY is the name of a saved Crypto Key. See Certificate & Key and Function Reference.

Check the response

Card values also work in Validation. This test passes when field 2 of the response has the card's number:

pv.test("card number came back", res.isValuePresent("2", "{{card.pan}}"));

A new cryptogram on every send

A chip card makes a new cryptogram for every payment. This cryptogram is called the ARQC (authorization request cryptogram). It is in tag 9F26. The host checks it with the card's key. If you send the same DE55 twice, the host may refuse it.

When the card has an EMV application and a Key group, PruTAN builds DE55 again each time you send:

1. It runs the Pre-request Script first.
2. Then it fills these tags from the message, after the script's changes:

3. It works out the cryptogram (9F26) with the card's chip key. It uses the card sequence number from tag 5F34, or from DE23 if the chip data has no 5F34. It puts the cryptogram in DE55.

This happens in Studio, in collection runs and in suites. PruTAN sends the ATC, TVR and TSI as you saved them.

In the DE55 field, put {{card.de55}} on its own. You can also add whole tags to it in the Pre-request Script, for example fn.concatenate("{{card.de55}}", "9F350122"). History, Validation and Trace show the DE55 that was sent.

If the Pre-request Script stamps a MAC with req.stampMAC, PruTAN stamps it again after the new cryptogram is in DE55. If the script then changed the MAC on purpose, PruTAN leaves it as the script made it. A MAC made with req.generateMAC cannot be redone, so PruTAN does not send the request. Use req.stampMAC instead.

Send a wrong cryptogram on purpose

If the Pre-request Script sets a tag with req.setEMVTagValue, PruTAN keeps the script's value, even when it is the same as the saved one. You can use this to send a wrong cryptogram. Then you can check that the host declines it. For example:

req.setEMVTagValue("55", "9F26", "0102030405060708");

If the script sets 9F26 itself, PruTAN sends that DE55 exactly as the script left it. It does not change any other tag in it.

In the same way, you can set a fixed random number (9F37) or date (9A). PruTAN then works out the cryptogram from your value.

Check a cryptogram in Sandbox or Interceptor

A Sandbox or Interceptor rule can check the cryptogram in a message that comes in. Pass the card number as card. PruTAN finds that card in the workspace. It uses the card's EMV application and key. Your rule then decides the answer. For example:

chip = emv.parseChip(req.getBody("55"), req);
check = emv.verifyArqc({ card: req.getBody("2"), data: chip, arqc: chip.arqc });
if (check.passed) { res.setBody("39", "00"); } else { res.setBody("39", "05"); }

card can also be a card name, for example card: "Visa_Credit_Chip". If two cards have the same number, use the name. emv.generateArqc and emv.generateArpc also take card like this. If the rule also passes key or profile, PruTAN uses them instead of the card's own.

Generate cards

You can make up to 100 chip cards at once from a BIN. A BIN is the first digits of a card number. It tells which bank issued the card.

1. Move the mouse over a collection and click ⋮. Then click Generate cards.
2. Fill in the fields.
3. Check the preview. It shows the first 5 cards.
4. Click Generate.

Each card gets:

• A card number. It has the BIN, then a running number, then a correct check digit. PruTAN skips numbers that a card in the workspace already has.
• A name. It is the prefix and a 3-digit number, for example gen_visa18_001. If cards with that prefix already exist, the new numbers start after the highest one.
• Expiry 12 / 2030, service code 201, and cardholder name TEST/CARDHOLDER.
• Track 1 and Track 2, built from the card number.
• PIN 1234.
• CVV 000 and iCVV 000, so {{card.track2Emv}} works.
• ATC 0001, TVR 0000008000, TSI E800, and the usual chip tags for the application.

Generated cards have no CVV2. Add it with Edit if you need it.

When Send is refused

In these cases PruTAN does not send the request. The response shows the reason.

The card does not have a value the request uses. For example, the request uses {{card.cvv2}}, but the card has no CVV2. The message is:

Card 'NAME' has no value for {{card.cvv2}} - the request was not sent.

Add the value to the card, or pick another card.

The linked card was deleted. The message is:

The linked card no longer exists - pick another card in Settings

From environment is picked, but no environment is selected and there is no Global environment. The message is:

Settings > Card uses {{visa_card}}, but no environment is selected - select one or pick a card.

From environment is picked, no environment is selected, and Global does not have the variable. The message is:

Settings > Card uses {{visa_card}}, but no environment is selected and Global has no visa_card - select one that has it, or pick a card.

From environment is picked, but the selected environment does not have the variable. The message is:

Settings > Card uses {{visa_card}}, but the selected environment has no visa_card - add it there or pick a card.

The environment gives a card name, but no card has that name. The message is:

No card named 'Visa_QA' in this team (named by {{visa_card}} in the environment)

From environment is picked, but no variable name is typed. The message is:

Settings > Card is set to From environment but has no variable name - type one or pick a card.

The card's key group was deleted. The message is:

Card 'NAME': can't make the chip cryptogram - its key group was deleted - pick another on the card's EMV tab - the request was not sent.

The key group has no IMK. The message ends with key 'NAME' has nothing in its IMK box. Add the IMK to the key group, or pick another key group.

DE55 is missing a tag the cryptogram needs. For example:

Card 'NAME': can't make the chip cryptogram - DE55 has no AIP (82) - add tag 82 on the card - the request was not sent.

If the missing tag is the amount, currency or transaction type, the message gives two choices. Add DE4, DE49 or DE3 to the message. Or add the tag to the card.

{{card.de55}} is joined with something that is not whole chip tags. The message is:

Card 'NAME': can't make the chip cryptogram - field 55 holds the card's DE55 joined with something that is not whole chip tags - put {{card.de55}} alone in the field, or join whole tags to it - the request was not sent.

The Pre-request Script made a MAC with req.generateMAC. The message ends with use req.stampMAC, which PruTAN stamps again after it.

The request uses card values, but no card is linked. The message is:

This request uses {{card.pan}} but no card is linked - pick one in Settings > Card.

Privacy

Some card values are secret: {{card.pin}}, {{card.cvv}}, {{card.icvv}} and {{card.cvv2}}. When a request uses one of them, PruTAN hides the real value. History, Trace test results and logs show the name, such as {{card.pin}}, and not the value.

Limits

• Only ISO requests can use cards. The Card row is only on the Settings tab of an ISO request.
• You cannot import or export cards yet.
• The Card Engine does not compute CVVs or PIN blocks.
• PruTAN supports only the EMV applications in the list. You can save RuPay cards, but they have no EMV application yet. So their DE55 is sent as saved.