Private Label Credit Card Authorization

Overview

A private label credit card (PLCC) is a credit card that is branded for a specific retailer. A PLCC is not processed on normal credit card processing networks. A PLCC usually offers a reward associated with the retailer. Processing PLCC transactions is similar to processing normal credit card transactions, except for the initial request message. Authorization cancels and settlements are the same for PLCCs and normal credit cards.

URI Summary

Action	URI Template	URI Example	Non-URI Request	Response
POST	/v[M.m]/stores/[StoreId]/ payments/plcc/auth/ [TenderCode].[format]	/v1.0/store/store123/ payments/plcc/auth/ge.xml	XML	200 + XML response

Request Example

The request is a PLCCAuthRequest message.

<PLCCAuthRequest requestId="54321" xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <PaymentContext>
      <OrderId>12345</OrderId>
      <PaymentAccountUniqueId isToken="false">6034591400000001</PaymentAccountUniqueId>
   </PaymentContext>
   <Amount currencyCode="USD">100.00</Amount>
   <BillingFirstName>FName</BillingFirstName>
   <BillingLastName>LName</BillingLastName>
   <BillingAddress>
      <Line1>935 First Ave</Line1>
      <City>King of Prussia</City>
      <MainDivision>PA</MainDivision>
      <CountryCode>US</CountryCode>
      <PostalCode>19406</PostalCode>
   </BillingAddress>
   <isRequestToCorrectCVVOrAVSError>false</isRequestToCorrectCVVOrAVSError>
</PLCCAuthRequest>

Request Elements

Element	Required	Description	Type	Restriction
PaymentContext	Yes	Unique identifier of the payment transaction for the order	ComplexType
PaymentContext/ OrderId	Yes	Unique identifier of the order. The client must ensure uniqueness of OrderIds across all transactions that the client initiates with this service.	String	Max 20 characters
PaymentContext/ PaymentAccountUniqueId	Yes - Either PaymentAccount UniqueId or EncryptedPayment AccountUniqueId must be present.	Either a raw PAN (payment account number such as a credit card number) or a token representing a PAN	String	Max 22 characters
PaymentContext/ PaymentAccountUniqueId @isToken	Yes (when PaymentAccount UniqueId is present)	Attribute that indicates whether the payment account number is tokenized	String	true or false
PaymentContext/ EncryptedPayment AccountUniqueId	Yes - Either PaymentAccount UniqueId or EncryptedPayment AccountUniqueId must be present.	Client encrypted PAN. Used for clients who use client side encryption to encrypt credit card numbers in the JavaScript that runs in their browser. For a webstores that is not PCI compliant, this ensures that the webstore never sees raw PANs.	String	Max 1000 characters
ExpirationDate	No	Expiration date of the private label credit card. Some PLCCs do not have expiration dates printed on the card.	String	yyyy-MM (year followed by month)
CardSecurityCode	No- Either CardSecurityCode or EncryptedCard SecurityCode may be present.	CVV2 code on the back of the private label credit card. Some PLCCs do not have this code.	String	3-4 digits
EncryptedCardSecurityCode	No - Either CardSecurityCode or EncryptedCard SecurityCode may be present.	Encrypted CVV2 code on the back of the private label credit card. Some PLCCs do not have this code.	String	1000 digits
Amount	Yes	Currency amount being authorized on the private label credit card	String	Positive decimal, up to two decimal places (for example, 4.75)
Amount/ @currencyCode	Yes	Type of currency used for the order	String	3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/ wiki/ISO_4217.
BillingFirstName	Yes	First name of the person on the billing address of the private label credit card	String	Max 64 characters
BillingLastName	Yes	Last name of the person on the billing address of the private label credit card	String	Max 64 characters
BillingAddress	Yes (for AVS verification)	Billing address of the private label credit card	ComplexType
BillingAddress/ Line1	Yes	Line# components of the billing address and, if necessary, suite and building identifiers for the physical address. Line1 is required. Other Line# components are optional.	String	Max 70 characters
BillingAddress/ Line2	No		String	Max 70 characters
BillingAddress/ Line3	No		String	Max 70 characters
BillingAddress/ Line4	No		String	Max 70 characters
BillingAddress/ City	Yes	Name of the city	String	Max 40 characters
BillingAddress/ MainDivision	Yes	Two- or three-digit postal abbreviation for the state or province. The ISO 3166-2 code is recommended, but not required. See http://en.wikipedia.org/wiki/ISO_3166-2.	String	Max 30 characters
BillingAddress/ CountryCode	Yes	Two digit country code. The ISO 3166 alpha 2 code is recommended, but not required. See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2.	String	2-40 characters
BillingAddress/ PostalCode	Depends on country. Yes for US and Canada	String of letters and/or numbers that specifies the delivery area more closely than the city component alone (for example, US ZIP code)	String	30 characters
StorePlanCode	No	Store plan code typically used for discounts, special offers, and promotions	String
isRequestToCorrectCVVOrAVSError	Yes	Setting that indicates this is an authorization re-submission to correct an AVS or CVV error Even when an AVS or CVV error occurs, the credit card processor authorizes a credit card and reserves the authorized amount from the available credit limit on the credit card. Customers must fix AVS and CVV errors. We do not want to double-authorize the amount already authorized on the customer's card. If this element is set true, the Payment Service decrements the authorized amount for purposes of the AVS/CVV check (for example, in the US authorizes for $0.01).	Boolean	true or false
useAlternateMerchantId	No	Setting that indicates an alternate merchant ID must be used to authorize and settle the payment. For example, Japanese regulations require that an alternate merchant ID be used to purchase gift cards.	Boolean	true or false

