Understanding Responses

Overview

When you make API calls to PayOS, the responses you receive are structured in JSON format. Understanding the structure and the data provided in these responses is crucial for effective integration. This guide will help you interpret these responses, ensuring your application can handle them correctly.

Response Structure

PayOS API responses generally follow a consistent format. Here is a breakdown of a typical response structure:

Success Response

A successful response typically contains a status field indicating success, and a data field containing the information requested:

1
{
2
  "status": "success",
3
  "data": {
4
    "merchant_id": "merchant_123456",
5
    "name": "Bookstore Ltd.",
6
    "industry": "Retail"
7
  }
8
}

Error Response

In case of an error, the response will include a status field indicating error, an error field providing a brief description, and often an error_code for more specific handling:

1
{
2
  "status": "error",
3
  "error": "Invalid API Key",
4
  "error_code": "401"
5
}

Interpreting Common Fields

• status: Indicates whether the call was successful (success) or resulted in an error (error).
• data: Contains the actual data requested, which varies depending on the API endpoint called.
• error: Provides a description of the error encountered during the API call.
• error_code: Offers a specific code that can be used for programmatic error handling.

Handling Errors

Understanding and properly handling errors is key to building a robust integration:

1. Check Status: Always check the status field in responses to quickly determine if further error handling is needed.
2. Log Errors: Keep logs of error responses for debugging and support purposes.
3. Retry Logic: Implement retry mechanisms for errors that may be resolved with subsequent attempts (e.g., network issues).

Tips for Success

• Validate Responses: Always validate the format and data of the responses to ensure they meet your application’s expectations.
• Use SDKs: If available, use PayOS SDKs which often handle response parsing and error management automatically.