VisaNet object reference
The object model of the Cassette for VisaNet closely reflects the generic model of the WebSphere Commerce Payments. This section describes each of the cassette extensions to the various framework objects, as well as new objects defined exclusively by the cassette.
The WebSphere Commerce Payments query command set allows merchant software to search for and retrieve the data objects maintained in the WebSphere Commerce Payments database. The results of each query call are returned in the form of an XML PSApiResult document. Cassette for VisaNet object extensions appear in these documents as extensions to the generic objects of the framework.
Financial objects used by Cassette for VisaNet
Each of the framework's generic financial objects is extended by the Cassette for VisaNet.
VisaNet Order
Field name | Description |
---|---|
expiry | The Credit or Debit card's expiration date in the form YYYYMM as specified on the AcceptPayment command. This value is always present. |
pan | The Credit or Debit card number as specified on the AcceptPayment command. This value is always present. |
numberOfPayments | The number of payments associated with this order. This field is used only if the order has recurring payments or installments associated with it. |
avsPostalCode | Specifies the cardholder's 5- or 9-digit postal code for the Address Verification Service. |
purchaseOrderNumber | The purchase order number as specified on the AcceptPayment command. |
avsStreet | Specifies the cardholder's street address for the Address Verification Service. The combination of street address and postal code cannot exceed a length of 24 characters for VisaNet. |
cvv2 | Card Verification Value that is used to assist in authenticating the physical presence of a card. |
taxExemptIndicator | Indicates that the order is tax exempt, that is, no taxes are applied to the order. |
localTaxAmount | The total amount of local tax applied to the order. |
nationalTaxAmount | The total amount of national tax (sales or VAT) applied to the order. |
customReferenceNumber | A reference number assigned to the order by the Cardholder. |
secureConnection | Returns value of the $SECURECONNECTION parameter. |
VisaNet Order object XML example
This XML example shows an Order object and its cassette extensions:
<?xml version="1.0" encoding="utf-8"?>
<PSApiResult objectCount="3" primaryRC="0" secondaryRC="0">
<OrderCollection size="3" withCredits="0" withPayments="0">
<PSOrder ID="O:123456789:33" amount="7500" amountExp10="-2"
approvesAllowed="1" currency="840" merchantAccount="1"
merchantNumber="123456789" merchantOriginated="1" numberOfCredits="0"
numberOfPayments="0" orderNumber="33" paymentType="VisaNet"
state="order_refundable" timeStampCreated="968460959000"
timeStampModified="968461231000" unapprovedAmount="0">
<CassetteExtensionObject>
<CassetteProperty propertyId="numberOfPayments" value="1">
</CassetteProperty>
<CassetteProperty propertyId="expiry" value="200411">
</CassetteProperty>
<CassetteProperty propertyId="pan" value="4111111111111111">
</CassetteProperty>
<CassetteProperty propertyId="avsPostalCode" value="27511">
</CassetteProperty>
<CassetteProperty propertyId="avsStreet" value="123 Memory Lane">
</CassetteProperty>
<CassetteProperty propertyId="cvv2" value="529">
</CassetteProperty>
</CassetteExtensionObject>
</PSOrder>
<PSOrder ID="O:123456789:34" amount="4399" amountExp10="-2"
approvesAllowed="1" currency="840" merchantAccount="1"
merchantNumber="123456789" merchantOriginated="1" numberOfCredits="0"
numberOfPayments="0" orderNumber="34" paymentType="VisaNet"
state="order_refundable" timeStampCreated="968461024000"
timeStampModified="968461279000" unapprovedAmount="0">
<CassetteExtensionObject>
<CassetteProperty propertyId="numberOfPayments" value="1">
</CassetteProperty>
<CassetteProperty propertyId="expiry" value="200207">
</CassetteProperty>
<CassetteProperty propertyId="pan" value="4060667755430966">
</CassetteProperty>
<CassetteProperty propertyId="avsPostalCode" value="23411">
<CassetteProperty>
<CassetteProperty propertyId="avsStreet" value="111 Main Street">
</CassetteProperty>
<CassetteProperty propertyId="cvv2" value="703">
</CassetteProperty>
</CassetteExtensionObject>
</PSOrder>
<PSOrder ID="O:123456789:35" amount="15688" amountExp10="-2"
approvesAllowed="1" currency="840" merchantAccount="1"
merchantNumber="123456789" merchantOriginated="1" numberOfCredits="0"
numberOfPayments="0" orderNumber="35" paymentType="VisaNet"
state="order_refundable" timeStampCreated="968461103000"
timeStampModified="968461103000" unapprovedAmount="15688">
<CassetteExtensionObject>
<CassetteProperty propertyId="numberOfPayments" value="1">
</CassetteProperty>
<CassetteProperty propertyId="expiry" value="200309">
</CassetteProperty>
<CassetteProperty propertyId="pan" value="7655343434987987834">
</CassetteProperty>
<CassetteProperty propertyId="avsPostalCode" value="29645">
</CassetteProperty>
<CassetteProperty propertyId="avsStreet" value="27 Lombard Street">
</CassetteProperty>
<CassetteProperty propertyId="cvv2" value="1234">
</CassetteProperty>
</CassetteExtensionObject>
</PSOrder>
</OrderCollection>
</PSApiResult>
VisaNet Payment
Field name | Description |
---|---|
paySequenceNum | The sequence number that this payment represents in the total count of installment payments being made. The VisaNet Order table contains the total count of installment payments associated with the order. |
cvv2ResultCode | CVV2 Result code returned in the Authorization Response. |
paymentNumber | The number assigned to this payment. |
validationCode | May contain specific information generated by the card issuer. |
authResponseCode | The status of the authorization request. An AuthResponseCode of "00" indicates approval. An AuthResponseCode of "85" indicates successful card verification and approval. All other codes indicate non-approval. |
avsResultCode | The AVS code received from the acquirer for this payment. This field will be present only when the VisaNet host returns an avs-code value for this payment. |
approvalCode | The approval code received from the acquirer for this payment. |
localTrxTime | Time calculated by the authorization center using the time zone differential. The time format is HH:MM:SS. |
orderNumber | The WebSphere Commerce Payments order number. |
trxSequenceNum | Cassette-generated transaction sequence number. |
merchantNumber | The WebSphere Commerce Payments merchant number. |
retrievalRefNum | The transaction's Retrieval Reference Number. |
authResponseText | Authorization response message. This message contains additional information about the authorization result. |
localTrxDate | Date calculated by the authorization center using the time zone differential. The date format is MMDDYY. |
returnedACI | The Returned Authorization Characteristics Indicator. This value provides information concerning the transaction's CPS qualification status. |
authSourceCode | Source of the authorization code. |
transactionID | May contain a Visa Transaction Identifier or MasterCard Reference Number. |
commonAVSCode | Common Address Verification Service result code. |
taxExemptIndicator | Indicates that the order is tax exempt, that is, no taxes are applied to the order. |
localTaxAmount | The total amount of local tax applied to the order. |
nationalTaxAmount | The total amount of national tax (sales or VAT) applied to the order. |
customReferenceNumber | A reference number assigned to the order by the Cardholder |
Payment object XML Example
This XML example shows a VisaNet Payment object and its cassette extensions:
<?xml version="1.0" encoding="UTF-8"?>
<PSApiResult objectCount="2" primaryRC="0" secondaryRC="0">
<PaymentCollection size="2" withOrders="0">
<PSPayment ID="P:123456789:33:1" amountExp10="-2" approveAmount="7500"
batchNumber="4" currency="840" depositAmount="7500" merchantAccount="1"
merchantNumber="123456789" orderNumber="33" paymentNumber="1"
paymentType="VisaNet" referenceNumber="123456789012" state="payment_deposited"
timeStampCreated="968461230000" timeStampModified="968461363000">
<CassetteExtensionObject>
<CassetteProperty propertyId="commonAVSCode" value="0">
</CassetteProperty>
<CassetteProperty propertyId="paySequenceNum" value="1">
</CassetteProperty>
<CassetteProperty propertyId="paymentNumber" value="1">
</CassetteProperty>
<CassetteProperty propertyId="authResponseCode" value="00">
</CassetteProperty>
<CassetteProperty propertyId="avsResultCode" value="X">
</CassetteProperty>
<CassetteProperty propertyId="approvalCode" value="222222">
</CassetteProperty>
<CassetteProperty propertyId="localTrxTime" value="123000">
</CassetteProperty>
<CassetteProperty propertyId="orderNumber" value="33">
</CassetteProperty>
<CassetteProperty propertyId="trxSequenceNum" value="0001">
</CassetteProperty>
<CassetteProperty propertyId="merchantNumber" value="123456789">
<CassetteProperty>
<CassetteProperty propertyId="retrievalRefNum" value="123456789012">
</CassetteProperty>
<CassetteProperty propertyId="authResponseText" value="Order Approved!!">
</CassetteProperty>
<CassetteProperty propertyId="localTrxDate" value="070400">
</CassetteProperty>
<CassetteProperty propertyId="returnedACI" value="A">
</CassetteProperty>
<CassetteProperty propertyId="returnedACI" value="A">
</CassetteProperty>
<CassetteProperty propertyId="authSourceCode" value="9">
</CassetteProperty>
</CassetteExtensionObject>
</PSPayment>
<PSPayment ID="P:123456789:34:1" amountExp10="-2" approveAmount="4399"
currency="840" depositAmount="0" merchantAccount="1"
merchantNumber="123456789" orderNumber="34" paymentNumber="1"
paymentType="VisaNet" referenceNumber="123456789012"
state="payment_approved" timeStampCreated="968461249000"
timeStampModified="968461279000">
<CassetteExtensionObject>
<CassetteProperty propertyId="commonAVSCode" value="0">
</CassetteProperty>
<CassetteProperty propertyId="paySequenceNum" value="1">
</CassetteProperty>
<CassetteProperty propertyId="paymentNumber" value="1">
</CassetteProperty>
<CassetteProperty propertyId="authResponseCode" value="00">
</CassetteProperty>
<CassetteProperty propertyId="avsResultCode" value="X">
</CassetteProperty>
<CassetteProperty propertyId="approvalCode" value="222222">
</CassetteProperty>
<CassetteProperty propertyId="localTrxTime" value="123000">
</CassetteProperty>
<CassetteProperty propertyId="orderNumber" value="34">
</CassetteProperty>
<CassetteProperty propertyId="trxSequenceNum" value="0002">
</CassetteProperty>
<CassetteProperty propertyId="merchantNumber" value="123456789">
</CassetteProperty>
<CassetteProperty propertyId="retrievalRefNum" value="123456789012">
</CassetteProperty>
<CassetteProperty propertyId="authResponseText" value="Order Approved!!">
</CassetteProperty>
<CassetteProperty propertyId="localTrxDate" value="070400">
</CassetteProperty>
<CassetteProperty propertyId="returnedACI" value="A">
</CassetteProperty>
<CassetteProperty propertyId="authSourceCode" value="9">
</CassetteProperty>
</CassetteExtensionObject>
</PSPayment>
</PaymentCollection>
</PSApiResult>
VisaNet Credit
Field name | Description |
---|---|
transactionTime | The local system time when the Credit was created. The format is "HHMMSS." |
transactionDate | The local system date when the Credit was created. The format is "MMDD." |
VisaNet Credit object XML example
This XML example shows a Credit object and its cassette extensions:
<?xml version="1.0" encoding="UTF-8"?>
<PSApiResult objectCount="1" primaryRC="0" secondaryRC="0">
<CreditCollection size="1" withOrders="0">
<PSCredit ID="C:123456789:34:1" amount="1500" amountExp10="-2"
batchNumber="4" creditNumber="1" currency="840" merchantAccount="1"
merchantNumber="123456789" orderNumber="34" paymentType="VisaNet"
referenceNumber="0908,210118" state="credit_refunded"
timeStampCreated="968461279000" timeStampModified="968461279000">
<CassetteExtensionObject>
<CassetteProperty propertyId="transactionTime" value="210118">
</CassetteProperty>
<CassetteProperty propertyId="transactionDate" value="0908">
</CassetteProperty>
</CassetteExtensionObject>
</PSCredit>
</CreditCollection>
</PSApiResult>
VisaNet Batch
Field name | Description |
---|---|
batchErrorData | If a batch response indicates "RB" for rejected batch, this field contains error information that can be useful in identifying and correcting the "RB" condition. |
batchRspCode | The status of the batch returned from the financial institution. The
responses returned, are:
|
batchTransDate | The batch transmission date, in the format of MMDD. This date is generated by the cassette and sent in the settlement message. |
vitalBatchNumber | The Cassette generated value in the range of 001-999. |
currencyCode | The currency code of the Batch. |
Batch object XML example
This XML example shows a Batch object and its cassette extensions:
<?xml version="1.0" encoding="UTF-8"?>
<PSApiResult objectCount="2" primaryRC="0" secondaryRC="0">
<BatchCollection size="2" withCredits="0" withPayments="0">
<PSBatch ID="B:123456789:3" batchNumber="3" batchStatus="batch_not_yet_balanced"
forceAllowed="0" merchantAccount="1" merchantControl="1" merchantNumber="123456789"
paymentType="OfflineCard" purgeAllowed="1" state="batch_open" timeStampClosed="0"
timeStampModified="968275527000" timeStampOpened="968275527000">
<BatchTotalCollection size="1">
<PSBatchTotal amountExp10="-2" creditAmount="0" currency="840" numberOfCredits="0"
numberOfPayments="1" paymentAmount="7500">
</PSBatchTotal>
</BatchTotalCollection>
<CassetteExtensionObject>
<CassetteProperty propertyId="Currency" value="840">
</CassetteProperty>
</CassetteExtensionObject>
</PSBatch>
<PSBatch ID="B:123456789:4" batchNumber="4" batchStatus="batch_not_yet_balanced"
forceAllowed="0" merchantAccount="1" merchantControl="1" merchantNumber="123456789"
paymentType="VisaNet" purgeAllowed="1" state="batch_open" timeStampClosed="0"
timeStampModified="968461363000" timeStampOpened="968461278000">
<BatchTotalCollection size="1">
<PSBatchTotal amountExp10="-2" creditAmount="1500" currency="840"
numberOfCredits="1" numberOfPayments="1" paymentAmount="7500">
</PSBatchTotal>
</BatchTotalCollection>
<CassetteExtensionObject>
<CassetteProperty propertyId="currencyCode" value="840">
</CassetteProperty>
</CassetteExtensionObject>
</PSBatch>
</BatchCollection>
</PSApiResult>
Administrative objects used by Cassette for VisaNet
The Cassette for VisaNet uses and extends these framework objects for WebSphere Commerce Payments administration:
Each administrative object is defined by its attributes, or fields. The field names and field descriptions are shown for each administrative object.
CassetteAdmin
Field name | Description |
---|---|
hostName | The TCP/IP host name to access the Vital host. |
portNumber | The TCP/IP port number to access the Vital host. |
fhmsHostName | The TCP/IP host name used to access the FHMS host. |
fhmsAuthPortNumber | The TCP/IP port number to access the FHMS host for authorizations. |
fhmsBatchPortNumber | The TCP/IP port number to access the FHMS host for settlement. |
vitalURL | The URL used to access the Vital SSL Gateway. |
fhmsURL | The URL used to access the FHMS SSL Gateway. |
socksHostName | TCP host address for SOCKS server. |
socksPortNumber | TCP port number for SOCKS server. |
maxAttempts | The maximum number of retry sets. The default is 3. |
attemptInterval | The number of seconds to wait before trying the next set of retries. The default is 60 seconds (1 minute). |
readTimeout | The number of seconds to wait before trying to read from the host. Applies to SSL only. |
maxRetries | The maximum number of retries reading from the host. Applies to SSL only. |
Cassette object XML example
This XML example shows a CassetteAdmin object and its cassette extensions:
<?xml version="1.0" encoding="UTF-8"?>
<PSApiResult objectCount="1" primaryRC="0" secondaryRC="0">
<CassetteCollection>
<PSCassette active="1" cassette="VisaNet" changesPending="0"
companyPkgName="ibm" enabled="1" valid="1">
<CassetteExtensionObject>
<CassetteProperty propertyId="maxAttempts" value="3">
</CassetteProperty>
<CassetteProperty propertyId="socksHostName" value="">
</CassetteProperty>
<CassetteProperty propertyId="attemptInterval" value="60">
</CassetteProperty>
<CassetteProperty propertyId="hostName" value="localhost">
</CassetteProperty>
<CassetteProperty propertyId="portNumber" value="1234>
<CassetteProperty>
<CassetteProperty propertyId="socksPortNumber" value="0">
</CassetteProperty>
<CassetteProperty>
<CassetteProperty propertyId="maxRetries" value="3">
</CassetteProperty>
<CassetteProperty>
<CassetteProperty propertyId="readTimeout" value="30">
</CassetteProperty>
<CassetteProperty>
<CassetteProperty propertyId="fhmsHostName" value="">
</CassetteProperty>
<CassetteProperty>
<CassetteProperty propertyId="fhmsAuthPortNumber" value="">
</CassetteProperty>
<CassetteProperty>
<CassetteProperty propertyId="fhmsBatchPortNumber" value="">
</CassetteProperty>
<CassetteProperty>
<CassetteProperty propertyId="fhmsURL"
value="https://gateway-bmd.nxt.com:4443/FTB/process-transaction.cgi">
</CassetteProperty>
<CassetteProperty>
<CassetteProperty propertyId="vitalURL" value="">
</CassetteProperty>
</CassetteExtensionObject>
</PSCassette>
</CassetteCollection>
</PSApiResult>
AccountAdmin
Field name | Description |
---|---|
accountNumber | The WebSphere Commerce Payments account number. |
acquirerBin | A 6-digit field containing the Visa assigned Bank Identification Number (BIN) issued by the merchant's member bank or processor. |
agentBankNumber | Identifies the agent of the acquirer which signed the merchant. This value is provided to the merchant by the acquirer. |
agentChainNumber | A 1-6 digit field containing a specific chain of an agent organization. Assigned by the merchant's bank or processor. |
merchantNumber | The WebSphere Commerce Payments merchant number. |
storeNumber | A 1-4 digit field containing a number assigned by the signing member, processor, or merchant to identify a specific merchant store within the VisaNet system. |
terminalNumber | A 1-4 digit field containing a number assigned by the signing member, processor, or merchant to identify a unique terminal within a merchant location. |
communicationHost | A 1-5 character field identifying the host with which this account is communicating. Valid values are VITAL or FHMS. |
fhmsMerchantID | The 1-12 digit Merchant ID assigned by FHMS. If a value is assigned to this field, the value will override the $VISANETMERCHANTNUMBER defined in the Merchant Cassette Settings (PaySystemAdmin object). |
This XML example shows a AccountAdmin object and its cassette extensions:
<?xml version="1.0" encoding="UTF-8"?>
<PSApiResult objectCount="1" primaryRC="0" secondaryRC="0">
<MerchantAccountCollection>
<PSMerchantAccount active="1" apApproveFlag="0" apDepositFlag="0" cassette="VisaNet"
changesPending="0" enabled="1" financialInstName="My Bank" merchantAccount="1"
merchantAccountName="My Account" merchantNumber="123456789" valid="1">
<CassetteExtensionObject>
<CassetteProperty propertyId="agentChainNumber" value="444545">
</CassetteProperty>
<CassetteProperty propertyId="accountNumber" value="1">
</CassetteProperty>
<CassetteProperty propertyId="acquirerBin" value="222222">
</CassetteProperty>
<CassetteProperty propertyId="terminalNumber" value="5656">
</CassetteProperty>
<CassetteProperty propertyId="agentBankNumber" value="222333">
</CassetteProperty>
<CassetteProperty propertyId="merchantNumber" value="123456789">
</CassetteProperty>
<CassetteProperty propertyId="storeNumber" value="5646">
</CassetteProperty>
<CassetteProperty propertyId="batchSequenceNumber" value="0">
</CassetteProperty>
<CassetteProperty propertyId="communicationHost" value="FHMS">
</CassetteProperty>
<CassetteProperty propertyId="fhmsMerchantID" value="192000950">
</CassetteProperty>
</CassetteExtensionObject>
</PSMerchantAccount>
</MerchantAccountCollection>
</PSApiResult>
<v>
PaySystemAdmin
Each PaySystem represents configuration data that are different for each merchant, but common across all accounts for the given merchant. The following describes the VisaNet PaySystem data:
Field name | Description |
---|---|
merchantLocation | An 11-character merchant location. This is a field that contains a customer service phone number in xxx-xxxxxxx format. The dash is required. |
countryCode | A 3-digit number assigned by the signing member or processor to identify a merchant's location country or region. |
cityCode | Used to further identify the merchant location. Within the U.S., the 5- or 9-digit zip code of the address of the store location is used. Outside the U.S., this field will be assigned by the signing member or processor. |
visaNetMerchantNumber | The 1-12 digit Merchant number assigned by the merchant's bank or processor. |
industryCode | A 3-digit number assigned by the signing member or processor to identify a merchant's location country or region. |
visaNetMerchantName | A 1-25 character string. The merchant name provided by the signing member or processor. |
vNumber | Contains a number assigned by the signing member or processor to identify a POS device tracking number. |
timeZoneDifferential | A 3-digit code used to calculate the local time within the VisaNet authorization system. The differential is calculated by the signing member or processor, providing the standard local time zone differential from GMT. |
merchantCategoryCode | A 1-4 digit field containing a number assigned by the signing member or processor to identify a merchant's industry classification. |
This XML example shows a PaySystemAdmin object and its cassette extensions:
<?xml version="1.0" encoding="UTF-8"?>
<PSApiResult objectCount="1" primaryRC="0" secondaryRC="0">
<MerchantCassetteSettingsCollection>
<PSMerchantCassetteSettings active="1" cassette="VisaNet" changesPending="0"
enabled="1" merchantNumber="123456789" valid="1">
<CassetteExtensionObject>
<CassetteProperty propertyId="visaNetMerchantNumber" value="132168461534">
</CassetteProperty>
<CassetteProperty propertyId="merchantLocation" value="213-1231234">
</CassetteProperty>
<CassetteProperty propertyId="countryCode" value="840">
</CassetteProperty>
<CassetteProperty propertyId="visaNetMerchantName" value="myMerchant">
</CassetteProperty>
<CassetteProperty propertyId="timeZoneDifferential" value="705">
</CassetteProperty>
<CassetteProperty propertyId="cityCode" value="90210">
</CassetteProperty>
<CassetteProperty propertyId="merchantState" value="CA">
</CassetteProperty>
<CassetteProperty propertyId="industryCode" value="D">
</CassetteProperty>
<CassetteProperty propertyId="vNumber" value="00000009">
</CassetteProperty>
<CassetteProperty propertyId="merchantNumber" value="123456789">
</CassetteProperty>
<CassetteProperty propertyId="merchantCategoryCode" value="9876">
</CassetteProperty>
</CassetteExtensionObject>
</PSMerchantCassetteSettings>
</MerchantCassetteSettingsCollection>
</PSApiResult>
Address Verification Service (AVS) result codes
When Address Verification Services (AVS) are requested on an AcceptPayment or a ReceivePayment command, subsequent approvals will reflect the results of the AVS check by storing the associated AVS result code in the Payment object. Since other credit card-oriented cassettes also support AVS, but may use different result codes, the WebSphere Commerce Payments framework provides a set of common AVS result codes that can be used by any cassette that supports AVS. These common codes relieve merchant software from having to be aware of which cassette is being used. For more information about Address Verification Services, see Overview of VisaNet.
The
following table illustrates the way the Cassette for VisaNet maps the VisaNet-specific
AVS result codes to the WebSphere Commerce Payments framework's common AVS
codes. Note that the VisaNet AVS result codes (defined in the left-most column)
are sometimes returned as two letters (for example, both the letter X
and
the letter Y
can be returned on a complete AVS match).
VisaNet AVS result code (returned from acquirer) | WebSphere Commerce Payments common AVS result code | Explanations |
---|---|---|
X | 0 | Both the postal code (that is, the AVS 5-digit and 9-digit) and the street address match. |
Y | 0 | Both the postal code (that is, the AVS 5-digit and 9-digit) and the street address match. |
A | 1 | The street address matches, but the postal code does not match. |
W | 2 | The 5-digit or 9-digit postal codes matches, but the street address does not match. |
Z | 2 | The 5-digit or 9-digit postal codes matches, but the street address does not match. |
N | 3 | Neither the street address nor the postal code matches. |
R | 4 | This constant maps:
|
S | 4 | This constant maps:
|
U | 4 | This constant maps:
|
E | 4 | This constant maps:
|
G | 4 | Non-US card issuer that does not participate in AVS. |
Note:
The query command results will contain both the common as well as the cassette-specific codes.