Webhook Concerns

Why am I not receiving webhook events?

Webhook events might not be delivered to your server due to your endpoint's response, a disabled webhook, or network issues. PayMongo requires your endpoint to confirm it has received the event with a specific response code.

Solution:

Verify Endpoint Response: Your webhook endpoint must respond with an HTTP 2xx status code (e.g., 200 OK) as soon as it receives an event. If it doesn't, PayMongo will retry sending the event up to twelve times.
Check if Webhook is Disabled: A webhook ID will be disabled if it continuously returns 4xx or 5xx status codes. You will need to re-enable it manually via the API.
Implement a Rollback Mechanism: PayMongo does not re-trigger missed webhook events. It is crucial to have a system that can retrieve a transaction's status by its ID if your server experiences downtime.

How do I properly test and secure my webhooks?

To ensure your webhooks work and are secure, you need to set them up correctly for your test and live environments and protect your endpoints from unauthorized requests.

Solution:

Use Separate Webhooks for Test and Live Modes: You must create one webhook using your test mode API key for testing and a separate one using your live mode API key for production.
Use HTTPS and a Valid SSL Certificate: Your webhook URLs must be served over HTTPS and have a valid, publicly trusted SSL certificate. Webhook delivery will fail if this is not the case.
Verify the Paymongo-Signature Header: To protect your endpoints from unauthorized requests, you should verify the Paymongo-Signature HTTP header in each request. This confirms that the webhook truly originated from PayMongo.

API Keys & Integration Errors

What is the difference between my Public and Secret keys?

PayMongo uses two types of API keys for different purposes and security levels.

Public Keys (pk_live_... or pk_test_...):

Purpose: Used on the client-side (e.g., your website's front end) to identify your account.
Access: Has restricted data access.

Secret Keys (sk_live_... or sk_test_...):

Purpose: Must be kept confidential and stored only on your secure server. Used to perform any API request without restriction.
Access: Has full access to your account's data. Never share your secret keys.

My API requests are failing. What are the most common API key errors?

The most common API key errors result in a 401 Unauthorized HTTP status code, indicating an issue with how your API key is being passed or its validity.

Solution:

api_key_required: You did not pass the API key. Ensure it is included in your request.
authentication_invalid: Your request did not implement HTTP Basic Authentication correctly.
api_key_not_found: The API key you provided does not exist. Double-check for typos.
secret_key_required: The specific API resource you are trying to access requires a secret key, but you used a public key.
account_not_activated: Your account must be fully activated to access the requested resource.

My payments are not going through in production, even with the correct keys.

This is a common issue that often results from a mix-up between Test and Live Mode.

Solution:

Use Live Keys for Live Payments: Ensure you are using your live API keys (pk_live_... and sk_live_...) for production.
Check Account Activation: Full API access, including live keys, is only available to fully verified M2 accounts.
Check PayMongo Links/Resources: Remember that links and other resources created in test mode will not process live payments, even if your account is activated.

What happens if I regenerate my API keys?

As a security measure, you can regenerate your API keys from your dashboard. This action will create a new set of keys and invalidate the old ones.

NOTE: Update All Integrations. If you regenerate your API keys, you must update them in any existing website or application that uses the old keys to continue accepting payments.