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

<?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.

<?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.