Go-live checklist

Use this checklist when your integration uses the PayMongo API directly, or when it relies on webhooks for async status updates. It covers API key security, idempotency, and webhook setup.

Who this checklist is for

Developers integrating PayMongo through the API. The items in Authentication apply if you make any API calls. The items in Webhooks apply if you need async status updates for payments, refunds, payouts, or disputes. Most production integrations need both.

ℹ️

Before you start: You need live API keys from Settings → Developers in the Dashboard. Complete the Get Started go-live checklist first.

Authentication

API authentication uses two keys: a public key for client-side operations and a secret key for server-side operations.

Required for launch

• Confirm you understand the public versus secret key roles

  The public key (pk_) is safe to expose. Use it client-side to create Payment Methods. The secret key (sk_) has full account access. Use it server-side only, and treat it like a password. See Developer Tools security best practices.

• Confirm secret keys are stored in environment variables or a secrets manager

  Never hardcode secret keys in source. Load them from environment variables or a secrets manager. Keep them out of version control.

• Confirm separate keys are used for live and test environments

  Never use a live key in development or testing. PayMongo issues distinct key pairs per environment for a reason.

• Confirm key access is restricted to the minimum team

  Only people who need live secret keys should have them. Audit access regularly. Rotate keys after any team change.

• Confirm Idempotency-Key is used on POST requests that create or modify data

  Generate a unique key per logical operation (UUIDv4, or a deterministic hash of your internal transaction ID). Same operation, same key. On retry, PayMongo returns the cached original response instead of creating a duplicate.

Best practices

• Confirm your key rotation procedure is documented

  Define how and when keys are rotated. If a key is exposed, rotate it immediately. Do not wait to assess impact first. See API keys.

Webhooks

Webhooks deliver async status updates from PayMongo to your application. They are how you know that a payment succeeded, a refund cleared, a payout was sent, or a dispute was raised.

Required for launch

• Confirm your webhook endpoint URL is ready

  A publicly accessible HTTPS URL that accepts POST and returns 200 immediately. Use a valid TLS certificate from a trusted CA. Self-signed certificates are not accepted. See Creating a webhook endpoint.

• Confirm your webhook is registered

  From the Dashboard: Developer Tools → Webhooks → Add Endpoint. From the API: POST to /v1/webhooks with url and events. Register the endpoint once during setup, not dynamically per resource.

• Confirm your webhook secret is stored securely

  PayMongo displays the endpoint secret when you create the webhook. Store it in your secrets manager. If it is exposed, rotate it immediately.

• Confirm signature verification is implemented

  Read the Paymongo-Signature header. Compute HMAC-SHA256 of the raw request body with your secret. Compare using a timing-safe equality check. Verify the signature before any parsing or processing.

• Confirm the raw request body is preserved before signature verification

  Disable JSON parsing middleware before the verification step. Any byte change before verification breaks signature checks on legitimate requests. See Webhook best practices.

• Confirm you subscribe only to the events you need

  Pick events from the Webhook events list: for example payment.paid, payment.failed, payment_intent.succeeded, refund.succeeded, dispute.created, dispute.resolved, payout.paid, payout.failed. Subscribing to events you do not handle adds noise and load.

• Confirm webhooks are acknowledged within 30 seconds and processed asynchronously

  Return a 200 response immediately. Push the payload to a background worker. Do not run slow database writes, external API calls, or business logic inside the response cycle.

• Confirm duplicate webhook deliveries are handled

  PayMongo retries failed deliveries up to 12 times. Expect occasional duplicates. Store processed event IDs and skip any that arrive again. This is required for any handler that touches financial data.

• Confirm test and live webhook environments are separated

  Use separate webhook endpoints for test and live. Use the livemode field in the event payload as an extra guard, but do not rely on it as your only safeguard.

• Confirm a 2xx response is returned for unrecognized event types

  Acknowledge with a 200 through 209 plus a JSON response, and skip processing. A 4xx or 5xx response triggers PayMongo's retry logic and piles up your retry queue.

Best practices

• Confirm you understand the webhook retry logic

  Review the Webhook retry logic page so your team knows when and how PayMongo retries. Pair this with your dedupe strategy.

• Confirm webhook delivery logs are monitored

  Open Developer Tools → Webhooks in the Dashboard. Review delivery logs for unexpected failures. Decide who owns this monitoring. See Webhooks Dashboard module.

• Confirm the webhook resend flow works

  Trigger a resend from the Dashboard or through the Retry a webhook delivery endpoint. Confirm your handler processes the replayed event correctly, with no duplicate side effects.

Error handling

Best practices

• Confirm your error mapping is documented

  Map PayMongo error codes to your own customer-friendly messages. Do not surface the raw detail field directly. It can contain internals not meant for end users. See Error handling.

Test then go-live

Required for launch

• Confirm your full integration works with test mode events

  Walk through the happy and unhappy paths end to end using test keys and test webhook events. See Developer Tools testing.

Next steps

After your API setup and webhook handlers are validated, return to the product-group checklists for the customer-facing integration work:

• Payment Acceptance go-live checklist: confirm payment events flow correctly
• Money Movement go-live checklist: confirm payout events flow correctly
• Payment Channels go-live checklist: confirm channel-side configuration is complete