Develop > Controller layer > Integrate with back-end systems and external applications > Customize WebSphere Commerce Payments > VisaNet overview


VisaNet command reference

For each WebSphere Commerce Payments application programming interface (API) command, the following sections describe:

For any framework commands, that are not listed here, there are no specific VisaNet parameters or unique behaviors.


Cassette for VisaNet commands

The following section outlines information specific to the VisaNet protocol for the parameters on WebSphere Commerce Payments commands.


AcceptPayment

The AcceptPayment command causes a generic order and a VisaNet cassette order to be created. The ApproveFlag for AcceptPayment can be set to "0", "1", or "2". The default setting is "0". An ApproveFlag of "0" indicates that the transaction should not be approved. An ApproveFlag of "1" indicates that the transaction should be approved automatically. An ApproveFlag of "2" indicates that the transaction should be approved asynchronously. If the DepositFlag is set to 1, the Payment is added to the currently open batch. If a batch is not currently open, one will be created implicitly.

Keywords Value Required
$EXPIRY Specifies card expiration date. The value is specified as a 6-character string, in the form of "YYYYMM." For example: "200207" (for July 2002). Yes
$PAN Specifies card account number. The value is specified as a 5-22 digit numeric string. For example: "2222333344445555." Yes
$ACCOUNTNUMBER Specifies the account number associated with the request. Yes
$AVS.STREETADDRESS Specifies the cardholder's street address for the Address Verification Service. The value is specified as a 1-24 character string. Yes
$AVS.POSTALCODE Specifies the cardholder's 5- or 9-digit postal code for the Address Verification Service. The value is specified as a string. For example: "37614". Yes
$CARDVERIFYCODE 3-4 character Card Verification Value used to assist in authenticating the physical presence of a card. This value appears as additional characters embossed on the credit card signature line following the credit card account number. If the $CARDVERIFYCODE represents an American Express CID, a seperate result code will not be returned. In the case of the CID not matching, American Express will not authorize the transaction (that is, a non-approval response code on the Approve). No
$NUMBEROFPAYMENTS Specifies the total number of payments or installments associated with this order. The default is 1. No
$PURCHASEORDERNUMBER Optional Purchase Order Number assigned by the merchant. A 1-25 character value. No
$PCARD.LOCALTAXAMOUNT If specified, contains the local tax amount for the order. VisaNet only supports sending one tax amount, thus, it is not valid to send both a NationalTaxAmount and a LocalTaxAmount. The cassette will detect this condition and throw an exception if this occurs. No
$PCARD.NATIONALTAXAMOUNT If specified, contains the national sales tax amount for the order. VisaNet only supports sending one tax amount, thus, it is not valid to send both a NationalTaxAmount and a LocalTaxAmount. The cassette will detect this condition and throw an exception if this occurs. No
$PCARD.TAXEXEMPTINDICATOR If specified, indicates if the order is tax exempt. Supported values are: 0 - indicates that the order is not tax exempt, 1 - indicates that the order is tax exempt. No
$PCARD.CUSTOMERREFERENCENUMBER A 16- or 17-character field indicating a customer reference ID. No
$SECURECONNECTION Specifies if the connection between the consumer and the merchant is secure (for example, SSL). A value of "0" (the default) means that the connection is not secure; a value of "1" means that the connection is secure. The setting of this field affects the ECI (electronic commerce indicator) that is passed in the authorization request. No
$TRANSACTIONTYPE Specifies the type of transaction. Valid values are:

5 - 3-D Secure transaction was successful (applies only if 3-D Secure support is enabled). The values for $VISA_CAVV and $VISA_XID are expected.

6 - 3-D Secure transaction was attempted but the cardholder does not participate in 3-D Secure (applies only if 3-D Secure support is enabled for the merchant). The values for $VISA_CAVV and $VISA_XID are not expected to be provided.

If 3-D Secure support is enabled, the $SECURECONNECTION keyword value is ignored.

