Protect PAN

Overview

A protect PAN call is made to take a PAN (payment account number) and receive a token value to represent the PAN. This token is stored and used in subsequent API calls. Using the token is a security practice that limits the exposure of the private information of the PAN.

URI Summary

Action	URI Template	URI Example	Non-URI Request	Response
POST	/vM.m/stores/[StoreId]/payments/pan/protect.xml (or) /vM.m/stores/[StoreId]/payments/pan/protect/[tenderType].xml	/v1.0/stores/TMSUS/payments/pan/protect.xml (or) /v1.0/stores/TMSUS/payments/pan/protect/VC.xml	XML	200 + XML Response containing the tokenized PAN

Request Formats

ProtectPanRequest with PaymentAccountNumber

Copy this code sample.

<?xml version="1.0" encoding="UTF-8"?>
  <ProtectPanRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <PaymentAccountNumber>{PAN}</PaymentAccountNumber>
    <TenderClass>{TenderClass}</TenderClass>
  </ProtectPanRequest>

ProtectPanRequest with EncryptedPaymentAccountNumber

Copy this code sample.

<?xml version="1.0" encoding="UTF-8"?>
  <ProtectPanRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <EncryptedPaymentAccountNumber>{ENCRYPTED PAN}</EncryptedPaymentAccountNumber>
    <TenderClass>{TenderClass}</TenderClass>
  </ProtectPanRequest>

ProtectPanRequest with PaymentAccountToken

<?xml version="1.0" encoding="UTF-8"?>
  <ProtectPanRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <OrderId>{orderId}</PaymentAccountToken>
    <PaymentAccountToken>{PAN TOKEN}</PaymentAccountToken>
    <TenderClass>{TenderClass}</TenderClass>
  </ProtectPanRequest>

Request Examples

ProtectPanRequest with PaymentAccountNumber

Copy this code sample.

<?xml version="1.0" encoding="UTF-8"?>
  <ProtectPanRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <PaymentAccountNumber>4111111111111111</PaymentAccountNumber>
    <TenderClass>CreditCard</TenderClass>
  </ProtectPanRequest>

ProtectPanRequest with EncryptedPaymentAccountNumber

Copy this code sample.

<?xml version="1.0" encoding="UTF-8"?>
  <ProtectPanRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <EncryptedPaymentAccountNumber>$bt4|javascript_1_3_9$iRTKyoL4wN2TpmJCK3FAQz4U2XNWvWPIJo99R+8kHuj1ZtyeqlBy95g5xBmNF8koHdkC1ej9jRnUaFcoKLUQwVzbSkjwev/ZghW9SJFyHj1RF6wy0g8Zq9FpGJANjnB2H3N5Y0qY139A86d4yh8RfWTzZBcdaOUz93CjyXnysRtJWktgUdltmWkuceN2zW/aMyr1zgTz/JmCcJBF5wre4X/xCD8K/efme3egHO35FIEjVxpSvTm6tWpS+DegmEdJB0X730lcYWLFwCuVLPYajQrEYmgDRWH9cN0H5rI7ueh1qg7jBWXa5/atXItcuZYL5Rr5sXOg+agoyl69u65VUA==$qt9hZbgX37c/1lOBR1+yxQz88CDI/JqC1vBlUhURh2B+om8WUVENRwy5lN+YnZQr$lATEKERFQw7jSr4y+3sANVHMR3Um+VlORB8as1dxMi8=</EncryptedPaymentAccountNumber>
    <TenderClass>CreditCard</TenderClass>
  </ProtectPanRequest>

ProtectPanRequest with PaymentAccountToken

Copy this code sample.

<?xml version="1.0" encoding="UTF-8"?>
  <ProtectPanRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <OrderId>123</OrderId>
    <PaymentAccountToken>4lakdjflskdafj2113</PaymentAccountToken>
    <TenderClass>CreditCard</TenderClass>
  </ProtectPanRequest>

Request Elements

Element	Required	Description	Type	Restriction
OrderId	No - But it is required along with tenderType in url for certain payment methods like AurusPay	Order Identifier.	String	Min - 1 Character Max - 20 Characters
PaymentAccountNumber	Yes - Either PaymentAccountNumber or EncryptedPaymentAccountNumber or PaymentAccountToken must be present.	The Payment Account Number (PAN) to be tokenized. Payment card numbers are found on payment cards, such as credit cards and debit cards, as well as stored-value cards, gift cards and other similar cards. Some card issuers refer to the card number as the primary account number or PAN.	String	Min - 3 Max - 50 Characters
EncryptedPaymentAccountNumber	Yes - Either PaymentAccountNumber or EncryptedPaymentAccountNumber or PaymentAccountToken must be present.	Encrypted Payment Account Number (PAN is encrypted using store specific public key)	String	Max - 1000 Characters
PaymentAccountToken	Yes - Either PaymentAccountNumber or EncryptedPaymentAccountNumber or PaymentAccountToken must be present.	A token for payment account number (PAN), from either internal or external tokenization	String	Min - 1 Max - 22 Characters
TenderClass	Yes	Represents type of Payment Account Number (PAN). NOTE: Use CreditCard tender class type instead of PrivateLabelCreditCard for private label credit card account numbers. PrivateLabelCreditCard is treated as CreditCard tender class type and available here for backward compatibility purpose only.	String	PrivateLabelCreditCard, CreditCard, StoredValue, PayPal

Response Format

The response is a ProtectPanReply message.

Copy this code sample.

<?xml version="1.0" encoding="UTF-8"?>
  <ProtectPanReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <Token>{Token}</Token>
  </ProtectPanReply>

Response Elements

Element	Required	Description	Type	Restriction
Token	Yes	The tokenized value of the PAN sent in the request	String

Response Example

Copy this code sample.

<?xml version="1.0" encoding="UTF-8"?>
  <ProtectPanReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <Token>4111110PASeK1111</Token>
  </ProtectPanReply>

Code Sample

For code samples in Java and PHP, see Protect PAN Request Code Samples.