Skip to main content

​
Insufficient Funds

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

​
What it means

The cardholder’s account does not have enough available balance or credit to cover the payment amount. The card issuer rejected the transaction because the requested amount exceeds what the card can currently spend.

​
Why it happens

  • The cardholder’s checking/savings account balance is too low (debit cards).
  • The cardholder has reached their credit limit (credit cards).
  • A pending hold from a previous transaction is reducing the available balance.
  • The cardholder has daily or per-transaction spending limits set by 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": "insufficient_funds",
  "decline_message": "The card has insufficient funds to complete the purchase."
}

​
What to tell the customer

Your payment could not be completed because your card has insufficient funds. Please try a different payment method, or contact your bank to check your available balance.
Keep the message helpful but not overly specific — the customer likely already knows their balance situation.

​
What the merchant should do

  1. Show a clear, friendly error message — do not expose raw API error details.
  2. Let the customer try again with a different card or payment method.
  3. Do not retry automatically — insufficient funds is unlikely to resolve on its own within seconds.
  4. Consider offering alternative payment methods if available (bank transfer, other cards).
  5. Do not store or flag the customer as fraudulent — this is a normal, non-suspicious decline.

​
Testing

Use this test card number to simulate an insufficient_funds decline: 
4000000000009995
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": "4000000000009995",
      "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"
    }
  }'