No
$VISA_CAVV

The cardholder authentication verification value used for credit card authorization when 3-D Secure support is enabled. Consists of a 28-byte value (a 20-character alphanumeric value that is Base64 encoded for a 28-byte result). (The cassette performs the necessary decoding.)

If this keyword is specified, $VISA_XID should also be specified.

No
$VISA_XID

A unique transaction identifier determined by the merchant and used when 3-D Secure support is enabled. Consists of a 28-byte value (a 20-character alphanumeric value that is Base64 encoded for a 28-byte result). (The cassette performs the necessary decoding.)

If this keyword is specified, $VISA_CAVV should also be specified.

No


Approve

The Approve command causes a generic payment and VisaNet cassette payment to be created, and an Authorization message to be sent to the associated financial institution. If the DepositFlag is set to 1, the Payment is added to the currently open batch. If a batch is not currently open, one will be created implicitly.

The following table presents cassette-specific processing of framework parameters.

Keyword Value
BATCHNUMBER Not allowed. Must not be specified because all batches are opened implicitly.


ApproveReversal

VisaNet supports both full reversals and partial reversals. The ApproveReversal command causes the specified payment to be retrieved and reversed. If the AMOUNT is "0", a full reversal is performed and the payment moves into Void state. If the Amount is non-"0", a partial reversal is performed and the old payment is voided and a new payment is created and approved with the amount passed in on the API . In either situation, an AuthorizationReversal message is sent to the financial institution. Due to the fact that the ApproveReversal is not supported by some brands, the ApproveReversal API will always result in a voided payment (if full reversal) and good return codes.


BatchOpen

This command is not supported. All batches are opened implicitly. If this command is issued with PAYMENTTYPE set to "VisaNet" the command will fail with the following return codes:


BatchPurge

The BatchPurge command is not supported by the acquirer, thus it is a local operation only. The BatchPurge causes all the associated payments and credits to be removed from the batch, with payments returning to the Approved state and credits returning to the Void state. In addition, the batch is returned to Open state. Batch Purge is valid when a batch close has been attempted but the batch did not reconcile and the batch is in open state.

Note:

Even though the batch is reopened, it is considered inactive. No new transactions will be added to it.


BatchClose

The BatchClose command causes a Data Capture message to be sent to the financial institution. If the operation is successful, all associated payments and credits are moved to the Closed state. In addition, the batch is placed in the Closed state. In the Cassette for VisaNet, batch total comparisons are performed by the acquirer, not the merchant. If a bad response is received from the financial institution, the associated payments and credits will stay in their current state. In this situation, reconciliation is done manually and offline. When a BatchClose command is received, the current batch is put in Closing state and a new batch is implicitly opened to ensure that new transactions will not be added to the batch we are trying to close.

If you use SSL, it is strongly recommended that you keep batch sizes to under 1MB. Leased-line batches do not have this limitation.


CassetteControl

The CassetteControl command is not supported. This command will fail with the following return codes:


CloseOrder

The Delete option may be used only if every Batch containing one or more of the Payments or Credits has already been Closed.


CreateAccount

Keywords Value Required
$ACQUIRERBIN The 6-digit field containing the Visa assigned Bank Identification Number (BIN) issued by the merchant's member bank or processor. Yes
$AGENTBANKNUMBER The 1-6 digit field that identifies the agent of the acquirer which signed the merchant. This value is provided to the merchant by the acquirer. Yes
$AGENTCHAINNUMBER The 1-6 digit field containing a specific chain of an agent organization. Assigned by the merchant's bank or processor. Yes
$STORENUMBER The 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. Yes
$TERMINALNUMBER The 1-4 digit field containing a number assigned by the signing member, processor, or merchant to identify a unique terminal within a merchant's location. Yes
$COMMUNICATIONHOST The 1-5 character field that identifies the type of host with which this account is communicating. Valid values are either VITAL or FHMS. If the host is not specified, VITAL is assumed. Yes
$FHMSMERCHANTID The 1-12 digit Merchant ID assigned by FHMS. This value is used only when the $COMMUNICATIONHOST keyword contains FHMS. If a value is assigned to this field, it will override the value for $VISAMERCHANTNUMBER defined in the Merchant Cassette Settings (PaySystemAdmin object). No


