Troubleshooting

Back

Troubleshooting

This section helps you quickly diagnose and fix the most common issues when integrating with the Payblr systems.

If you cannot find the solution here, please check the Error Codes section or contact our support team with your request_id or event_id.

1. Authentication & Token Issues

If authentication fails, verify the following:

  • The Client ID and Client Secret are correct.

  • You are calling the correct token endpoint for your environment.

  • The request uses the grant_type=client_credentials.

  • The access token is included correctly as a Bearer token in the Authorization header.

  • The token has not expired.

Common issues include:

  • Invalid credentials

  • Expired or missing token

  • Incorrect token endpoint

  • Wrong or missing Authorization header

Solutions:

  • Generate a new access token using the Client Credentials flow (see Get Started).

  • Store the expires_in value and refresh the token before it expires.

2. API Request Issues

  • 400 Bad Request. Cause: Invalid parameters or malformed JSON. Solution: Validate your request body and ensure all required fields are correct.

  • 429 Too Many Requests. Cause: Rate limit reached. Solution: Reduce request frequency and implement backoff retries.

  • Request timeout. Solution: Increase your timeout (recommended: at least 30 seconds) and use Idempotency for safe retries.

  • Unexpected responses or missing fields. Solution: Double-check you are using the correct Base URL and environment.

3. Webhook Issues

  • Webhooks are not arriving. Solution: Ensure your webhook URL is publicly accessible over HTTPS.

  • Payblr keeps retrying the same event. Solution: Always return HTTP 200 OK quickly. Acknowledge first, then process the event.

  • Duplicate events received. Solution: Make your webhook handler idempotent by checking the event id.

  • Signature verification failing. Solution: Use the correct secret key from the dashboard and validate the Payblr-Signature header.

4. Card & Transaction Issues

  • Card creation or update fails → Check all required fields and card program rules.

  • Authorization is declined → Look at the decline_reason or response_code in the webhook or API response.

  • Tokenization (Apple Pay / Google Pay) problems → Ensure your domain is verified.

  • Test cards not working in environment→ Use only the official test card numbers provided for the specific environment.

5. General Tips

  • Always include an Idempotency on POST and PATCH requests when retrying.

  • Log the request_id from every API response — it helps us support you faster.

  • Test everything thoroughly in current environment first.

  • Use the built-in API console in the Developer Portal to test requests quickly.

Still Need Help?

  • Search and save for your error message or status code.

  • When contacting support, please include:

    • Your request_id or event_id

    • Timestamp of the issue

    • Error message or status code

    • Environment

    • Relevant request or payload (remove sensitive data)

We usually respond to technical questions within 24 business hours.