Troubleshooting

For a complete list of error codes, see the API Reference.

Failed payments

Payment Intent stuck at awaiting_payment_method

After attaching a Payment Method, the status returns to awaiting_payment_method instead of moving forward.

Read last_payment_error.failed_message on the Payment Intent for the specific reason. Common causes:

• Validation error on the Payment Method — the details provided were invalid or incomplete
• Incorrect Payment Method type — verify that the type matches a method in payment_method_allowed
• Expired Payment Intent — Payment Intents expire after a set period; create a new one
• Incorrect client_key — the client_key must come from the same Payment Intent you're attaching to

Correct the issue and retry with a new Payment Method.

Card declined

A card payment fails with an error in last_payment_error.

3D Secure authentication failed

The customer was redirected to 3DS, failed or cancelled authentication, and the payment didn't complete.

The customer may have cancelled, entered the wrong OTP, or their bank rejected the authentication. When the customer returns to your return_url, retrieve the Payment Intent server-side. If the status is awaiting_payment_method, show an error and let them retry. Don't retry the attachment automatically — create a new Payment Method.

E-wallet redirect not working

The customer is not being redirected to the e-wallet app, or the redirect URL doesn't open correctly.

1. Confirm the return_url is a valid, reachable HTTPS URL
2. Confirm you're redirecting to next_action.redirect.url — not your own URL
3. For mobile apps, implement deep link handling for GCash (see Integrating GCash on mobile applications)

Webhook issues

Webhooks not being received

Payments succeed but your server isn't receiving webhook events.

1. Verify webhook endpoints are registered in the Webhooks section of your PayMongo dashboard
2. Check that test webhooks use test API keys and live webhooks use live API keys — test webhooks only fire for test mode payments
3. Check your server logs for incoming requests and any processing errors
4. Ensure your endpoint returns 200 OK quickly — process webhooks asynchronously if the handler takes time

Redirect and return URL issues

Payment status unclear after customer returns

The customer lands on your return page but you don't know if the payment succeeded.

Never trust the redirect alone. When the customer returns:

1. Extract the payment_intent_id from the query parameters
2. Retrieve the Payment Intent from your server using the secret key
3. Check status — succeeded means paid; awaiting_payment_method means something went wrong

QR Ph issues

QR code not displaying

The QR code is not visible after the attach response.

The value at next_action.code.image_url is a Base64 data URI. Set it directly as the src of an <img> tag:

<img src="data:image/png;base64,..." alt="Scan to pay" />

If the value already includes the data:image/...;base64, prefix, use it as-is.

QR code expired before customer scanned

You received a qrph.expired webhook and the customer didn't pay in time.

Notify the customer and generate a new QR code by creating a new Payment Method and attaching it to the same Payment Intent.