What a test card refund is
A test card refund is a refund issued against a payment created with a test card in a payment gateway sandbox. The gateway simulates the refund response, updates the test charge status, and sends test webhooks. No real funds move, and no real cardholder is involved. Use only gateway-issued test numbers in this process, never live card data.
Prerequisites
- Test-mode API keys or sandbox dashboard access.
- At least one completed test charge with a refundable status.
- Permission to create refunds on the account.
- Access to webhook or event logs for the sandbox.
Steps to issue a test card refund
- Open the sandbox dashboard and find the test charge or payment intent you want to refund. Confirm the charge is in test mode and shows a captured or settled status. Authorized-only charges often cannot be refunded until captured.
- Copy the charge ID or payment ID. You will use this identifier in the refund request. Check that the ID belongs to the same sandbox account and currency as the original charge.
- Go to the refunds section of the dashboard, or open the refund endpoint in the API reference for your gateway. Select full refund for the total amount.
- Enter the refund amount. For a partial refund, use an amount lower than the captured total. Match the currency of the original charge.
- Add an idempotency key if the gateway supports one. Reuse the same key only when retrying the same refund request. A new key prevents duplicate refunds when you test repeated submissions.
- Submit the refund. Read the response status and the refund object. A test refund returns a simulated status such as succeeded, pending, or failed depending on the test card number and gateway rules.
- Check the charge status in the dashboard. The refunded amount and remaining refundable balance should update. For partial refunds, confirm the balance equals the original amount minus the refunded amount.
- Open the event or webhook log. Find the refund event and confirm the payload contains the refund ID, amount, currency, and status. Replay the event if you are testing webhook handling.
- Repeat the test with a partial refund, a second partial refund, and a refund that exceeds the remaining balance. Record the error codes for each case.
- Reset or archive the test data when the test run ends. Keep a short note of the charge ID, refund ID, amount, and result.
Why a test refund can fail
- The original charge was never captured.
- The refund amount exceeds the captured total.
- The charge and refund use different currencies.
- The idempotency key was reused with a different amount.
- The test card number maps to a simulated decline in that gateway.
Test mode versus live mode
Test refunds settle on the gateway schedule, often at once. Live refunds depend on the card network and issuer, and can take several business days. Test refunds do not create fee reversals or settlement entries. Live refunds do. Test webhooks carry test flags; live webhooks do not. Keep test and live keys separate so a test request never reaches a live charge.
Records to keep
Log the charge ID, refund ID, amount, currency, status, timestamp, and the test card number used. Store the gateway response body for failures. These records make later test runs repeatable and help you compare gateway behavior when you change providers.