Validate Card

Overview

This API performs validation of details for both credit card and private label credit card tenders. This API is intended for verfiying details when adding cards to a virtual wallet. This API should NOT be used as part of the standard checkout flow.

When storing a gift card in a virtual wallet, use the Gift Card Balance Inquiry API to verify existing balance and card validity. The gift card balance should be rechecked during the checkout flow when a stored gift card account is selected for payment.

Before carrying out any new implementation or design activity, please verify with Radial Payments team that your specific processing is supported.

Using this API with Virtual Wallet

After the card validation flow completes, card holder information mat be added to the customer's virtual wallet managed by the webstore. Do not store card details in the virtual wallet unless both the address and card security information are confirmed to match. All card holder details may be stored in a virtual wallet, except for the Card Security Code. When using a card in the virtual wallet which requires a card security code it must be provided by the customer again.

The token returned by the payment service will have the same first 6 and last 4 digits as the customer's card number. This may be used for identification by the customer if the webstore does not provide another means of identification in their virtual wallet information. This token and other details (e.g. billing address, etc) may be used for future authorization requests to the payment service.

If the customer changes any card holder information, the validation flow must be invoked again using the new information.

URI Summary

Action	URI Template	URI Example	Non-URI Request	Response
POST	/v1.0/stores/[StoreId]/payments/ creditcard/validate/[tenderCode].[format]	/v1.0/stores/QUIK/payments/ creditcard/validate/VC.xml	XML	200 + XML Response containing response status of the validity of the card details provided.

Action	URI Template	URI Example	Non-URI Request	Response
POST	/v1.0/stores/[StoreId]/payments/ plcc/validate/[tenderCode].[format]	/v1.0/stores/QUIK/payments/ plcc/validate/GE.xml	XML	200 + XML Response containing response status of the validity of the card details provided.

Request Example

Copy this code sample.

<?xml version="1.0" encoding="UTF-8"?>
<ValidateCardRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0" requestId="1234567890ABCD">
   <PaymentContext>
      <OrderId>OrderId0</OrderId>
      <PaymentAccountUniqueId isToken="false">PaymentAccountUniqueId</PaymentAccountUniqueId>
   </PaymentContext>
   <ExpirationDate>2013-09</ExpirationDate>
   <CardSecurityCode>123</CardSecurityCode>
   <CurrencyCode>USD</CurrencyCode>
   <BillingFirstName>John</BillingFirstName>
   <BillingLastName>Smith</BillingLastName>
   <BillingAddress>
      <Line1>123 Main St</Line1>
      <Line2>Building 123</Line2>
      <Line3>4th Floor</Line3>
      <Line4>Apt 12</Line4>
      <City>Philadelphia</City>
      <MainDivision>PA</MainDivision>
      <CountryCode>US</CountryCode>
      <PostalCode>19019</PostalCode>
   </BillingAddress>
   <BillingPhoneNo>6101234567</BillingPhoneNo>
   <CustomerEmail>customer@sample.com</CustomerEmail>
   <CustomerIPAddress>208.247.73.130</CustomerIPAddress>
</ValidateCardRequest>

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 PaymentAccountUniqueId 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 PaymentAccountUniqueId is present)	Attribute that indicates whether the payment account number is tokenized	String	true or false
PaymentContext/ EncryptedPaymentAccount UniqueId	Yes - Either PaymentAccountUniqueId 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 webstore that is not PCI compliant, this ensures that the webstore never sees raw PANs.	String	Max 1000 characters
ExpirationDate	Yes	Expiration date of the credit card	String	yyyy-MM (year followed by month)
CardSecurityCode	Yes - Either CardSecurityCode or EncryptedCardSecurityCode must be present.	CVV2 code on the back of the credit card	String	3 or 4 digits
EncryptedCardSecurityCode	No. This optional field can either have CardSecurityCode or EncryptedCardSecurityCode.	Encrypted CVV2 code on the back of the credit card	String	1000 digits
CurrencyCode	Yes	CurrencyCode that the store is configured to process credit card requests	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 credit card	String	Max 64 characters
BillingLastName	Yes	Last name of the person on the billing address of the credit card	String	Max 64 characters
BillingAddress	Yes (for AVS verification)	Billing address of the credit card	ComplexType
BillingAddress/ Line1	Yes	Line# components of the street address and, if necessary, suite and building identifiers for the physical address. Line1 is required. Line2, Line3, and Line4 are optional. Include them only if the data exists. A blank AddressLine element will fail validation.	String	1 to 70 characters.
BillingAddress/ Line2	No		String	1 to 70 characters.
BillingAddress Line3	No		String	1 to 70 characters.
BillingAddres Line4	No		String	1 to 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 ISO 3166 alpha 2 code country code. See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2.	String	2 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 alone (for example, US ZIP code)	String	Max 30 characters
BillingPhoneNo	Yes	Phone number of the person on the billing address of the credit card	String	Max 15 characters
CustomerEmail	Yes	Email address of the customer who is making the purchase. Used for realtime fraud checking by our API and payment processors.	String	Max 70 characters
CustomerIPAddress	Yes	IP address of the customer who is making the purchase. Used for realtime fraud checking by our API and payment processors.	IPv4Address	Valid dotted quad IPv4 Address
requestId	Yes	RequestId is used to uniquely identify a request, including as part of idempotent duplicate request processing. The value must be unique. It is recommended to use a variant 4 UUID for the request ID. The same request ID should only be reused if a read timeout occurs when attempting to receive a response from the payment service, or the payment service responds with a fault response. In all other cases a new request ID must be sent for retried requests, including responses such as Fail, Timeout or PaymentProcessorTimeout.	String	Up to 40 Characters.

Response Example

The response is a ValidateCardReply message.

Copy this code sample.

<?xml version="1.0" encoding="UTF-8"?>
<ValidateCardReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
   <PaymentContext>
      <OrderId>12345</OrderId>
      <!-- You will receive a token in the response, which is a scrambled version of the
      Credit Card number.-->
      <PaymentAccountUniqueId isToken="true">411111adgh2y1111</PaymentAccountUniqueId>
   </PaymentContext>
   <ResponseCode>VALID</ResponseCode>
</ValidateCardAuthReply>

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 CreditCardAuthReply message, this attribute is always set to true.	String	true
ResponseCode	Yes	Response code of the Validate card request. Includes valid, invalid, timeout, and several correction codes. See Validate Card Response Codes for a list of codes.	String	Max 7 characters.