com.beasys.commerce.ebusiness.payment
Interface CreditCardService

All Superinterfaces:

BusinessSmartComponent, java.io.Serializable, Session

public interface CreditCardService

extends Session

A CreditCardService is a Stateless Session EJB that provides services related to the authorization, capture, and settlement of credit card transactions.
It is designed as a service provider interface behind which integrations with various payment solutions are implemented. The business methods implement a very standard workflow that is associated with the completion of credit card transactions. The current state of the transaction is maintained and each action is journaled.

• Each transaction is initiated with a request to authorize. This authorization generally results in the creation of a persistent PaymentTransaction. The state of the payment and the key for that PaymentTransaction is returned in a TransactionResponse as well as service specific information. A handle for that PaymentTransaction can be obtained from the TransactionResponse.
• In the event that the initial authorization fails due to a failure to connect to the payment authorization service, it is is possible to retry the authorization using the reauthorize method.
• An authorized transaction can then be captured or settled depending on the way that the service is configured.
• Alternatively it is possible to complete the entire transaction in a single authorizeAndCapture.

Note that these methods may behave differently based on the payment model used by a merchant. Refer to the product documentation for guidance on how to configure WLCS to work with your business model. The documentation included here makes reference to concepts that are more fully explained in the documentation.

See Also:

CreditCardServiceHome, TransactionResponse, PaymentTransaction

Method Summary

TransactionResponse	authorize(CreditCard card, Price amount, boolean useAvs) Reserve credit on the supplied card for the amount specified.
TransactionResponse	authorizeAndCapture(CreditCard card, Price amount, boolean useAvs) Reserve credit on the supplied card for the amount specified.
TransactionResponse	batchQuery(java.lang.String transactionId) The batch-query message is used to update and reconcile the status of a transaction committed in a given batch.
TransactionResponse	capture(java.lang.String transactionId, Price amount) Marks a portion of a payment transaction for settlement such that it will be processed in the next batch.
TransactionResponse	queryTransactions(java.lang.String transactionId, java.lang.String transactionType, java.lang.String transactionStatus, java.lang.String transactionOrigin, java.lang.String cardType, java.sql.Date startTime, java.sql.Date endTime, Price lowAmount, Price highAmount, java.lang.Integer maxNumberOfTransactions) Query the Payment server for transactions which match the supplied parameters.
TransactionResponse	reauthorize(java.lang.String paymentTransactionId, boolean useAvs) Atempt to authorize a payment transaction that is in the retry state.
TransactionResponse	reauthorizeAndCapture(java.lang.String paymentTransactionId, boolean useAvs) Atempt to authorize a payment transaction that is in the retry state.
TransactionResponse	settle(java.lang.String transactionId, Price amount) Finalize a transaction by transferring a portion of the funds previously captured from the customer's account to the merchant's account.
TransactionResponse	voidTransaction(java.lang.String transactionId) Abort a transaction which was previously submitted.

Method Detail

authorize

public TransactionResponse authorize(CreditCard card,
                                     Price amount,
                                     boolean useAvs)
                              throws java.rmi.RemoteException,
                                     AuthorizationException,
                                     InvalidCreditCardException,
                                     ServiceUnavailableException,
                                     ServiceConfigurationException,
                                     GeneralServiceException

Reserve credit on the supplied card for the amount specified. The amount of the transaction is deducted from the "open to buy" in the customer's credit balance, but the funds are not actually transferred to the merchant. Funds are transferred from the customer's credit balance to the merchants account only after settling.

This method should only be used for terminal-based payment models. Merchants who are using a terminal-based processor must perform a capture and settlement procedure in order for the funds from the sale to be transferred to their account. This is accomplished by a subsequent call to capture and/or settle (depending on the Auto Mark/Auto Settle processor configuration).

It is also possible to void a transaction that has not yet been captured or settled using the voidTransaction method.

Parameters:

card - CreditCard against which the amount will be authorized.

amount - the amount of credit to authorize.

useAvs - boolean that tells the service if the billing address on the card is to be verified.

Returns:

a TransactionResponse that refers to the resulting PaymentTransaction.

Throws:

InvalidCreditCardException - If the associated credit card is invalid

AuthorizationException - If the associated credit card could not be authorized for the specified amount

