Requests
3 years ago
Responses
3 years ago
Response.php
3 years ago
Response_Message_Helper.php
3 years ago
Response_Message_Helper.php
157 lines
| 1 | <?php |
| 2 | /** |
| 3 | * WooCommerce Square |
| 4 | * |
| 5 | * This source file is subject to the GNU General Public License v3.0 |
| 6 | * that is bundled with this package in the file license.txt. |
| 7 | * It is also available through the world-wide-web at this URL: |
| 8 | * http://www.gnu.org/licenses/gpl-3.0.html GNU General Public License v3.0 or later |
| 9 | * If you did not receive a copy of the license and are unable to |
| 10 | * obtain it through the world-wide-web, please send an email |
| 11 | * to license@woocommerce.com so we can send you a copy immediately. |
| 12 | * |
| 13 | * DISCLAIMER |
| 14 | * |
| 15 | * Do not edit or add to this file if you wish to upgrade WooCommerce Square to newer |
| 16 | * versions in the future. If you wish to customize WooCommerce Square for your |
| 17 | * needs please refer to https://docs.woocommerce.com/document/woocommerce-square/ |
| 18 | * |
| 19 | * @author WooCommerce |
| 20 | * @copyright Copyright: (c) 2019, Automattic, Inc. |
| 21 | * @license http://www.gnu.org/licenses/gpl-3.0.html GNU General Public License v3.0 or later |
| 22 | */ |
| 23 | |
| 24 | namespace WooCommerce\Square\Gateway\API; |
| 25 | |
| 26 | defined( 'ABSPATH' ) || exit; |
| 27 | |
| 28 | /** |
| 29 | * WooCommerce Payment Gateway API Response Message Helper |
| 30 | * |
| 31 | * This utility class is meant to provide a standard set of error messages to be |
| 32 | * displayed to the customer during checkout. |
| 33 | * |
| 34 | * Most gateways define a plethora of error conditions, some of which a customer |
| 35 | * can resolve on their own, and others which must be handled by the admin/ |
| 36 | * merchant. It's not always clear which conditions should be reported to a |
| 37 | * customer, or what the best wording is. This utility class seeks to ease |
| 38 | * the development burden of handling customer-facing error messages by |
| 39 | * defining a set of common error conditions/messages which can be used by |
| 40 | * nearly any gateway. |
| 41 | * |
| 42 | * This class, or a subclass, should be instantiated by the API response object, |
| 43 | * which will use a gateway-specific mapping of error conditions to message, |
| 44 | * and returned by the `Payment_Gateway_API_Response::get_user_message()` |
| 45 | * method implementation. Add new common/generic codes and messages to this |
| 46 | * base class as they are encountered during gateway integration development, |
| 47 | * and use a subclass to include any gateway-specific codes/messages. |
| 48 | * |
| 49 | * @since 2.2.3 |
| 50 | */ |
| 51 | class Response_Message_Helper { |
| 52 | |
| 53 | |
| 54 | /** |
| 55 | * Returns a message appropriate for a frontend user. This should be used |
| 56 | * to provide enough information to a user to allow them to resolve an |
| 57 | * issue on their own, but not enough to help nefarious folks fishing for |
| 58 | * info. |
| 59 | * |
| 60 | * @since 2.2.3 |
| 61 | * |
| 62 | * @param string[] $message_ids array of string $message_id's which identify the message(s) to return |
| 63 | * @return string a user message, combining all $message_ids |
| 64 | */ |
| 65 | public function get_user_messages( $message_ids ) { |
| 66 | $messages = array(); |
| 67 | |
| 68 | foreach ( $message_ids as $message_id ) { |
| 69 | $messages[] = $this->get_user_message( $message_id ); |
| 70 | } |
| 71 | |
| 72 | $messages = implode( '<br>', $messages ); |
| 73 | |
| 74 | return trim( $messages ); |
| 75 | } |
| 76 | |
| 77 | |
| 78 | /** |
| 79 | * Returns a message appropriate for a frontend user. This should be used |
| 80 | * to provide enough information to a user to allow them to resolve an |
| 81 | * issue on their own, but not enough to help nefarious folks fishing for |
| 82 | * info. |
| 83 | * |
| 84 | * @since 2.2.3 |
| 85 | * @param string $message_id identifies the message to return |
| 86 | * @return string a user message |
| 87 | */ |
| 88 | public function get_user_message( $message_id ) { |
| 89 | $error_codes = array( |
| 90 | // ErrorCodes from https://developer.squareup.com/docs/payments-api/error-codes |
| 91 | 'BAD_EXPIRATION' => esc_html__( 'The card expiration date is missing or incorrectly formatted.', 'woocommerce-square' ), |
| 92 | 'INVALID_ACCOUNT' => esc_html__( 'An error occurred, please try again or try an alternate form of payment.', 'woocommerce-square' ), |
| 93 | 'CARDHOLDER_INSUFFICIENT_PERMISSIONS' => esc_html__( 'The card issuer has declined the transaction due to restrictions on where the card can be used.', 'woocommerce-square' ), |
| 94 | 'INSUFFICIENT_PERMISSIONS' => esc_html__( 'An error occurred, please try again or try an alternate form of payment.', 'woocommerce-square' ), |
| 95 | 'INSUFFICIENT_FUNDS' => esc_html__( 'The payment source has insufficient funds to cover the payment.', 'woocommerce-square' ), |
| 96 | 'INVALID_LOCATION' => esc_html__( 'An error occurred, please try again or try an alternate form of payment.', 'woocommerce-square' ), |
| 97 | 'TRANSACTION_LIMIT' => esc_html__( 'The card issuer has determined the payment amount is too high or too low.', 'woocommerce-square' ), |
| 98 | 'CARD_EXPIRED' => esc_html__( 'The card issuer declined the request because the card is expired.', 'woocommerce-square' ), |
| 99 | 'CVV_FAILURE' => esc_html__( 'The card issuer declined the request because the CVV value is invalid.', 'woocommerce-square' ), |
| 100 | 'ADDRESS_VERIFICATION_FAILURE' => esc_html__( 'The card issuer declined the request because the postal code is invalid.', 'woocommerce-square' ), |
| 101 | 'TEMPORARY_ERROR' => esc_html__( 'A temporary internal error occurred. You can safely retry the payment.', 'woocommerce-square' ), |
| 102 | 'PAN_FAILURE' => esc_html__( 'The specified card number is invalid.', 'woocommerce-square' ), |
| 103 | 'EXPIRATION_FAILURE' => esc_html__( 'The card expiration date is invalid or indicates that the card is expired.', 'woocommerce-square' ), |
| 104 | 'CARD_NOT_SUPPORTED' => esc_html__( 'The card is not supported in the geographic region.', 'woocommerce-square' ), |
| 105 | 'INVALID_POSTAL_CODE' => esc_html__( 'The postal code is incorrectly formatted.', 'woocommerce-square' ), |
| 106 | 'PAYMENT_LIMIT_EXCEEDED' => esc_html__( 'Square declined the request because the payment amount exceeded the processing limit for this seller.', 'woocommerce-square' ), |
| 107 | 'REFUND_DECLINED' => esc_html__( 'The card issuer declined the refund.', 'woocommerce-square' ), |
| 108 | 'GENERIC_DECLINE' => esc_html__( 'An error occurred, please try again or try an alternate form of payment.', 'woocommerce-square' ), |
| 109 | |
| 110 | // ErrorCodes not listed under Square Docs |
| 111 | 'INVALID_EXPIRATION' => esc_html__( 'The card expiration date is invalid or indicates that the card is expired.', 'woocommerce-square' ), |
| 112 | |
| 113 | // ErrorCodes from SV Framework - https://github.com/skyverge/wc-plugin-framework/blob/master/woocommerce/payment-gateway/api/class-sv-wc-payment-gateway-api-response-message-helper.php |
| 114 | 'ERROR' => esc_html__( 'An error occurred, please try again or try an alternate form of payment.', 'woocommerce-square' ), |
| 115 | 'DECLINE' => esc_html__( 'We cannot process your order with the payment information that you provided. Please use a different payment account or an alternate payment method.', 'woocommerce-square' ), |
| 116 | 'HELD_FOR_REVIEW' => esc_html__( 'This order is being placed on hold for review. Please contact us to complete the transaction.', 'woocommerce-square' ), |
| 117 | 'HELD_FOR_INCORRECT_CSC' => esc_html__( 'This order is being placed on hold for review due to an incorrect card verification number. You may contact the store to complete the transaction.', 'woocommerce-square' ), |
| 118 | 'CVV_FAILURE' => esc_html__( 'The card verification number is invalid, please try again.', 'woocommerce-square' ), |
| 119 | 'CSC_MISSING' => esc_html__( 'Please enter your card verification number and try again.', 'woocommerce-square' ), |
| 120 | 'UNSUPPORTED_CARD_BRAND' => esc_html__( 'That card type is not accepted, please use an alternate card or other form of payment.', 'woocommerce-square' ), |
| 121 | 'INVALID_CARD' => esc_html__( 'The card type is invalid or does not correlate with the credit card number. Please try again or use an alternate card or other form of payment.', 'woocommerce-square' ), |
| 122 | 'CARD_TYPE_MISSING' => esc_html__( 'Please select the card type and try again.', 'woocommerce-square' ), |
| 123 | 'CARD_NUMBER_TYPE_INVALID' => esc_html__( 'The card type is invalid or does not correlate with the credit card number. Please try again or use an alternate card or other form of payment.', 'woocommerce-square' ), |
| 124 | 'INVALID_EXPIRATION' => esc_html__( 'The card expiration date is invalid, please re-enter and try again.', 'woocommerce-square' ), |
| 125 | 'INVALID_EXPIRATION_YEAR' => esc_html__( 'The card expiration year is invalid, please re-enter and try again.', 'woocommerce-square' ), |
| 126 | 'CARD_EXPIRY_MISSING' => esc_html__( 'Please enter your card expiration date and try again.', 'woocommerce-square' ), |
| 127 | 'BANK_ABA_INVALID' => esc_html__( 'The bank routing number is invalid, please re-enter and try again.', 'woocommerce-square' ), |
| 128 | 'BANK_ACCOUNT_NUMBER_INVALID' => esc_html__( 'The bank account number is invalid, please re-enter and try again.', 'woocommerce-square' ), |
| 129 | 'CARD_DECLINED' => esc_html__( 'The provided card was declined, please use an alternate card or other form of payment.', 'woocommerce-square' ), |
| 130 | 'CARD_INACTIVE' => esc_html__( 'The card is inactivate or not authorized for card-not-present transactions, please use an alternate card or other form of payment.', 'woocommerce-square' ), |
| 131 | 'TRANSACTION_LIMIT' => esc_html__( 'The credit limit for the card has been reached, please use an alternate card or other form of payment.', 'woocommerce-square' ), |
| 132 | 'VERIFY_CVV_FAILURE' => esc_html__( 'The card verification number does not match. Please re-enter and try again.', 'woocommerce-square' ), |
| 133 | 'AVS_MISMATCH' => esc_html__( 'The provided address does not match the billing address for cardholder. Please verify the address and try again.', 'woocommerce-square' ), |
| 134 | ); |
| 135 | |
| 136 | $message = null; |
| 137 | |
| 138 | if ( array_key_exists( $message_id, $error_codes ) ) { |
| 139 | $message = $error_codes[ $message_id ]; |
| 140 | } |
| 141 | |
| 142 | /** |
| 143 | * Payment Gateway API Response User Message Filter. |
| 144 | * |
| 145 | * Allow actors to modify the error message returned to a user when a transaction |
| 146 | * has encountered an error and the admin has enabled the "show detailed |
| 147 | * decline messages" setting |
| 148 | * |
| 149 | * @since 2.2.3 |
| 150 | * @param string $message message to show to user |
| 151 | * @param string $message_id machine code for the message, e.g. card_expired |
| 152 | * @param Response_Message_Helper $this instance |
| 153 | */ |
| 154 | return apply_filters( 'wc_payment_gateway_transaction_response_user_message', $message, $message_id, $this ); |
| 155 | } |
| 156 | } |
| 157 |