Testing & Debugging

Test mode vs Live mode

Every PaymentHooks account operates in two isolated environments. Test mode lets you exercise the full API without moving real funds. Live mode processes actual charges through your configured payment gateways.

Objects created in test mode are never visible in live mode and vice versa. Payment IDs, customer records, webhooks, and logs are fully segregated.

Test card numbers

Use these card numbers when submitting payments in test mode. Combine them with any valid future expiry date and the appropriate CVC length.

Test webhook events

You can trigger synthetic webhook events directly from the dashboard without creating a real payment object:

1. 1Navigate to Developers → Webhooks in your merchant dashboard.
2. 2Select the endpoint you want to target.
3. 3Click Send test event and choose an event type from the dropdown.
4. 4Inspect the delivery log to confirm receipt and view the response your server returned.

Every webhook delivery follows this envelope structure:

{
"id": "evt_01HXYZ123456",
"type": "payment.succeeded",
"created": 1716820000,
"livemode": false,
"api_version": "2024-01",
"data": {
"object": {
"id": "pay_01HXYZ789",
"amount": 4999,
"currency": "usd",
"status": "succeeded"
}
}
}

Simulating errors

To trigger a specific decline code without depending on a particular card number, create a payment with an amount whose last two digits match one of the codes below. This works with any test card number that would otherwise succeed.

Debugging checklist

If your integration is not behaving as expected, work through the following common causes before opening a support ticket.

• API key not set / wrong mode

  Verify PAYMENTHOOKS_SECRET_KEY is set in your environment and uses the sk_test_ prefix in test mode.

• Missing required parameters

  Check the error response for the param field. Common omissions: currency, amount, or payment_method.

• Webhook signature verification failures

  Ensure you are passing the raw request body (before JSON parsing) to verifyWebhookSignature, and that the correct WEBHOOK_SECRET is in use.

• Currency mismatch

  Currency codes must be lowercase ISO 4217 strings (e.g. usd, eur, gbp). Uppercase values are rejected.

• Idempotency key conflicts

  A reused Idempotency-Key with different parameters returns a 409 Conflict. Generate a fresh key per unique request.

Error response format

All API errors return a consistent JSON envelope alongside the appropriate HTTP status code (4xx or 5xx). The structure is:

{
"error": {
"type": "card_error",
"code": "card_declined",
"decline_code": "insufficient_funds",
"message": "Your card has insufficient funds.",
"param": "payment_method",
"request_id": "req_01HXYZ999",
"doc_url": "https://paymenthooks.com/docs/errors#card_declined"
}
}