PaymentGatewayPaymentValidator: Validator meant to ensure that PaymentTransactionServices Payment objects are sufficiently populated to later execute transactions via the related PaymentGatewayTransactionService implementation.
PaymentGatewayTransactionService: Implementations of this interface are responsible for making API calls with the payment gateway to execute payment transactions.
Supported transaction types: Authorize, AuthorizeAndCapture, ReverseAuthorize, Capture, Refund, & DetachedCredit
Note: Some integrations may not support all of these transaction types. In that case, just implement the values that are relevant for your integration.
PaymentGatewayRollbackService: Implementations of this interface are responsible for making API calls with the payment gateway to reverse payment transactions that were executed via the PaymentGatewayTransactionService.
Note: Typically this implementation injects the gateway’s PaymentGatewayTransactionService bean & calls the relevant transactions.
PaymentGatewayConfiguration: Implementations of this interface declare the supported transaction types & features for the gateway.
PaymentGatewayWebhookHandler: Implementations of this interface are meant to take in webhook requests from the payment gateway, validate the request, interpret the transaction results, & build the API response to be sent to the gateway.
Note: Webhooks are typically a secondary means of gathering transaction results, but they are required for some gateways.
PaymentGateway3DSTransactionLookupService: Implementations of this interface are used within the checkout process to interpret and/or look up the results of a transaction that required 3DS verification.
PaymentGatewaySavedPaymentMethodService: Implementations of this interface leverage a hook in the PaymentTransactionServices add SavedPaymentMethod logic to manipulate the SavedPaymentMethod#paymentMethodProperties.
Typically this is used when the gateway’s frontend integration provides a single-use credit card token that must be swapped for a multi-use credit card token via a backend interaction.
PaymentGatewayReportingService: Implementations of this interface provide the ability to get the status of a transaction after it has been submitted to the gateway.
PaymentGatewayCustomerService: Implementations of this interface provide the ability to manage the gateway’s representation of a customer.
PaymentGatewayHostedService: Implementations of this interface are used to execute setup requests for the gateway’s hosted payment page.
PaymentGatewayTransactionResponseValidator: Implementations of this interface are responsible for validating transaction results that were provided via the Record Transaction Results PaymentTransactionServices API. Note: this endpoint is only used when the transaction was executed outside of PaymentTransactionServices.
Note: This service should be implemented in combination with PaymentGatewayTransactionResponseService.
PaymentGatewayTransactionResponseService: Implementations of this interface are responsible for interpreting transaction results that were provided via the Record Transaction Results PaymentTransactionServices API. Note: this endpoint is only used when the transaction was executed outside of PaymentTransactionServices.
Note: This service should be implemented in combination with PaymentGatewayTransactionResponseValidator.
To simultaneously support multiple payment gateway integrations, each of the service interfaces mentioned above extend the PaymentGatewayTypeAware interface. In doing so, each implementation must declare its relevant gateway type (e.g. CHECKOUT_COM vs STRIPE). From there, we use DefaultPaymentGatewayResourceProvider to collect all the implementation beans for each integration and make them accessible by gateway type.
For example if you wanted to get the appropriate PaymentGatewayTransactionService to execute a transaction on a payment, you would simply call PaymentGatewayResourceProvider#getTransactionService("MY_GATEWAY_TYPE").
@Service
@lombok.RequiredArgsConstructor
public class MyPaymentService {
private final PaymentGatewayResourceProvider paymentGatewayResourceProvider;
PaymentGatewayTransactionService getTransactionServiceForPayment(final Payment payment) {
final String gatewayType = payment.getGatewayType();
return paymentGatewayResourceProvider.getTransactionService(gatewayType);
}
}This PaymentRequest DTO is meant to communicate all the necessary information to execute a transaction with the payment gateway. The expectation is that the core services will take in this payload & map its values into API requests sent to the payment gateway.
When PaymentTransactionServices produces a PaymentRequest, the most important properties that it supplies are:
PaymentRequest#paymentOwnerType & PaymentRequest#paymentOwnerId - The type & id of the owning entity (typically BLC_CART & the cart id)
PaymentRequest#paymentId - Id of the PaymentTransactionServices Payment
PaymentRequest#transactionTotal - The amount that will be used for the transaction
PaymentRequest#transactionReferenceId - This value represents Broadleaf’s unique identifier for the transaction. Passing this value to the payment gateway as part of the transaction payload, creates a link between our representation of the transaction & the gateway’s representation. If something goes wrong with the interaction & we’re unsure of the transaction results, we can use this value to lookup results.
PaymentRequest#additionalFields - General-use map that should contain references to whatever data points are needed to complete the transaction. In some cases, this is a reference to a payment method (e.g. a credit card token). In other cases, this is a reference to a previous transaction.
Credit Card CVV - Some gateways require, or optionally allow, the CVV to be provided when executing transactions for saved payment methods. If this data is included in the PaymentRequest, then it must never be logged or persisted.
PaymentRequest#applicationId & PaymentRequest#tenantId - Describe the context of the request, which is used to identify the correct API credentials for the interaction
PaymentRequest#createMultiUseToken - Declares if a multi-use token should be produced as part of the gateway interaction
|
Tip
|
See javadocs. |
The PaymentResponse DTO is responsible for communicating the result of the transaction in a common structure that PaymentTransactionServices can use to record transaction results. The primary goal of the response is to provide as much information as possible, some that we gather from the PaymentRequest & some that we gather from the gateway’s response.
When interpreting a payment gateway’s response for a transaction, it’s important that the following properties are declared in the PaymentResponse:
PaymentResponse#success - Was the interaction successful?
PaymentResponse#awaitingAsyncResults - Declares if transaction results are available, or if they’ll be delivered asynchronously (e.g. via a webhook)
PaymentResponse#responseMap - General use map that must include any properties required for subsequent transactions. For example, Authorize transactions often produce a reference (payment or transaction id) that must be used to execute a Capture or ReverseAuthorize transaction.
PaymentResponse#gatewayTransactionId - The gateway’s unique identifier for the transaction
PaymentResponse#gatewayTransactionType - The gateway’s name for the type of interaction
PaymentResponse#gatewayResponseCode - The gateway’s response code
PaymentResponse#failureType - If the transaction failed, this field will represent our categorization of the failure. See DefaultTransactionFailureTypes. The mapping of gatewayResponseCode to failureType should be done in each gateway integration.
PaymentResponse#message - Simple message describing the result of the interaction
PaymentResponse#threeDSecureVerificationUrl - URL where the customer must be redirected, if 3DS verification is required
PaymentResponse#rawResponse - A string representation of the response that came from the gateway
PaymentResponse#paymentMethodProperties - Map that should contain a reference to a multi-use token, if one was produced as part of the interaction
|
Tip
|
Use the DefaultPaymentResponseUtil to populate the PaymentResponse with data from the PaymentRequest, before populating data from the API response. |
|
Tip
|
See javadocs. |