Support
Troubleshooting
This section helps you quickly diagnose and fix the most common issues when integrating with Payblr systems.
If you cannot find the solution here, review the relevant error code details and contact the Payblr support team with your request_id or event_id.
Overview
Start by identifying whether the issue is related to authentication, the API request, webhook delivery, card configuration, transaction behavior, or the testing environment. Capture identifiers early so the issue can be traced faster.
Authentication & token issues
Use this section when a token request fails or an API request is rejected because of missing, expired, or invalid authentication.
API request issues
Use this section when Payblr returns a 400, 429, timeout, unexpected response, or missing field behavior.
Webhook issues
Use this section when webhook notifications are not arriving, duplicate events are received, or signature validation fails.
Card & transaction issues
Use this section when card creation, card updates, authorizations, tokenization, or test cards are not behaving as expected.
Quick checklist
Before opening a support request, confirm the following items.
- Confirm the Client ID and Client Secret are correct.
- Confirm you are calling the correct token endpoint for the selected environment.
- Confirm the token request uses grant_type=client_credentials.
- Confirm the access token is included as a Bearer token in the Authorization header.
- Confirm the token has not expired.
- Confirm the Base URL matches the environment you are testing.
- Capture the request_id or event_id before contacting support.
1. Authentication & token issues
If authentication fails, verify the token request, client credentials, token endpoint, grant type, Authorization header, and token expiry.
Verify
- The Client ID and Client Secret are correct.
- You are calling the correct token endpoint for your environment.
- The request uses 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
- 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.
- Store the expires_in value and refresh the token before it expires.
2. API request issues
API request issues are commonly caused by malformed JSON, invalid parameters, rate limits, request timeouts, or using the wrong Base URL or environment.
| Issue | Cause | Solution |
|---|---|---|
| 400 Bad Request | Invalid parameters or malformed JSON. | Validate your request body and ensure all required fields are correct. |
| 429 Too Many Requests | Rate limit reached. | Reduce request frequency and implement backoff retries. |
| Request timeout | The request did not complete within the expected time window. | Increase your timeout to at least 30 seconds and use idempotency for safe retries. |
| Unexpected responses or missing fields | The request may be using the wrong Base URL, environment, or endpoint version. | Double-check you are using the correct Base URL and environment. |
Use idempotency for safe retries on POST and PATCH requests, especially when retrying after a timeout or network failure.
3. Webhook issues
Webhook issues are usually related to endpoint availability, acknowledgement behavior, duplicate delivery handling, or signature verification.
| Issue | Solution |
|---|---|
| Webhooks are not arriving | Ensure your webhook URL is publicly accessible over HTTPS. |
| Payblr keeps retrying the same event | Always return HTTP 200 OK quickly. Acknowledge first, then process the event. |
| Duplicate events received | Make your webhook handler idempotent by checking the event id before processing. |
| Signature verification failing | Use the correct secret key from the dashboard and validate the Payblr-Signature header. |
Acknowledge first
Return HTTP 200 OK quickly, then process the event asynchronously. This helps prevent unnecessary retries.
Process idempotently
Check the event id before processing so duplicate webhook deliveries do not create duplicate actions.
4. Card & transaction issues
Card and transaction issues may be caused by required field validation, card program rules, authorization decline reasons, tokenization setup, or using incorrect test card data.
| Issue | Solution |
|---|---|
| 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 problems | For Apple Pay or Google Pay issues, 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
Use these practices across all Payblr API integrations to make testing, debugging, and support escalation easier.
- Always include an Idempotency value on POST and PATCH requests when retrying.
- Log the request_id from every API response so Payblr can support you faster.
- Test everything thoroughly in the current environment first.
- Use the built-in API console in the Developer Portal to test requests quickly.
Still need help?
Search for the error message or status code first. When contacting Payblr support, include enough information for the issue to be traced quickly.
Before contacting support
Search for the exact error message or status code and confirm the issue is reproducible in the current environment.
Response time
Payblr usually responds to technical questions within 24 business hours.
Include these details
- Your request_id or event_id.
- Timestamp of the issue.
- Error message or status code.
- Environment.
- Relevant request or payload with sensitive data removed.
Next steps
After reviewing troubleshooting guidance, continue with API availability and testing considerations to prepare for resilient integration testing.