CreatePaySystem

Keywords Value Required
$VISANETMERCHANTNUMBER The 1-12 digit Merchant number assigned by the merchant's bank or processor. Yes
$COUNTRYCODE A 3-digit number assigned by the signing member or processor to identify a merchant's location country. Yes
$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. Yes
$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. Yes
$MERCHANTCATEGORYCODE A 1-4 digit field containing a number assigned by the signing member or processor to identify a merchant's industry classification. Yes
$VISANETMERCHANTNAME A 1-25 character string. The merchant name provided by the signing member or processor. Yes
$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. Yes
$MERCHANTSTATE A 2-character field containing the merchant state or province code provided by the signing member or processor. Yes
$VNUMBER A 1-8 digit number assigned by the signing member or processor to identify a POS device tracking number to be used during Settlement. Defaults to "00000001" if not specified. No


DeleteBatch

The DeleteBatch command removes the specified Batch from the database. A Batch can be deleted only if the Batch is in Closed state.


Deposit

The Deposit command causes the specified payment to be added to the currently open batch. If a batch is not currently open, one is created. This command does not cause a message to be sent to the financial institution. It is a local operation only. If the operation is successful, the payment moves from Approved state to Deposited state.

Optional keywords Value
$PCARD.LOCALTAXAMOUNT If specified, contains the local tax amount for the order. VisaNet only supports sending one tax amount, thus, it is not valid to send both a NationalTaxAmount and a LocalTaxAmount. The cassette will detect this condition and throw an exception if this occurs.
$PCARD.NATIONALTAXAMOUNT If specified, contains the national sales tax amount for the order. VisaNet only supports sending one tax amount, thus, it is not valid to send both a NationalTaxAmount and a LocalTaxAmount. The cassette will detect this condition and throw an exception if this occurs.
$PCARD.TAXEXEMPTINDICATOR If specified, inicates if the order is tax exempt. Supported values are: 0 - indicates that the order is not tax exempt, 1 - indicates that the order is tax exempt.
$PCARD.CUSTOMERREFERENCENUMBER A 16- or 17-character field indicating a customer reference ID.


DepositReversal

The DepositReversal command causes the specified payment to be removed from the currently open batch. This command is a local operation only and does not cause a message to be sent to the financial institution. This command is valid for payments in Deposited state. If the command is successful, the payment moves to Approved state.


ModifyAccount

Optional keywords Value
$ACQUIRERBIN The 6-digit field containing the Visa assigned Bank Identification Number (BIN) issued by the merchant's member bank or processor.
$AGENTBANKNUMBER This is a 1-6 digit value that identifies the agent of the acquirer which signed the merchant. This value is provided to the merchant by the acquirer.
$AGENTCHAINNUMBER The 1-6 digit field containing a specific chain of an agent organization. Assigned by the merchant's bank or processor.
$STORENUMBER The 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 The 1-4 digit field containing a number assigned by the signing member, processor, or merchant to identify a unique terminal within a merchant location.
$FHMSMERCHANTID The 1-12 digit Merchant ID assigned by FHMS. This value is used only when the $COMMUNICATIONHOST keyword contains FHMS. If a value is assigned to this field, it will override the value for $VISAMERCHANTNUMBER defined in the Merchant Cassette Settings (PaySystemAdmin object).


ModifyCassette

Optional keywords Value
$ATTEMPTINTERVAL Number of seconds to wait until trying the next set of retries. An integer between 0 and 2147483647. If not specified, the default is "60" (1 minute).
$MAXATTEMPTS Maximum number of retry sets. An integer between 0 and 2147483647. If not specified, the default is "3."
$SOCKSHOSTNAME TCP Host Address for socks server (0-254 character string).

