Module com.aoapps.payments.api

Package com.aoapps.payments

Interface MerchantServicesProvider

public interface MerchantServicesProvider

This set of functions may be provided by a specific merchant services provider/bank. Not all of the functions will be supported by all providers.

Author:

AO Industries, Inc.

Method Summary

Modifier and Type	Method	Description
AuthorizationResult	authorize(TransactionRequest transactionRequest, CreditCard creditCard)	Authorizes a sale.
boolean	canGetTokenizedCreditCards()	Queries the provider to see if they support retrieving the list of cards from the secure storage of credit cards.
boolean	canStoreCreditCards()	Queries the provider to see if they support the secure storage of credit cards.
CaptureResult	capture(AuthorizationResult authorizationResult)	Captures the funds from a previous call to authorize.
CreditResult	credit(TransactionRequest transactionRequest, CreditCard creditCard)	Requests a credit.
void	deleteCreditCard(CreditCard creditCard)	Deleted the credit card from the provider's secure storage.
String	getProviderId()	Gets the unique identifier for this provider.
Map<String,TokenizedCreditCard>	getTokenizedCreditCards(Map<String,CreditCard> persistedCards, PrintWriter verboseOut, PrintWriter infoOut, PrintWriter warningOut)	Gets all stored credit cards, with optional replacement masked card numbers and/or expiration dates.
SaleResult	sale(TransactionRequest transactionRequest, CreditCard creditCard)	Performs an immediate sale, effectively a combination of authorize and capture.
String	storeCreditCard(CreditCard creditCard)	Stores a credit card securely for later reuse, returning its providerUniqueId.
void	updateCreditCard(CreditCard creditCard)	Updates the credit card details, all except the card number and expiration.
void	updateCreditCardExpiration(CreditCard creditCard, byte expirationMonth, short expirationYear)	Updates the credit card expiration in the secure storage, card expiration on creditCard are not changed.
void	updateCreditCardNumberAndExpiration(CreditCard creditCard, String cardNumber, byte expirationMonth, short expirationYear, String cardCode)	Updates the credit card number, expiration, and (optionally) card code in the secure storage, card number, expiration, and card code on creditCard are not changed.
VoidResult	voidTransaction(Transaction transaction)	Voids a previous transaction.

Method Details

getProviderId

String getProviderId()

Gets the unique identifier for this provider. The persistence layer may enforce unique IDs per each provider. Also, each credit, void, capture, and stored credit card transaction must be performed by the same provider. The identifier is compared to test this equality.

sale

SaleResult sale(TransactionRequest transactionRequest,
 CreditCard creditCard)

Performs an immediate sale, effectively a combination of authorize and capture. No exceptions should ever be thrown, the CommunicationResult should be set to the appropriate error instead.

See Also:

• authorize(com.aoapps.payments.TransactionRequest, com.aoapps.payments.CreditCard)
• capture(com.aoapps.payments.AuthorizationResult)
• CreditCardProcessor.sale(java.security.Principal, com.aoapps.lang.security.acl.Group, com.aoapps.payments.TransactionRequest, com.aoapps.payments.CreditCard)

authorize

AuthorizationResult authorize(TransactionRequest transactionRequest,
 CreditCard creditCard)

Authorizes a sale. The funds are reserved but not captured until a later call to capture.

See Also:

• capture(com.aoapps.payments.AuthorizationResult)
• voidTransaction(com.aoapps.payments.Transaction)
• CreditCardProcessor.authorize(java.security.Principal, com.aoapps.lang.security.acl.Group, com.aoapps.payments.TransactionRequest, com.aoapps.payments.CreditCard)

capture

CaptureResult capture(AuthorizationResult authorizationResult)

Captures the funds from a previous call to authorize.

See Also:

• authorize(com.aoapps.payments.TransactionRequest, com.aoapps.payments.CreditCard)
• CreditCardProcessor.capture(java.security.Principal, com.aoapps.payments.Transaction)

voidTransaction

VoidResult voidTransaction(Transaction transaction)

Voids a previous transaction.

See Also:

• CreditCardProcessor.voidTransaction(java.security.Principal, com.aoapps.payments.Transaction)

credit

CreditResult credit(TransactionRequest transactionRequest,
 CreditCard creditCard)

Requests a credit.

See Also:

• CreditCardProcessor.credit(com.aoapps.payments.TransactionRequest, com.aoapps.payments.CreditCard)