ServiceUnavailableException - If the authorization service is unavailable

ServiceConfigurationException - If the authorization service is misconfigured

GeneralServiceException - On general service error

java.rmi.RemoteException - On remote error

authorizeAndCapture

public TransactionResponse authorizeAndCapture(CreditCard card,
                                               Price amount,
                                               boolean useAvs)
                                        throws java.rmi.RemoteException,
                                               AuthorizationException,
                                               InvalidCreditCardException,
                                               ServiceUnavailableException,
                                               ServiceConfigurationException,
                                               GeneralServiceException

Reserve credit on the supplied card for the amount specified. The amount of the transaction is deducted from the "open to buy" in the customer's credit balance, but the funds are not actually transferred to the merchant. Funds are transferred from the customer's credit balance to the merchants account only after settling.

This method should only be used for host-based payment models. Merchants who are using a host-based post-authorization capture processor must perform a capture and settlement procedure in order for the funds from the sale to be transferred to their account. This is accomplished by a subsequent call to capture and/or settle. However, in the case of a host-based authorization-capture processor, the capture and settlement of the transaction are done by the processor at the time of authorization.

It is also possible to void a transaction that has not yet been captured or settled using the voidTransaction method.

Parameters:

card - CreditCard against which the amount will be authorized.

amount - the amount of credit to authorize.

useAvs - boolean that tells the service if the billing address on the card is to be verified.

Returns:

a TransactionResponse that refers to the resulting PaymentTransaction.

Throws:

InvalidCreditCardException - If the associated credit card is invalid

AuthorizationException - If the associated credit card could not be authorized for the specified amount

ServiceUnavailableException - If the authorization service is unavailable

ServiceConfigurationException - If the authorization service is misconfigured

GeneralServiceException - On general service error

java.rmi.RemoteException - On remote error

reauthorize

public TransactionResponse reauthorize(java.lang.String paymentTransactionId,
                                       boolean useAvs)
                                throws com.beasys.commerce.ebusiness.payment.FinderException,
                                       InvalidCreditCardException,
                                       AuthorizationException,
                                       ServiceUnavailableException,
                                       ServiceConfigurationException,
                                       GeneralServiceException,
                                       java.rmi.RemoteException

Atempt to authorize a payment transaction that is in the retry state. The payment transaction is updated with the current date and a transaction entry is added to the payment transaction as the result of the authorization attempt. The modified payment transaction and any service-specific results are then returned.

This method should only be used for terminal-based payment models.

Parameters:

paymentTransactionId - The ID of the payment transaction to reauthorize

useAvs - Flag indicating whether to use address verfication

Returns:

a TransactionResponse that refers to the resulting PaymentTransaction.

Throws:

com.beasys.commerce.ebusiness.payment.FinderException - If the payment transaction with the specified ID could not be found

InvalidCreditCardException - If the associated credit card is invalid

AuthorizationException - If the associated credit card could not be authorized for the specified amount

ServiceUnavailableException - If the authorization service is unavailable

ServiceConfigurationException - If the authorization service is misconfigured

GeneralServiceException - On general service error

java.rmi.RemoteException - On remote error

reauthorizeAndCapture

public TransactionResponse reauthorizeAndCapture(java.lang.String paymentTransactionId,
                                                 boolean useAvs)
                                          throws com.beasys.commerce.ebusiness.payment.FinderException,
                                                 InvalidCreditCardException,
                                                 AuthorizationException,
                                                 ServiceUnavailableException,
                                                 ServiceConfigurationException,
                                                 GeneralServiceException,
                                                 java.rmi.RemoteException

Atempt to authorize a payment transaction that is in the retry state. The payment transaction is updated with the current date and a transaction entry is added to the payment transaction as the result of the authorization attempt. The modified payment transaction and any service-specific results are then returned.

This is method should only be used for host-based payment models.

Parameters:

paymentTransactionId - The ID of the payment transaction to reauthorize

useAvs - Flag indicating whether to use address verfication

Returns:

a TransactionResponse that refers to the updated PaymentTransaction.

Throws:

com.beasys.commerce.ebusiness.payment.FinderException - If the payment transaction with the specified ID could not be found

InvalidCreditCardException - If the associated credit card is invalid

AuthorizationException - If the associated credit card could not be authorized for the specified amount

