Recurly

Transaction Errors

When Recurly encounters an error submitting a payment to your gateway, it parses the error code. From your gateway's error code, Recurly generates a friendly error message that can be displayed to your user and returns it in the XML error document. In addition, Recurly sets a code on the error document to let you know exactly why the transaction was declined. These errors can be returned when you are creating a new subscription, updating billing information, and processing a one-time transaction.

Error Codes

The following error codes are return by Recurly. The description is specific to the error code to help you understand why it was declined.

approved
Approved
Approved
approved_fraud_review
Approved
Approved, flagged for fraud review in your payment gateway.
declined
The transaction was declined. Please use a different card or contact your bank.
The transaction was declined without specific information. Please contact your payment gateway for more details or ask the customer to contact their bank.
insufficient_funds
The transaction was declined due to insufficient funds in your account. Please use a different card or contact your bank.
The card has insufficient funds to cover the cost of the transaction.
temporary_hold
Your card has a temporary hold. Please use a different card or contact your bank.
The issuing bank has a temporary hold on the card. This is known as a 'Do Not Honor' response.
too_many_attempts
The transaction was declined. You have exceeded a reasonable number of attempts. Please wait a while before retrying your card, or try a different card.
The transaction was declined because of too many authorization attempts.
call_issuer
Your transaction was declined. Please contact your bank for further details or try another card.
The transaction was declined by the payment gateway. Contact the card issuer for more details.
call_issuer_update_cardholder_data
Please contact support: the payment system experienced an unspecified error with your card issuer.
The transaction was declined by the payment gateway. Contact the card issuer for more details.
paypal_primary_declined
Your primary funding source was declined. Please try again or update your billing information with PayPal.
The primary funding source failed but the transaction can be attempted again. The next attempt will use the alternate funding source.
paypal_declined_use_alternate
Your primary funding source was declined. Please try again to use your secondary funding source.
The primary funding source failed but the transaction can be attempted again. The next attempt will use the alternate funding source.
declined_security_code
The security code you entered does not match. Please update the CVV and try again.
The payment gateway declined the transaction because the security code (CVV) did not match.
declined_exception
The transaction was declined. Please try again or try another card.
An exception occurred with your payment gateway while processing this transaction. The transaction may be missing required information or the information is not properly formatted. Please contact your gateway for details.
declined_missing_data
Your billing information is missing some required information.
The payment gateway declined the transaction for missing a required field. Please verify your configuration with Recurly and your gateway is correct. You may need to require more address information.
invalid_data
The transaction was declined due to invalid data.
The payment gateway declined the transaction due to invalid data. Please check the response details for more information.
invalid_email
Your email address is not valid.
The payment gateway requires a valid email address for this transaction.
declined_card_number
Your card number is not valid. Please update your card number.
The credit card number is not valid. The customer needs to try a different number.
invalid_card_number
Your card number is not valid. Please update your card number.
The credit card number is not valid. The customer needs to try a different number.
invalid_account_number
Your account number is not valid. Please update your account number.
The account number is not valid. The customer needs to try a different number.
gateway_token_not_found
Your payment details were not found. Please update your billing information.
The payment details were not found in your payment gateway. The customer needs to update their billing information.
expired_card
Your credit card is expired, please update your card.
The payment gateway declined the transaction because the expiration date is expired or does not match.
declined_expiration_date
Your expiration date is invalid or does not match.
The payment gateway declined the transaction because the expiration date is expired or does not match.
exceeds_daily_limit
The transaction exceeds your daily approval limit. Please contact your bank or try another card.
The transaction exceeds the cardholder's daily approval limit.
invalid_merchant_type
Your card is not allowed to complete this transaction. Please try another card.
The card is not allowed to make purchases from you (e.g. a Travel only card trying to purchase electronics).
invalid_transaction
Your card is not allowed to complete this transaction. Please contact your bank or try another card.
The card type cannot perform the transaction type. The card is likely restricted. The customer needs to contact their bank for details.
invalid_issuer
Your card number is not valid. Please try another card or contact your bank.
The card number references an issuer (bank) that does not exist. It is not a valid card number.
card_type_not_accepted
Your card type is not accepted. Please try another card.
Your merchant account does not accept this card type or specific transaction.
payment_not_accepted
Your payment type is not accepted. Please try another card.
Your merchant account does not accept this payment type or specific transaction.
restricted_card
Your card cannot be accepted. Please contact your issuing bank for details or try another card.
The card number has restrictions that prevent it from being used with your merchant account. It is likely a corporate card. The customer needs to use a different card.
restricted_card_chargeback
Your card cannot be accepted. Please contact your issuing bank for details or try another card.
The card has a restriction preventing approval if there are any chargebacks against it.
card_not_activated
Your card has not been activated. Please call your bank to activate your card and try again.
The card is brand new and has not been activated yet.
deposit_referenced_chargeback
The refund cannot be processed because of a chargeback.
The deposit is already referenced by a chargeback; therefore, a refund cannot be processed against this transaction.
customer_canceled_transaction
You canceled the transaction after it was approved. Please update your billing information to authorize a new transaction.
The cardholder requested this particular payment be stopped before it settled.
cardholder_requested_stop
You requested recurring payments no longer be accepted on this card. Please update your billing information.
The cardholder requested recurring payments be stopped. This card will no longer work with your merchant account.
no_billing_information
Your billing information is not on file. Please add your billing information.
This transaction cannot be processed because Recurly has no billing information for this account.
paypal_invalid_billing_agreement
Your PayPal billing agreement is no longer valid. Please update your billing information.
The billing agreement is no longer valid. The customer may have canceled the agreement.
paypal_hard_decline
Your primary funding source was declined. Please update your billing information with PayPal or try again.
PayPal failed to run the transaction with the primary funding source.
paypal_account_issue
Your primary funding source was declined. Please update your billing information with PayPal or try again.
PayPal indicated the transaction failed due to an issue with the buyer account.
fraud_address
Your billing address does not match the address on your account. Please fix your address or contact your bank.
The payment gateway declined the transaction because the billing address did not match.
fraud_security_code
The security code you entered does not match. Please update the CVV and try again.
The payment gateway declined the transaction because the security code (CVV) did not match.
fraud_stolen_card
The transaction was declined. Please use a different card or contact your bank.
The card has been designated as lost or stolen; contact the issuing bank.
fraud_ip_address
The transaction was declined. Please contact support.
The payment gateway declined the transaction because it originated from an IP address known for fraudulent transactions.
fraud_gateway
The transaction was declined. Please use a different card or contact your bank.
The payment gateway declined the transaction because it originated from an IP address known for fraudulent transactions.
fraud_too_many_attempts
You attempted to use this card too many times. Please wait 15 minutes before trying again, or use a different card.
The card number was used unsuccessfully too many times consecutively. The cardholder must wait before the card number will work again.
fraud_advanced_verification
The transaction was declined. Please use a different card or contact your bank.
The payment gateway declined the transaction because it failed the advanced verification.
invalid_gateway_configuration
Please contact support: the payment system is configured incorrectly. Your card was not charged.
Your payment gateway is not configured correctly. Please contact your payment gateway for more information.
invalid_login
Please contact support: the payment system is configured incorrectly. Your card was not charged.
Your payment gateway login is incorrect. Please check your login credentials.
gateway_unavailable
Please contact support: the payment system experienced an unspecified error with your card issuer.
The payment gateway was unavailable for transaction. Contact your payment gateway for more details.
processor_unavailable
Please contact support: the payment system experienced an unspecified error with your card issuer.
The payment processor was unavailable for the transaction. Contact your payment gateway for more details.
issuer_unavailable
Please contact support: the payment system experienced an unspecified error with your card issuer.
The issuer was unavailable to authorize the transaction. Contact the card issuer or your payment gateway for more details.
gateway_timeout
Please contact support: the payment system did not respond in time to process your transaction.
The payment gateway timed out while processing this transaction. Please verify that the transaction did not process. Contact your payment gateway for more details.
gateway_error
An error occurred while processing your transaction. Please contact support.
The payment gateway encountered an unknown error. Please contact your payment gateway for details.
contact_gateway
Please contact support: the payment system experienced an unspecified error with your card issuer.
This error requires you to contact your payment gateway for a resolution.
try_again
The payment system would like you to please try again.
The payment gateway is too busy or experienced another temporary problem, and cannot process the transaction at the moment. Please try again.
cvv_required
Please contact support: the payment system experienced an error. Your card was not charged.
Your payment gateway account is requiring the security code (CVV) for all transactions. Recurly cannot process recurring/subscription transactions. Please contact your payment gateway to disable the CVV requirement.
currency_not_supported
Please contact support: the requested currency is not supported for this merchant. Your card was not charged.
The currency configured on your Recurly account is not accepted by your gateway. Please use a supported currency or contact your payment gateway for more details.
ssl_error
Please contact support: the payment system experienced an error. Your card was not charged.
Your PEM certificate is configured incorrectly. Recurly cannot communicate with your payment gateway.
zero_dollar_auth_not_supported
Please contact support: the payment system experienced an error while authorizing your card. Your card was not charged.
Zero dollar authorizations are not supported for this card type or by your payment processor.
no_gateway
Please contact support: the payment system experienced an unspecified error with your card issuer.
There is no available payment gateway on your account capable of processing this transaction.
ach_transactions_not_supported
Please contact support: ACH/EFT transfers are not supported.
ACH/EFT transfers are not enabled on your account.
three_d_secure_not_supported
Please contact support: the payment system experienced an error. Your card was not charged.
3D Secure was attempted but is not enabled on your account.
transaction_not_found
The original transaction was not found.
The original transaction was not found.
transaction_settled
The transaction has already been settled, so it cannot be voided. Please try a refund.
The transaction has already been settled, so it cannot be voided. Please try a refund.
transaction_already_voided
The transaction has already been voided, so it cannot be settled or refunded.
The transaction has already been voided, so it cannot be settled or refunded.
transaction_failed_to_settled
The transaction did not settle successfully. Please update your billing information.
The transaction authorized successfully, but failed to settle. The settlement request may have expired or have been canceled.
payment_cannot_void_authorization
An error occurred while voiding your payment authorization. Please contact support.
The credit exceeds the amount of the original transaction.
partial_credits_not_supported
An error occurred while refunding your transaction. Please contact support.
Your payment gateway does not support partially refunding a transaction. Please refund the entire amount.
cannot_refund_unsettled_transactions
An error occurred while refunding your transaction. Please contact support.
The transaction has not settled yet, so it cannot be refunded. Please try voiding the transaction instead.
transaction_cannot_be_refunded
The transaction cannot be refunded. Please contact support.
The transaction cannot be refunded. Please contact your payment gateway for details.
transaction_cannot_be_voided
The transaction cannot be voided. Please contact support.
The transaction cannot be void. It may have settled, already been voided, or otherwise be illegible for voiding. Please contact your payment gateway for details.
total_credit_exceeds_capture
An error occurred while refunding your transaction. Please contact support.
The credit exceeds the amount of the original transaction.
authorization_expired
An error occurred while processing your transaction. Please contact update your billing information.
The purchase authorization expired and can no longer be used to collect payment. Please attempt another transaction.
authorization_already_captured
An error occurred while processing your transaction. Please contact support.
The purchase amount was already captured. This authorization cannot be used again.
authorization_amount_depleted
An error occurred while processing your transaction. Please contact support.
The amount of purchases exceeds the original authorized amount. You cannot collect more money using this authorization.
recurly_error
An error occurred while processing your transaction. Please contact support.
An error occurred while processing the transaction. Please contact Recurly support.
unknown
The transaction was declined or failed for an unknown reason. Please try again or contact support.
The transaction was declined or failed for an unknown reason. Please try again or contact support.
api_error
An error occurred while processing your transaction. Please contact support.
The payment gateway returned an error code that usually indicates its API specs have changed. Please contact Recurly support.
duplicate_transaction
A similar transaction was recently submitted. Please wait a few minutes and try again.
A transaction was recently submitted with the same Invoice Number, or the same card number and amount. The payment gateway refused to process this transaction in order to prevent a duplicate transaction.
recurly_failed_to_get_token
An error occurred while initializing the transaction. Please try again.
An error occurred while initializing the transaction. Please try again.
recurly_token_not_found
An error occurred while processing your transaction. Please contact support.
An error occurred while processing the transaction. Please contact Recurly support.