canStoreCreditCards

boolean canStoreCreditCards()
                     throws IOException

Queries the provider to see if they support the secure storage of credit cards.

Throws:

IOException - when unable to contact the bank

See Also:

• CreditCardProcessor.canStoreCreditCards()

storeCreditCard

String storeCreditCard(CreditCard creditCard)
                throws UnsupportedOperationException,
IOException

Stores a credit card securely for later reuse, returning its providerUniqueId.

Throws:

UnsupportedOperationException - when not supported

IOException - when unable to contact the bank

See Also:

• canStoreCreditCards()
• CreditCardProcessor.storeCreditCard(java.security.Principal, com.aoapps.lang.security.acl.Group, com.aoapps.payments.CreditCard)

updateCreditCard

void updateCreditCard(CreditCard creditCard)
               throws UnsupportedOperationException,
IOException

Updates the credit card details, all except the card number and expiration.

Throws:

UnsupportedOperationException - when not supported

IOException

See Also:

• canStoreCreditCards()
• CreditCardProcessor.updateCreditCard(java.security.Principal, com.aoapps.payments.CreditCard)

updateCreditCardNumberAndExpiration

void updateCreditCardNumberAndExpiration(CreditCard creditCard,
 String cardNumber,
 byte expirationMonth,
 short expirationYear,
 String cardCode)
                                  throws UnsupportedOperationException,
IOException

Updates the credit card number, expiration, and (optionally) card code in the secure storage, card number, expiration, and card code on creditCard are not changed. This information is stored by local persistence, but some providers also have a copy of this information. This is used to keep the two systems in sync.

Throws:

UnsupportedOperationException - when not supported

IOException - when unable to contact the bank

See Also:

• canStoreCreditCards()
• CreditCardProcessor.updateCreditCardNumberAndExpiration(java.security.Principal, com.aoapps.payments.CreditCard, java.lang.String, byte, short, java.lang.String)

updateCreditCardExpiration

void updateCreditCardExpiration(CreditCard creditCard,
 byte expirationMonth,
 short expirationYear)
                         throws UnsupportedOperationException,
IOException

Updates the credit card expiration in the secure storage, card expiration on creditCard are not changed.

Throws:

UnsupportedOperationException - when not supported

IOException - when unable to contact the bank

See Also:

• canStoreCreditCards()
• CreditCardProcessor.updateCreditCardExpiration(java.security.Principal, com.aoapps.payments.CreditCard, byte, short)

deleteCreditCard

void deleteCreditCard(CreditCard creditCard)
               throws UnsupportedOperationException,
IOException

Deleted the credit card from the provider's secure storage.

Throws:

UnsupportedOperationException - when not supported

IOException - when unable to contact the bank

See Also:

• CreditCardProcessor.deleteCreditCard(java.security.Principal, com.aoapps.payments.CreditCard)

canGetTokenizedCreditCards

boolean canGetTokenizedCreditCards()
                            throws IOException

Queries the provider to see if they support retrieving the list of cards from the secure storage of credit cards.

Throws:

IOException - when unable to contact the bank

See Also:

• getTokenizedCreditCards(java.util.Map, java.io.PrintWriter, java.io.PrintWriter, java.io.PrintWriter)
• CreditCardProcessor.synchronizeStoredCards(java.security.Principal, java.io.PrintWriter, java.io.PrintWriter, java.io.PrintWriter, boolean)

getTokenizedCreditCards

Map<String,TokenizedCreditCard> getTokenizedCreditCards(Map<String,CreditCard> persistedCards,
 PrintWriter verboseOut,
 PrintWriter infoOut,
 PrintWriter warningOut)
                                                 throws UnsupportedOperationException,
IOException

Gets all stored credit cards, with optional replacement masked card numbers and/or expiration dates.

The returned map must be unmodifiable.

Returns:

The unmodifiable mapping of stores cards from TokenizedCreditCard.getProviderUniqueId() to TokenizedCreditCard.

Throws:

UnsupportedOperationException - when not supported

IOException - when unable to contact the bank

See Also:

• canStoreCreditCards()
• canGetTokenizedCreditCards()
• CreditCardProcessor.synchronizeStoredCards(java.security.Principal, java.io.PrintWriter, java.io.PrintWriter, java.io.PrintWriter, boolean)
• PersistenceMechanism.getCreditCards(java.security.Principal, java.lang.String)