ServiceUnavailableException - If the authorization service is unavailable

ServiceConfigurationException - If the authorization service is misconfigured

GeneralServiceException - On general service error

java.rmi.RemoteException - On remote error

capture

public TransactionResponse capture(java.lang.String transactionId,
                                   Price amount)
                            throws java.rmi.RemoteException,
                                   CaptureException,
                                   ServiceUnavailableException,
                                   PaymentException

Marks a portion of a payment transaction for settlement such that it will be processed in the next batch. The amount can be less than or equal to the authorization amount.

Before a transaction can be settled (and funds transfered into a merchant's account) it must first be captured. This marks the transaction such that it will be settled as part of a batch process. This method should be used for terminal-based payment models with a Manual Mark processor configuration. This method should be used for host-based, post authorization and capture payment model.

Parameters:

paymentTransactionId - The ID of the payment transaction to reauthorize.

amount - The amount of the transaction to capture.

Returns:

A TransactionResponse that refers to the updated PaymentTransaction.

Throws:

CaptureException - If it was not possible to capture the amount from the transaction.

ServiceUnavailableException - If the underlying service is unreachable.

PaymentException - On general payment exception.

java.rmi.RemoteException - On remote error

queryTransactions

public TransactionResponse queryTransactions(java.lang.String transactionId,
                                             java.lang.String transactionType,
                                             java.lang.String transactionStatus,
                                             java.lang.String transactionOrigin,
                                             java.lang.String cardType,
                                             java.sql.Date startTime,
                                             java.sql.Date endTime,
                                             Price lowAmount,
                                             Price highAmount,
                                             java.lang.Integer maxNumberOfTransactions)
                                      throws java.rmi.RemoteException

Query the Payment server for transactions which match the supplied parameters. The caller need only supply non-null values for those parameters that they want to query against, but must supply at least one non-null parameter.

This method is implemented as a pass through to the underlying service provider. As such all return information is service specific. Refer to the service provider manual for details on return codes and results.

Parameters:

transactionId - The ID of a specific transaction.

Throws:

java.rmi.RemoteException - On remote error

voidTransaction

public TransactionResponse voidTransaction(java.lang.String transactionId)
                                    throws java.rmi.RemoteException,
                                           PaymentException

Abort a transaction which was previously submitted. The following transactions may be voided:

• HOST_AUTH_CAPTURE transactions in the pending settlement state.
• HOST_POST_AUTH_CAPTURE transactions in the pending settlement state.
• AUTO_MARK_AUTO_SETTLE transactions in the pending settlement state.
• MANUAL_MARK_AUTO_SETTLE transactions in the pending settlement state.
• AUTO_MARK_MANUAL_SETTLE transactions in the captured state.
• MANUAL_MARK_MANUAL_SETTLE transactions in the captured state.

Parameters:

transactionId - The ID of the payment transaction to void.

Throws:

PaymentException - General payment error.

java.rmi.RemoteException - On remote error.

settle

public TransactionResponse settle(java.lang.String transactionId,
                                  Price amount)
                           throws java.rmi.RemoteException,
                                  SettleException,
                                  ServiceUnavailableException,
                                  PaymentException

Finalize a transaction by transferring a portion of the funds previously captured from the customer's account to the merchant's account. The amount can be less than or equal to the captured amount.

This method should be used for terminal-based payment models with a Manual Settle processor configuration.

Parameters:

transactionId - The ID of the payment transaction to settle.

amount - The amount of the transaction to mark for settlement.

Throws:

SettleException - If the transaction cannot be settled.

ServiceUnavailableException - If the authorization service is unavailable

PaymentException - General payment error.

java.rmi.RemoteException - On remote error

batchQuery

public TransactionResponse batchQuery(java.lang.String transactionId)
                               throws java.rmi.RemoteException

The batch-query message is used to update and reconcile the status of a transaction committed in a given batch. This message is used to determine if a particular transaction has failed, and is essential for payment processors where the status of an item cannot be determined correctly from the output fields of a batch-commit message.

This method is implemented as a pass through to the underlying service provider. As such all return information is service specific. Refer to the service provider manual for details on return codes and results. <\b>

Parameters:

transactionId - The ID of the payment transaction to query status for.

Throws:

java.rmi.RemoteException - On remote error.