Troubleshooting

Common Issues

Troubleshooting common problems with PayOS integrations

Overview

While PayOS aims to provide a seamless payment orchestration experience, some issues may arise due to integration challenges, configuration errors, or external dependencies. This guide highlights common issues merchants encounter and how to resolve them.

Common Issues and Solutions

  1. Invalid API Key (401 Unauthorized)

    • Issue: Requests fail with a 401 error.
    • Cause: Incorrect or expired API key used in the request.
    • Solution: Verify the API key and ensure it is correctly included in the Authorization header. Generate a new key if needed.

  2. Payment Declined by Issuer (402 Payment Declined)

    • Issue: Payment requests are declined by the customer’s bank.
    • Cause: Insufficient funds, incorrect payment details, or card restrictions.
    • Solution: Suggest the customer try a different payment method or contact their bank for details.

  3. Incorrect Webhook Configuration

    • Issue: Webhook notifications are not being received.
    • Cause: Incorrect endpoint configuration or blocked traffic.
    • Solution: Ensure the webhook endpoint is correctly configured and accessible. Verify any firewall rules that may block incoming requests.

  4. Mismatched Currency Code in Transactions

    • Issue: Payments are rejected due to unsupported currency codes.
    • Cause: Currency code mismatch between the merchant and the payment processor.
    • Solution: Ensure the currency code is supported by both PayOS and the payment processor. Use the currency compatibility matrix in the dashboard.

  5. Duplicate Transactions Due to Retries

    • Issue: Multiple payments are processed for a single order.
    • Cause: Manual retries by merchants during automatic PayOS retries.
    • Solution: Monitor PayOS’s retry logic and avoid triggering manual retries when automatic retries are active.

  6. Timeouts During Payment Processing

    • Issue: Payments fail with a timeout error.
    • Cause: Network issues or a slow response from the payment processor.
    • Solution: Implement retries with exponential backoff or use PayOS’s automatic retry feature.

  7. Missing Payment Methods in Checkout

    • Issue: Some expected payment methods are not shown in the hosted checkout.
    • Cause: Payment methods may not be enabled for the merchant’s account.
    • Solution: Verify the payment method configurations in the dashboard and ensure all relevant methods are enabled.

Best Practices for Issue Resolution

  • Monitor Logs and Metrics: Regularly monitor your integration logs and PayOS metrics to identify issues early.
  • Use Webhooks for Real-Time Alerts: Configure webhooks to stay informed about payment statuses and issues.
  • Keep Your API Keys and Webhooks Secure: Rotate API keys periodically and secure webhook endpoints to prevent unauthorized access.