The SDK includes a sample Merchant Gateway to get you started.

Merchant Gateways must extend the MerchantGateway class and implement at least one of the four interfaces provided by the payment system, to ensure proper functionality and integration.


The MerchantGateway class is an abstract class that defines methods that all merchant gateways must implement. In addition, it implements a set of overwritable helper methods to handle common errors as well as HTTP requests, and extends the Gateway class which can be found in /installpath/components/gateways/lib/gateway.php.

The MerchantGateway class can be found in /installpath/components/gateways/lib/merchant_gateway.php.

Common Errors

When implementing merchant gateways a number of errors may occur either with validation or with processing. The MerchantGateway class provides a method called getCommonError(), which converts common error types into error response values suitable for error message passing (i.e. can be set into Input::setErrors()). You are encouraged, whenever possible, to use these common error types.

card_number_invalidUse whenever a credit card number is invalid.
card_expiredUse whenever a credit card has expired.
routing_number_invalidUse whenever a routing number is invalid.
account_number_invalidUse whenever an account number is invalid.
duplicate_transactionUse whenever a duplicate transaction has been detected.
card_not_acceptedUse whenever a credit card type is not accepted.
invalid_security_codeUse whenever the credit card security code provided is invalid.
address_verification_failedUse whenever the address provided is invalid.

Use whenever processing a capture, refund, or void and the original transaction can not be found.

unsupportedUse whenever the gateway does not support the requested action (e.g. refundCc())

Use for all other cases.

Do not trigger an error response for declined payments, Blesta will automatically issue the appropriate error.

Setting Errors


Merchant Interfaces

There are four merchant gateway interfaces, each with its own unique set of method requirements. A payment gateway must implement at least one of these interfaces.

Both the MerchantCc and MerchantAch interfaces allow for the capturing, returning, and voiding of funds with account information stored within Blesta. The MerchantCc interface handles credit cards, while the MerchantAch interface handles bank account transfers.

The MerchantCcOffsite and MerchantAchOffsite interfaces allow for the capturing, returning, and voiding of funds stored with the gateway processor. In addition, these interfaces define methods allowing payment account details to be stored, updated, and removed from the gateway processor. Again, the MerchantCcOffsite interface handles credit cards, while the MerchantAchOffsite interfaces handles bank account transfers.

The MerchantCcForm and MerchantAchForm interface allows for the replacement of credit card or ach forms in Blesta with one generated by the gateway. This is typically for use in authorizing payments using tokens for credit cards or bank accounts that are not sent through Blesta.

The following table will help identify which interfaces should be implemented for a payment gateway based upon the features of that payment processor.

Processor FeatureMerchantCcMerchantAchMerchantCcOffsiteMerchantAchOffsiteMerchantCcFormMerchantAchForm
Accept Credit CardsYesNoMaybeNoYesNo
Accept Bank TransfersNoYesNoMaybeNoYes
Allow Credit Card Account StorageMaybeNoYesNoMaybeNo
Allow Bank Account StorageNoMaybeNoYesNoMaybe
Allow Tokenized Credit CardsMaybeNoMaybeNoYesNo
Allow Client-Side Only FormsNoNoNoNoYesYes