Error Handling Best Practices

Overview

When integrating with PayOS, it’s important to implement robust error handling to ensure a seamless payment experience. PayOS offers automatic retries for specific types of failures, provides detailed error codes, and uses webhooks to notify merchants of transaction statuses. This document outlines best practices for managing errors effectively.

Key Error Types

1. Client Errors (4xx):

   • These errors occur due to invalid requests from the merchant (e.g., missing parameters, invalid data).
   • Examples:
     • 400 Bad Request: Incorrect or missing request parameters.
     • 401 Unauthorized: Invalid or missing API key.
     • 404 Not Found: Resource not available (e.g., transaction ID does not exist).

2. Server Errors (5xx):

   • These errors are caused by issues on PayOS’s side.
   • Examples:
     • 500 Internal Server Error: Temporary system failure.
     • 503 Service Unavailable: PayOS service is temporarily down or under maintenance.

3. Payment-Specific Errors:

   • These errors occur during payment processing and could result from card issues, insufficient funds, or expired payment methods.
   • Examples:
     • 402 Payment Declined: Card issuer declined the payment.
     • 409 Duplicate Transaction: A transaction with the same ID has already been processed.

Automatic Retry Mechanism

PayOS employs an automatic retry system for certain transient errors, such as timeouts or temporary PSP unavailability.

• How it Works:

  • If the first payment attempt fails due to a recoverable issue (e.g., PSP downtime), PayOS will retry the payment automatically up to three times within a set period.
  • If the retry is successful, the merchant is notified via webhook.
  • If retries fail, PayOS sends a final failure notification.

• No Merchant Intervention Needed:

  • Merchants do not need to manually trigger retries. PayOS will manage the retry logic internally.

Example Error Response

Here is an example of a typical error response from the PayOS API:

1
{
2
  "error": {
3
    "code": "402",
4
    "message": "Payment declined by card issuer.",
5
    "details": "Insufficient funds or card expired.",
6
    "retryable": false
7
  }
8
}

Handling Errors in Your Integration

1. Monitor Webhook Notifications:

   • Use webhooks to stay informed about payment statuses and errors. Always implement retry logic for webhook failures on your side.

2. Implement Graceful Error Messages:

   • Display user-friendly error messages when a payment fails. Avoid showing raw error codes to end-users.

3. Log All Errors for Debugging:

   • Log errors with detailed context for troubleshooting. Include request IDs, timestamps, and transaction data.

4. Use Exponential Backoff for Retries:

   • When retrying failed API requests, use exponential backoff to avoid overwhelming the system.

Error Codes and Suggested Actions

Webhook-Triggered Error Responses

When a payment attempt fails, PayOS sends a failure notification via webhook. Example webhook payload for a failed payment:

1
{
2
  "event": "payment.failed",
3
  "data": {
4
    "transaction_id": "txn_7890",
5
    "status": "failed",
6
    "reason": "Card expired",
7
    "amount": 5000,
8
    "currency": "USD"
9
  }
10
}

Conclusion

Effective error handling is essential for maintaining a smooth payment experience. By leveraging PayOS’s automatic retries, monitoring webhook notifications, and implementing clear error messages, merchants can minimize disruptions and ensure better customer satisfaction.