Response Example

The response is a PLCCAuthReply message.

<PLCCAuthReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <PaymentContext>
      <OrderId>12345</OrderId>
      <PaymentAccountUniqueId isToken="true">6034590x1xY30001</PaymentAccountUniqueId>
   </PaymentContext>
   <ResponseCode>APPROVED</ResponseCode>
   <BankAuthorizationCode>1234</BankAuthorizationCode>
   <CVV2ResponseCode></CVV2ResponseCode>
   <AVSResponseCode>Y</AVSResponseCode>
   <AVSResponseCodeDesc>Street Match, 5 digit ZIP Match</AVSResponseCodeDesc>
   <AuthorizationResponseCode>AP01</AuthorizationResponseCode>
   <AmountAuthorized currencyCode="USD">100.00</AmountAuthorized>
</PLCCAuthReply>

Response Elements

Element	Required	Description	Type	Restriction
PaymentContext	Yes	Unique identifier of the payment transaction for the order	ComplexType
PaymentContext/ OrderId	Yes	Unique identifier of the order. The client must ensure uniqueness of OrderIds across all transactions that the client initiates with this service.	String	Max 20 characters
PaymentContext/ PaymentAccountUniqueId	Yes	Token (scrambled version) of the PAN (payment account number such as a credit card number). When passing the PAN for the PaymentAuthCancelRequest and the PaymentSettlementRequest messages, always use the returned token, not the original PAN.	String	Max 22 characters
PaymentContext/ PaymentAccountUniqueId/ @isToken	Yes	Attribute that indicates whether the PAN is tokenized. In the PLCCAuthReply message, this attribute is always set to true.	String	true
ResponseCode	Yes	Response code of the credit card authorization. Includes approved, timeout, and several decline codes. Only orders with an approved or timeout response code are submitted to the Order Service. See Authorization Response Codes for a list of codes.	String	Max 1000 characters
BankAuthorizationCode	Yes	Authorization code returned by the payment processor upon a successful credit card authorization Any order taken by the Order Service and paid by credit card MUST have this authorization code.	String	Max 1000 characters
CVV2ResponseCode	Yes	Payment processor response code for the CVV2 (card verification value) check. For most credit cards, you get an approval on the AuthorizationResponseCode even if the CVV2ResponseCode returns a CVV2 failure. You CANNOT accept an order if the CVV2ResponseCode returns a CVV2 failure code. See CVV2 Response Codes for a list of codes.	String	Max 3 characters
AVSResponseCode	Yes	Payment processor response for the Address Verification System (AVS) check. For most credit cards, you get an approval on the AuthorizationResponseCode even if the AVSResponseCode returns an AVS failure code. It is typically considered a significant fraud risk to accept an order if the AVSResponseCode returns an AVS failure code. See AVS Response Codes for a list of codes.	String	Max 3 characters
AVSResponseCodeDesc	No	Description of the AVS response code	String
AuthorizationResponseCode	Yes	Response code of the credit card authorization. Includes approved, timeout, and several decline codes. Only orders with an approved or timeout response code are submitted to the Order Service. See Authorization Response Codes for a list of codes.	String	Max 1000 characters
AmountAuthorized	Yes	Currency amount authorized on the private label credit card	String	Positive decimal, up to two decimal places (for example, 4.75)
AmountAuthorized/ @currencyCode	Yes	Type of currency used for the order	String	3-character ISO 4217 code (for example, USD, CAD, EUR). See http://en.wikipedia.org/wiki/ISO_4217.