Skip to main content

​
Generic Decline

Decline code: generic_decline Error type: card_error HTTP status: 201 Created (payment status becomes failed asynchronously)

​
What it means

The card issuer declined the transaction without providing a specific reason code. This is the most general decline and serves as a fallback when the issuer’s response does not map to a more specific decline code.

​
Why it happens

A generic decline can occur for many reasons, including:
  • The issuer’s fraud prevention system flagged the transaction.
  • The cardholder has set spending controls that block this transaction.
  • The card has restrictions on the type or amount of transactions allowed.
  • There is a temporary issue with the issuer’s authorization system.
  • The issuer declined for an internal reason that does not have a standard code.
Because this is a catch-all, the exact cause can only be determined by the cardholder contacting their bank.

​
API response

The payment is created with status: "pending". After processing, it transitions to failed with decline details: 
{
  "id": "pay_abc123",
  "status": "failed",
  "decline_code": "generic_decline",
  "decline_message": "The card was declined for an unknown reason."
}

​
What to tell the customer

Your card was declined. Please try a different payment method, or contact your card issuer for more details.
Keep the message neutral and helpful. Avoid language that implies the customer did something wrong.

​
What the merchant should do

  1. Show a generic, polite decline message — do not try to guess the specific reason.
  2. Let the customer try again — a single retry with the same card sometimes succeeds, especially if the decline was triggered by a one-time fraud check.
  3. Offer alternative payment methods — suggest trying a different card.
  4. Direct the customer to their bank — only the issuer knows the real reason.
  5. Do not block or flag the customer — generic declines are not an indicator of fraud on the customer’s part.
  6. Log the request_id from the error response for debugging and support purposes.

​
Reducing generic declines

While you cannot eliminate generic declines entirely, you can reduce them by:
  • Providing customer information — include customer.email and customer.name in payment requests. More data helps issuers make better authorization decisions.
  • Using clear descriptions — a meaningful description field can help with issuer fraud scoring.
  • Avoiding unusual patterns — sudden spikes in transaction volume or amount from a single card can trigger fraud flags.

​
Testing

Use this test card number to simulate a generic_decline: 
4000000000000002
Any future expiration date and any CVC will work. 
curl -X POST https://api.flowlix.dev/v1/payments \
  -H "Authorization: Bearer fl_test_sk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "eur",
    "card": {
      "number": "4000000000000002",
      "exp_month": 12,
      "exp_year": 2027,
      "cvc": "123",
      "holder_name": "Test User"
    },
    "customer": {
      "email": "test@example.com",
      "first_name": "Test",
      "last_name": "User",
      "country": "DE",
      "phone": "+491234567890",
      "address": "100 Main St",
      "city": "Berlin",
      "zip": "10115"
    }
  }'