Transaction Error XML

Below is an example XML response for the fraud_security_code error:

Status: 422 Unprocessable Entity
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <transaction_error>
    <error_code>fraud_security_code</error_code>
    <error_category>fraud</error_category>
    <merchant_message>The payment gateway declined the transaction because the security code (CVV) did not match.</merchant_message>
    <customer_message>The security code you entered does not match. Please update the CVV and try again.</customer_message>
  </transaction_error>
  <error field="transaction.account.billing_info.verification_value" symbol="declined_bad">did not match</error>
  <transaction href="https://your-subdomain.recurly.com/v2/transactions/3d1c6aa86e3d447eb0f3b4a6e3e074d9" type="credit_card">
    <uuid>3d1c6aa86e3d447eb0f3b4a6e3e074d9</uuid>
    <action>purchase</action>
    <amount_in_cents type="integer">4900</amount_in_cents>
    <tax_in_cents type="integer">0</tax_in_cents>
    <currency>USD</currency>
    <status>declined</status>
    <reference nil="nil"></reference>
    <test type="boolean">true</test>
    <voidable type="boolean">false</voidable>
    <refundable type="boolean">false</refundable>
    <transaction_error>
      <error_code>fraud_security_code</error_code>
      <error_category>fraud</error_category>
      <merchant_message>The payment gateway declined the transaction because the security code (CVV) did not match.</merchant_message>
      <customer_message>The security code you entered does not match. Please update the CVV and try again.</customer_message>
    </transaction_error>
    <cvv_result code="N">No Match</cvv_result>
    <avs_result code="D">Street address and postal code match.</avs_result>
    <avs_result_street>Y</avs_result_street>
    <avs_result_postal>Y</avs_result_postal>
    <created_at type="datetime">2011-10-17T17:24:53-07:00</created_at>
    <details>
      <account>
        <account_code>1</account_code>
        <first_name nil="nil"></first_name>
        <last_name nil="nil"></last_name>
        <company nil="nil"></company>
        <email>verena@example.com</email>
        <billing_info type="credit_card">
          <first_name nil="nil"></first_name>
          <last_name nil="nil"></last_name>
          <address1 nil="nil"></address1>
          <address2 nil="nil"></address2>
          <city nil="nil"></city>
          <state nil="nil"></state>
          <zip nil="nil"></zip>
          <country nil="nil"></country>
          <phone nil="nil"></phone>
          <vat_number nil="nil"></vat_number>
          <card_type>Visa</card_type>
          <year type="integer">2015</year>
          <month type="integer">11</month>
          <first_six>400000</first_six>
          <last_four>0101</last_four>
        </billing_info>
      </account>
    </details>
  </transaction>
</errors>