VisaNet command reference
For each WebSphere Commerce Payments application programming interface (API) command, the following sections describe:
- All VisaNet-specific protocol parameters
- Any special notes related to the Cassette for VisaNet handling of framework parameters.
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:
- PRC_COMMAND_NOT_SUPPORTED
- RC_NONE
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:
- PRC_COMMAND_NOT_SUPPORTED
- RC_NONE
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, |
| $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, you must 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, you must 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, you must 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:
- PRC_COMMAND_NOT_SUPPORTED
- RC_NONE
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.