MockCard
All posts
All posts
declinestest-cardsci-cdsoft-declinespayment-failureinsufficient-funds-test-cardcard-decline-testingsoft-decline

Insufficient Funds Test Card: Master Soft Decline Testing

Share
September 5, 20262 min read

The problem

When a payment fails because a customer’s account is short of money, the error is often a soft decline—the card is still valid, but the issuer temporarily refuses the transaction. Developers rely on an insufficient funds test card to reproduce this scenario, but most sandbox environments either ignore the nuance or return a generic failure that masks the real retry logic needed in production. The result is a gap in testing: your retry scheduler may never be exercised, and you’ll discover the issue only after a customer’s subscription is lost.

How gateway sandboxes miss it

Typical gateway sandboxes provide a handful of “failure” cards, but they rarely expose the full spectrum of soft-decline codes (e.g., 51 for insufficient funds, 05 for do-not-honor). They also don’t simulate the timing of retries, issuer velocity limits, or the possibility of a race condition when multiple webhook deliveries collide. Consequently, developers end up writing ad-hoc logic that works with the sandbox but breaks when the real issuer imposes a 2-day retry window or throttles requests.

How MockCard helps with insufficient funds test card

MockCard gives you deterministic decline scenarios for every supported brand—visa, mastercard, rupay, and amex—so you can trigger an insufficient_funds or do_not_honor event and observe the exact webhook payload. The API returns a Stripe-shaped payment_intent event (succeeded or payment_failed) with an HMAC-SHA256 signature in the X-MockCard-Signature header, letting you validate your webhook handler end-to-end.

You can also enable chaos modes such as simulate_race, limbo, latency, and 3ds_abandoned (Pro only) to test how your system behaves under race conditions or delayed deliveries. For example, simulate_race will send duplicate webhook events to mimic a real-world race, while latency will delay the callback to test your timeout handling.

Explore the playground. For detailed usage, check the docs.

Code example

Use this cURL request to generate a Visa card with the insufficient_funds scenario and post a signed webhook to your endpoint:

curl -X POST https://www.mockcard.io/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"brand":"visa","scenario":"insufficient_funds","webhook_url":"https://example.com/webhooks"}'

Swap brand for mastercard, rupay, or amex as needed. Replace the webhook URL with your handler.

Takeaways

  • Soft declines like insufficient_funds need deterministic fixtures — generic sandbox failures hide retry bugs.
  • Call POST /api/v1/generate with an explicit scenario and verify HMAC signatures on the webhook.
  • Use Pro chaos modes (simulate_race, latency, limbo) when you need duplicate or delayed delivery coverage.
  • Try the playground or read the API docs.

Research notes consulted for industry context: Failed-Payment Recovery: The 2026 Dunning Playbook · Why Subscription Payments Fail: 4 Causes & Fixes (2026) · Soft vs Hard Declines: What They Mean for Recovery · Understanding Your Credit Card Decline Codes.

Comments