Payment Gateway Common has several "providers" that should be used to actually get access to the underlying components. These allow the system to have multiple configured payment gateway implementations such as one that can handle credit cards and one that can handle gift cards. The providers will select the correct component for a given gateway type, represented as a string.
For example if you wanted to get the appropriate PaymentGatewayTransactionService to confirm a payment, you would simply inject the PaymentGatewayTransactionServiceProvider and call #getTransactionService(String).
@Service
@lombok.RequiredArgsConstructor
public class MyPaymentService {
private final PaymentGatewayTransactionServiceProvider transactionServiceProvider;
PaymentGatewayTransactionService getTransactionServiceForPayment(final MyPayment payment) {
final String gatewayType = payment.getGatewayType();
return transactionServiceProvider.getTransactionService(gatewayType);
}
}This is facilitated by every relevant component, such as PaymentGatewayTransactionService, also implementing the method PaymentGatewayTypeAware#getGatewayType() (see PaymentGatewayTypeAware).
In the case of a PayPal Express Checkout module, the service could return PAYPAL_CHECKOUT as the type, and every payment created for PayPal would include that gateway type on its DTO.
PaymentGatewayConfigurationProvider.
See PaymentGatewayConfiguration also.
PaymentGatewayTransactionServiceProvider.
See PaymentGatewayTransactionService also.
PaymentGatewayRollbackServiceProvider.
See PaymentGatewayTransactionService also.
PaymentGatewayClientTokenServiceProvider.
See PaymentGatewayClientTokenService also.
PaymentGatewayCreditCardServiceProvider.
See PaymentGatewayCreditCardService also.
PaymentGatewayCustomerServiceProvider.
See PaymentGatewayCustomerService also.
PaymentGatewayFraudServiceProvider.
See PaymentGatewayFraudService also.
PaymentGatewayHostedServiceProvider.
See PaymentGatewayHostedService also.
PaymentGatewayReportingServiceProvider.
See PaymentGatewayReportingService also.
PaymentGatewaySubscriptionServiceProvider.
See PaymentGatewaySubscriptionService also.
PaymentGatewayTransparentRedirectServiceProvider.
See PaymentGatewayTransparentRedirectService also.
PaymentGatewayWebResponseServiceProvider.
See PaymentGatewayWebResponseService also.
|
Warning
|
For most of these components, not all methods can be implemented for every gateway and may throw an UnsupportedOperationException.
Use PaymentGatewayConfiguration to define what operations are allowed and refer to it before making calls.
|
|
Important
|
Please check the documentation of the implementing module to determine intended goal of different operations. |
PaymentGatewayConfiguration: Defines the specific operations (e.g., authorize, capture, refund) that a gateway implementation currently supports.
This helps callers of PaymentGatewayTransactionService and others avoid UnsupportedOperationException for any methods not implemented.
PaymentGatewayTransactionService: Provides the means to create billable credit card transactions.
The intention of the provided methods is to make a server-to-server API call. However, the details of how each implementation handles the calls varies.
Consider the case where we try to authorize a payment. A gateway implementation may:
Send credit card information directly (server to server) to the gateway to perform the transaction
Confirm an authorization process (some gateways don’t handle a token based process through a transparent redirect)
Handle both the above (the implementation will do one or the other based on the passed in parameters).
PaymentGatewayRollbackService: This API allows each module to provide its own implementation for rollback handling.
Each module needs to implement this if for some reason the checkout workflow fails after payments have been finalized and the submitted transaction needs to rollback. The details of how each implementation handles the calls varies.
Consider the case where we try to rollback a captured payment. A gateway implementation may:
Issue a refund
Void the payment
PaymentGatewayTransactionConfirmationService: This API is intended to be called during the Checkout Workflow to confirm all Payments on the cart that have not yet been confirmed/finalized.
Note: Not all Gateways allow confirmation.
In the case where an error is thrown by the gateway and confirming is not possible, the workflow should invoke the rollback handlers on any Payments that have already been successfully confirmed.
The this can be determined using the PaymentRequest#completeCheckoutOnCallback flag.
If this value is set to true, then the gateway does not support confirming the transaction, as it assumes to be the final step in the completion process.
Most Credit Card integrations do not support confirming the transaction. Third Party providers like PayPal Express do and should implement this interface.
PaymentGatewayClientTokenService: The intention of this API is to generate the necessary parameters and fields needed by the payment gateway’s JavaScript library in order to create a tokenization request.
These parameters will be placed on the PaymentResponse for consumption by a client application or template.
PaymentGatewayCreditCardService: Several payment gateways allow you to manage Customer and Credit Card Information from the gateway allowing you to create a transaction from the tokenized customer or payment method at a later date.
Note: These are usually extra features you need to pay for when you sign up with the Gateway
PaymentGatewayCustomerService: Several payment gateways allow you to manage Customer and Credit Card Information from the gateway allowing you to create a transaction from the tokenized customer or payment method at a later date.
Note: These are usually extra features you need to pay for when you sign up with the Gateway
PaymentGatewayFraudService: This API allows you to call certain fraud prevention APIs exposed from the gateway.
Certain Payment Integrations allow you to use Fraud Services like Address Verification and Buyer Authentication.
PaymentGatewayHostedService: This API allows you to create the call to send a user to the Gateway’s Hosted page and to capture and record transaction responses back from them.
Certain Payment Integrations allow you to use a Hosted Solution, such as PayPal Express and SagePay Form.
PaymentGatewayReportingService: This API provides the ability to get the status of a Transaction after it has been submitted to the Gateway.
Gateways have different ways to provide this information. For example, Cybersource can provide a nightly feed or FTP file that contain details of what was SETTLED, CHARGEBACK, etc. to be reconciled in your system. Braintree and Paypal have API hooks to either do a date based query or an individual inquiry on a particular transaction.
PaymentGatewaySubscriptionService: Handles requests to manage subscriptions.
Some gateways allow you to create a form of recurring billing by creating a subscription profile.
Note: Some Gateways charge an extra fee to enable this feature
PaymentGatewayTransparentRedirectService: Provides an API that will create any gateway specific parameters needed for a Transparent Redirect, Silent Order Post, etc.
Some payment gateways provide this ability and will generate either a Secure Token or some hashed parameters that will be placed as hidden fields on your Credit Card form. These parameters (along with the Credit Card information) will be placed on the ResponseDTO and your HTML should include these fields to be POSTed directly to the implementing gateway for processing.
Some gateways also support the creation of a payment token (i.e. a tokenized version of a Credit Card that can be used on subsequent requests) outside the scope of an authorize or sale transaction.
PaymentGatewayWebResponseService: Provides an API that will translate a web response returned from a Payment Gateway into a PaymentResponse.
Some payment gateways provide the ability that ensures that the transaction data is passed back to your application when a transaction is completed. Most of the gateways issue an HTML Post to return data to your server for both approved and declined transactions. This occurs even if a customer closes the browser before returning to your site, or if the payment response is somehow severed.
Note: Many gateways will continue calling your exposed API webhook for a certain period until a 200 Response is received. Others will forward to an error page configured through the gateway.
PaymentGatewayCheckoutService: Provides a generic contract for allowing payment modules to add payments to an order represented in Broadleaf while still staying decoupled from any of the Broadleaf core framework concepts.
PaymentGatewayWebResponsePrintService: Defines a utility service that aids in translating the Request Attribute and Request Parameters to a single String.
This is useful when setting the Raw Response fields on a PaymentResponse.
Primarily used in the PaymentGatewayWebResponseService but can be injected anywhere you need to get the attributes or parameters from an HTTPServletRequest as a String.
PaymentGatewayResolver: Resolves a PaymentGatewayType based on a web request.
This is intended to be used by transparent-redirect solutions that utilize Thymeleaf processors and expressions.
Identifies the payment gateway related to a given PaymentRequest or PaymentResponse The expectation is that each payment gateway implementation will implement this interface to define its unique gateway identifier. Components that are tied to specific gateway types should implement PaymentGatewayTypeAware.
|
Tip
|
There is a PASSTHROUGH type provided with this library.
|
Interface marking a component as tied to a specified PaymentGatewayType so that the resource can be easily identified by the various provider services. Services with providers should implement this interface so that the Service Providers can identify them as appropriate.
This is a DTO that is comprised of all the information that is sent to a Payment Gateway to complete a transaction. It uses a modified builder pattern in order to provide an easy way of constructing the request.
You can construct a DTO using the following notation:
|
Important
|
Note that some of the convenience methods generate a new instance of the object. (e.g. billTo, shipTo, etc.).
Therefore, if you need to modify the shipping or billing information after you have invoked requestDTO.shipTo()…, use the getShipTo() method to append more information.
Otherwise, you will overwrite the shipping information with a new instance.
|
PaymentRequest paymentRequest = new PaymentRequest()
.orderId(referenceNumber)
.customer()
.customerId("1")
.done()
.shipTo()
.firstName("Bill")
.lastName("Broadleaf")
.addressLine1("123 Test Dr.")
.city("Austin")
.stateRegion("TX")
.postalCode("78759")
.done()
.billTo()
.firstName("Bill")
.lastName("Broadleaf")
.addressLine1("123 Test Dr.")
.city("Austin")
.stateRegion("TX")
.postalCode("78759")
.done()
.shippingTotal(0)
.taxTotal(0)
.orderDescription("My Order Description")
.orderSubtotal(10.00)
.transactionTotal(10.00)
.lineItem()
.name("My Product")
.description("My Product Description")
.shortDescription("My Product Short Description")
.systemId("1")
.amount(10.00)
.quantity(1)
.itemTotal(10.00)
.tax(0)
.total(10.00)
.done();|
Tip
|
See javadocs. |
This is a DTO object that represents the response coming back from any call to the Gateway. This can either wrap an API result call or a translated HTTP Web response. It can not only be the results of a transaction, but also a request for a Secure Token, etc.
|
Note
|
The success and validity flags are set to true by default, unless otherwise overridden by specific gateway implementations |
|
Tip
|
See javadocs. |