...
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.
| Type | Usage |
|---|---|
| card_number_invalid | Use whenever a credit card number is invalid. |
| card_expired | Use whenever a credit card has expired. |
| routing_number_invalid | Use whenever a routing number is invalid. |
| account_number_invalid | Use whenever an account number is invalid. |
| duplicate_transaction | Use whenever a duplicate transaction has been detected. |
| card_not_accepted | Use whenever a credit card type is not accepted. |
| invalid_security_code | Use whenever the credit card security code provided is invalid. |
| address_verification_failed | Use whenever the address provided is invalid. |
| transaction_not_found | Use whenever processing a capture, refund, or void and the original transaction can not be found. |
| unsupported | Use whenever the gateway does not support the requested action (e.g. refundCc()) |
| general | Use for all other cases. |
| Note | ||
|---|---|---|
| ||
Do not trigger an error response for declined payments, Blesta will automatically issue the appropriate error. |
...
| Code Block | ||
|---|---|---|
| ||
$this->Input->setErrors($this->getCommonError("unsupported")); |
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.
- MerchantCc found in /installpath/components/gateways/lib/merchant_cc.php
- MerchantAch found in /installpath/components/gateways/lib/merchant_ach.php
- MerchantCcOffsite found in /installpath/components/gateways/lib/merchant_cc_offsite.php
- MerchantAchOffsite found in /installpath/components/gateways/lib/merchant_ach_offsite.php
- MerchantCcForm found in /installpath/components/gateways/lib/merchant_cc_form.php
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 interface allows for the replacement of credit card forms in Blesta with one generated by the gateway. This is typically for use in authorizing payments using tokens for credit cards 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 Feature | MerchantCc | MerchantAch | MerchantCcOffsite | MerchantAchOffsite | MerchantCcForm |
|---|---|---|---|---|---|
| Accept Credit Cards | Yes | No | Maybe | No | Yes |
| Accept Bank Transfers | No | Yes | No | Maybe | No |
| Allow Credit Card Account Storage | Maybe | No | Yes | No | Maybe |
| Allow Bank Account Storage | No | Maybe | No | Yes | No |
| Allow Tokenized Credit Cards | Maybe | No | Maybe | No | Yes |
| Allow Client-Side Only Card Forms | No | No | No | No | Yes |