Payment Gateway Troubleshooting

Payment Gateway Troubleshooting

Payment issues directly impact your revenue. This guide covers the most common payment problems across Stripe, PayPal, and cryptocurrency gateways with specific solutions for each.

Stripe Issues

Problem: Card Declined

Common decline codes and what they mean:

Decline Code	Meaning	Customer Action
insufficient_funds	Not enough money on card	Use a different card or add funds
card_declined	Generic decline by issuing bank	Contact their bank
expired_card	Card has expired	Use a valid card
incorrect_cvc	Wrong security code entered	Re-enter the correct CVC
processing_error	Temporary issue at Stripe/bank	Try again in a few minutes
fraudulent	Stripe's fraud detection triggered	Use a different payment method

Vendor actions:

• Check the Stripe Dashboard under Payments for the specific decline reason.
• If you see many fraudulent declines from legitimate customers, review your Stripe Radar rules.
• Consider enabling 3D Secure to reduce fraud declines.

Problem: Webhooks Not Arriving

Symptoms: Payments succeed in Stripe but IPTVbp does not create subscriptions.

Diagnostic steps:

1. Go to Stripe Dashboard > Developers > Webhooks.
2. Click your endpoint.
3. Check Recent Deliveries for failed attempts (red status).
4. Common errors:
   • 404: The webhook URL is wrong. Verify it matches your domain.
   • 401/403: Webhook signature verification failed. Check the signing secret.
   • 500: IPTVbp encountered an error processing the event. Check IPTVbp error logs.
   • Timeout: IPTVbp took too long to respond. Check server performance.

Solutions:

• Verify the webhook URL: https://yourdomain.com/api/webhooks/stripe
• Verify the signing secret matches in both Stripe and IPTVbp.
• Click Resend on failed webhook events in Stripe to retry.
• If the IPTVbp server was temporarily down, Stripe will automatically retry for up to 3 days.

Problem: Test Mode Payments in Live Mode (or Vice Versa)

Symptom: Payments appear in the Stripe Dashboard but under the wrong mode.

Solution: Ensure you are using the correct API keys. Test keys start with pk_test_/sk_test_, live keys start with pk_live_/sk_live_. Update in IPTVbp at Settings > Payment Gateways > Stripe.

PayPal Issues

Problem: Payment Stuck as "Pending"

Causes:

• eCheck: Customer paid via bank transfer (takes 3-5 business days).
• Payment review: PayPal is reviewing the transaction for fraud.
• Unconfirmed email: The customer's PayPal email is not verified.

Solutions:

• For eCheck: Wait for the payment to clear. IPTVbp will process it when the IPN/webhook confirms completion.
• For review: Contact PayPal support to expedite.
• For the customer: Ask them to use a funded PayPal balance or linked card instead.

Problem: IPN/Webhook Not Received

Diagnostic steps:

1. In PayPal, check IPN history under Account Settings > Notifications > IPN.
2. Look for failed deliveries.
3. Verify the IPN/webhook URL is correct.
4. Check that your server responds with HTTP 200 to PayPal's requests.

Solutions:

• Update the webhook URL if incorrect.
• Ensure your server is not blocking PayPal's IP addresses.
• Resend the IPN notification from PayPal's history page.

Problem: Currency Mismatch

Symptom: PayPal rejects the payment or shows a different amount.

Solution: Ensure your PayPal account can receive payments in EUR (or whatever currency your store uses). In PayPal, go to Settings > Money, banks and cards > Currency management and add EUR.

Cryptocurrency Issues

Problem: Payment Not Confirmed

Symptom: Customer says they sent payment but IPTVbp shows "Waiting for payment".

Diagnostic steps:

1. Check the payment status in your NOWPayments or BTCPay dashboard.
2. Get the transaction hash from the customer.
3. Look up the transaction on a blockchain explorer:
   • BTC: blockchain.com/explorer
   • ETH/USDT: etherscan.io

Common causes:

• Underpayment: Customer sent less than the required amount (forgot to account for network fees).
• Unconfirmed: Transaction is in the mempool but has not been mined yet. Wait for confirmations.
• Wrong address: Customer sent to the wrong wallet address.
• Expired invoice: The payment window (typically 20-30 minutes) expired before the transaction confirmed.

Solutions:

• If the payment is confirmed on the blockchain but not in NOWPayments, contact their support with the transaction hash.
• For underpayments, NOWPayments may require the customer to send the difference or you can manually adjust.
• For expired invoices, create a new payment request and ask the customer to pay again (refund the first payment if it eventually arrives).

Problem: Payment Confirmed But Subscription Not Created

Cause: The IPN callback from NOWPayments or BTCPay failed.

Solutions:

• Check the IPN/webhook delivery logs in NOWPayments/BTCPay.
• Verify the IPN secret matches.
• Check IPTVbp error logs for processing failures.
• Manually activate the subscription in IPTVbp and note the payment reference.

General Troubleshooting

Payment Succeeds But Invoice Shows "Unpaid"

This typically means the webhook arrived but IPTVbp could not match it to the correct invoice. Check:

• The order/invoice ID is passed correctly in the payment metadata.
• No duplicate webhook events are causing conflicts.
• The IPTVbp logs for any matching errors.

Refund Not Appearing for Customer

• Stripe refunds take 5-10 business days to appear on the customer's statement.
• PayPal refunds are typically instant to PayPal balance but may take longer to reach the original funding source.
• Crypto refunds must be processed manually to the customer's wallet address.

When to Contact Support

Contact IPTVbp support if:

• Webhook events are consistently failing despite correct configuration.
• Payments are being processed but subscriptions are never created.
• You see errors in the logs that you cannot resolve.

Provide: the payment gateway, the specific error message, the transaction/invoice ID, and any relevant log entries.