- v1.0.0-latest-prod
This library contains resources and concepts to support integrating with a variety of payment gateways.
Implementations of this library’s interfaces are meant to communicate directly with the payment gateway’s APIs to execute payment transactions & manage payment method representations (e.g. credit card tokens). These implementations are meant to be registered with PaymentTransactionServices to surface common endpoints & provide a means of tracking payment transactions relative to carts, fulfillments, returns, etc.
Before you begin integrating with your desired payment gateway, it’s important to understand how the overall integration will align with Broadleaf’s expectations & components. It will be helpful to review the Checkout Payment Architecture and OMS Payment Architecture documents to get a better sense of Broadleaf’s most common (and preferred) payment integration pattern.
Although all gateways have their own mechanisms of accepting and passing information back and forth, they all tend to follow similar patterns. The key is figuring out which pattern it falls into, making it easier to determine which of the Broadleaf Payment Gateway Interfaces should be implemented.
One way to help determine which communication mechanisms the gateways implement is to take note as you read through the Gateways documentation and answer the following questions. Once you have the answers to these questions laid out, you may be able to start seeing where it all fits in terms of interfaces provided by Broadleaf. Now you can begin Creating a Payment Gateway Module.
Does the gateway support credit card tokenization?
Is this a Hosted Solution? Will the customer see a button on the Cart or Checkout screen which when clicked will be redirected out of your site to a Hosted Payment Page where payment/billing information is collected?
Is this a Silent Post/Transparent Redirect Solution where Credit Card information is collected on a form managed on your end which will then be POST’ed directly to the Payment Gateway for processing?
They may simply respond to your API requests
They may send back a 302 Redirect Response to the browser with some information about the transaction (e.g. a token to get details of what happened)
They may send back a 200 Response to a URL you specify with a hidden form that contains the result of the transaction. This form will then automatically submit itself using JavaScript.
They may POST the transaction information directly to a publicly available URL on your system which will wait for a response back from you to relay back to the customer’s browser.
Due to the vast differences in how gateways are implemented, errors/failures can happen in a variety of places within the payment process. It’s important to understand where these errors can happen and how you and the gateway will deal with those errors in the event that one occurs. For example:
If the communication pattern is to POST the transaction results back to a publicly available URL, the Gateway may wait on a 200 response back from you to deem it a successful transaction. If there was an error completing checkout on your end, you can send back a 500 error and the gateway may be configured to automatically VOID the charged card. Again, this form of error handling is SPECIFIC to one particular gateway and may be completely different for other gateways. In many cases, the Payment Gateway will charge the card and send you back a response. If for some reason an error occurs processing that response and completing checkout, it is up to you to manually VOID that payment if necessary. Therefore, you may need to implement the Rollback interfaces in order to handle these error flows.
In some cases, we may find it necessary to pass some additional information that we would need passed back to us in the response. For example:
One gateway provides an API to send extra custom fields that are pass through fields. In some of the modules built by Broadleaf, these fields may be used to hold identifying information about the Broadleaf Cart/Order. Many gateways allow this, and it is important to keep in mind as you begin developing your solution.
It’s important to understand the lifecycle of a Payment Transaction and how its state can affect which operations can be performed next.
The default transaction types are as follows as defined by DefaultTransactionTypes:
AUTHORIZE: Funds have been authorized (reserved) for capture (transfer).
This might appear as a 'pending' transaction on a customer’s credit card statement.
REVERSE_AUTH: The reverse of an AUTHORIZE.
This can only occur after funds have been authorized and before funds have been captured.
If already captured, use REFUND as appropriate: see Reverse Authorize, Capture, Void, and Refund
CAPTURE: Funds have been transferred (charged, submitted, debited) from the customer and payment is complete.
AUTHORIZE_AND_CAPTURE: Funds have been captured and authorized all at once.
While this might be the simplest to implement from an order management perspective, the recommended approach is to AUTHORIZE during checkout in one transaction, then CAPTURE at time of fulfillment with another transaction
REFUND: Funds have been refunded/credited.
This can only occur after funds have been captured or settled.
This should only be used when money goes back to a customer.
This assumes that there will be a parent CAPTURE or AUTHORIZE_AND_CAPTURE transaction that it can be tied back to.
Note: This can also be referred to as a "follow-on credit".
Less common transaction types:
DETACHED_CREDIT: Some payment processors allow you to issue credit to a customer that is not tied to an initial AUTHORIZE or AUTHORIZE_AND_CAPTURE transaction.
Most payment gateways disable this feature by default because it is against card association (e.g. Visa, MasterCard) rules. However, there may be legitimate instances where you had a sale transaction but are not able to issue a refund (e.g. closed account of original payment etc.).
Please contact your payment gateway provider to see how to enable this feature.
This should be configurable by the interface method PaymentGatewayConfiguration#isPerformAuthorizeAndCapture
If this is true, then the system will initiate a payment transaction using PaymentTransactionType.AUTHORIZE_AND_CAPTURE, otherwise it will use PaymentTransactionType.AUTHORIZE.
Once a payment has initially been sent to the processor, it’s state will either be authorized or authorized-and-captured. (Some gateways use the term sale or another term to represent this). From this point, if a transaction is just authorized, you can either reverse-authorize the transaction or capture it.
Once the transaction has been captured, (either from a capture request or from initially creating an authorize-and-capture request), there is period where the money has not left the card issuer’s bank into the merchant’s account. This is known as being submitted for settlement. During this time, and only this time, can a transaction be voided. Once the funds have been transferred, the transaction is considered settled.
Once a transaction has been settled, then, and only then, will you have the ability to refund the transaction.
It’s important to note that some Gateways may have slightly different terminology, but the concepts are the same. Also, some Gateway SDKs may combine the reverse-authorize and void methods into just void, as the processor will know what to do based on it’s current state. Please read your gateway’s implementation for details.