Error Handling

The APM API uses standard HTTP status codes to indicate whether a request was successful or encountered an error.

Common API Response Codes

✅ 200 OK

The request was successfully processed.

Examples:

A payment request was successfully initiated and accepted for processing.
An info query (/info/{id}) successfully returned transaction details.

Note: For GET requests, a 200 OK response code is returned upon success.

✅ 201 Created

A new resource (such as a payment transaction) was successfully created.

Examples:

A new APM payment request was successfully created using the /api/v1/payments/apm endpoint.
A tokenization or recurring payment setup was successfully created.

Note: For POST requests, a 201 Created response code is returned upon success.

⚠️ 400 Bad Request

The request is malformed or missing required parameters.

This generally occurs if:

Required fields are missing.
JSON payloads are incorrectly formatted.
Supplied values are invalid.

Tip: Check the response body for detailed error messages specifying which field(s) caused the failure.

🔑 401 Unauthorized

Authentication failed.

Common causes:

The Authorization header is missing.
The provided token is invalid or has expired.

Ensure you’re using a valid, non-expired token in all requests.

❌ 404 Not Found

The requested resource could not be found.

Examples:

Querying /info/{id} for a payment that does not exist.
Attempting to access resources not associated with your account.

🛑 500 Internal Server Error

An unexpected error occurred on the server side while processing the request.

Generally indicates a problem within the platform or an upstream service failure.
Retry the request later or contact support if the issue persists.

🔎 Error Response Details

When an error occurs, the API returns a JSON response body containing:

An error code (machine-readable).
A human-readable message explaining the issue.

Always check the error response payload to debug and handle errors gracefully. For example:

{  
  "httpStatus": 400,  
  "internalCode": "common-4001",  
  "errorMessage": "Invalid amount format",  
  "traceId": "abcd1234efgh5678"  
}

Notes

Monetary amounts as strings: Always provide monetary values (such as amount) as strings (e.g., "100.00") rather than as numeric values. This ensures that decimal precision is preserved and no rounding occurs due to floating-point representation.
Polymorphic APM payload: The apmPayload field in the request is polymorphic, meaning its content will vary depending on the payment method. Each APM might require different fields within apmPayload (for example, a PayPal payload might differ from a bank transfer payload). Be sure to construct this object according to the requirements of the specific APM you are using.
Validate inputs: Always perform server-side validation of all fields (amount, currency, IDs, etc.) before sending the request. This helps prevent errors due to invalid data and ensures you only send well-formed requests to the API.
Callback reliability: The callback mechanism is the primary way you’ll be informed of the transaction outcome. Make sure your callback endpoint is robust and idempotent (able to handle repeats), and consider security measures like verifying the X-Checksum and restricting access to known IPs, etc.
UseapmResponseData: The apmResponseData object in the initial response is crucial for completing the payment flow. It contains the URL(s) or other information needed to guide the customer through the payment process (redirect or iframe). Always handle this object in your integration logic to ensure the customer can complete the payment.