Understanding Responses

Overview

When you make API calls to CrissCross (Collect, Exchange, or Payouts), the responses you receive are structured in JSON format. Understanding the structure and the data provided in these responses is crucial for effective integration across all services. This guide will help you interpret these responses, ensuring your application can handle them correctly.

Response Structure

CrissCross 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).

Service-Specific Response Patterns

While the general response structure is consistent, each service may include service-specific fields:

• Collect: Responses include payment status, transaction IDs, and payment method details
• Exchange: Responses include account balances, conversion rates, and trading history
• Payouts: Responses include payout status, recipient details, and disbursement information

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 CrissCross SDKs which often handle response parsing and error management automatically across Collect, Exchange, and Payouts.
• Check Service Documentation: Refer to the specific API reference for each service (Collect, Exchange, Payouts) for detailed response schemas.