Specify the fully qualified host name carefully. For example, mycomputer.city.company.com is fully qualified. If you enter the wrong SOCKS host name, the Payments application server may fail when a Payments transaction is attempted and we will not be able to use the Payments GUI. (To recover, stop and restart the Payments instance.)

$SOCKSPORTNUMBER TCP Port Number for socks server. An integer between 0 and 2147483647.
$HOSTNAME The TCP/IP host name to access the VisaNet host (1-254 character string). If specified, the $PORTNUMBER keyword must also be specified. If this keyword contains a null value, $PORTNUMBER must contain a null value.
$PORTNUMBER The TCP/IP port number to access the VisaNet host. An integer between 0 and 2147483647. If specified, the $HOSTNAME keyword must also be specified. If this keyword contains a null value, $HOSTNAME must contain a null value.
$FHMSHOSTNAME The TCP/IP host name to access the FHMS host (1-254 character string). If specified, also specify a value for $FHMSAUTHPORTNUMBER and FHMSBATCHPORTNUMBER. If one of these three keywords contains a null value, all three must contain null values.
$FHMSAUTHPORTNUMBER The TCP/IP port number to access the FHMS host for authorization. An integer between 0 and 2147483647. If specified, also specify a value for $FHMSHOSTNAME and FHMSBATCHPORTNUMBER. If one of these three keywords contains a null value, all three must contain null values.
$FHMSBATCHPORTNUMBER The TCP/IP port number to access the FHMS host for batch settlement. An integer between 0 and 2147483647. If specified, also specify a value for $FHMSHOSTNAME and FHMSAUTHPORTNUMBER. If one of these three keywords contains a null value, all three must contain null values.
$FHMSURL The SSL gateway to access the FHMS host using HTTPS (1-254 character string).
$VITALURL The SSL gateway to access the Vital host using HTTPS (1-254 character string).
$MAXRETRIES Maximum number of retry sets. An integer between 0 and 2147483647. This keyword applies to SSL only.
$READTIMEOUT Number of seconds to wait until trying the next read attempt. An integer between 0 and 2147483647. This keyword applies to SSL only.


ModifyPaySystem

Optional keywords Value
$VISANETMERCHANTNUMBER The 1-12 digit Merchant number assigned by the merchant's bank or processor.
$COUNTRYCODE A 3-digit number assigned by the signing member or processor to identify a merchant's location country.
$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.
$TIMEZONEDIFFERENTIAL The 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 The 1-4 digit field containing a number assigned by the signing member or processor to identify a merchant's industry classification.
$VISANETMERCHANTNAME The 1-25 character merchant name.
$MERCHANTLOCATION The 11-character merchant location. For Direct Marketing merchants, this field will contain a customer service phone number in xxx-xxxxxxx format. The dash is required.
$MERCHANTSTATE The 2-character field containing the merchant's state or province code provided by the signing member or processor.


ReceivePayment

This command is not supported because the cassette does not support order creation by using a wallet. If this command is issued with PAYMENTTYPE set to "VisaNet" the command fails with the following return codes:


Refund

The Refund command causes a generic Credit object and a VisaNet cassette Credit object to be created and added to the currently open batch. If a batch is not currently open, one is created. The Refund command is valid only if the associated Order is in the Refundable state. If the operation is successful, the Credit is put in Refunded state. When the Refund command is issued, a message is not sent to the financial institution.

Keyword Value
BATCHNUMBER Is not allowed. Must not be specified because all batches are opened implicitly.


RefundReversal

The RefundReversal command causes the specified credit to be removed from the currently open batch. This command does not cause a message to be sent to the financial institution. The RefundReversal command is valid for credits in the Refunded state only. If the RefundReversal command is successful, the credit moves to the Void state.


Related concepts

VisaNet overview

Cassette for VisaNet


+

Search Tips   |   Advanced Search