Axis API Base URL, Request Format, and Error Handling

const BASE_URL = "https://api.axispayments.ai";

async function axisRequest<T>(
  path: string,
  options: {
    method?: "GET" | "POST" | "PATCH" | "DELETE";
    body?: unknown;
    apiKey?: string;
    token?: string;
  } = {}
): Promise<T> {
  const { method = "GET", body, apiKey, token } = options;

  const headers: Record<string, string> = {
    "Content-Type": "application/json",
  };

  if (apiKey) {
    headers["x-api-key"] = apiKey;
  } else if (token) {
    headers["Authorization"] = `Bearer ${token}`;
  }

  const response = await fetch(`${BASE_URL}${path}`, {
    method,
    headers,
    body: body !== undefined ? JSON.stringify(body) : undefined,
  });

  if (!response.ok) {
    const error = await response.json();
    throw new AxisApiError(response.status, error);
  }

  return response.json() as Promise<T>;
}

{
  "status": "fail",
  "message": "invalid request body",
  "details": {
    "amount": ["Must be greater than 0"]
  }
}

// axis-error.ts

export interface AxisErrorBody {
  status: string;
  message: string;
  code?: AxisErrorCode;
  details?: Record<string, string[]>;
}

export type AxisErrorCode =
  | "MISSING_API_KEY"
  | "INVALID_API_KEY"
  | "WALLET_INACTIVE"
  | "WALLET_EXPIRED"
  | "SPEND_LIMIT_PER_TX_EXCEEDED"
  | "SPEND_LIMIT_PER_PERIOD_EXCEEDED"
  | "MERCHANT_NOT_ALLOWED"
  | "INSUFFICIENT_FUNDS";

export class AxisApiError extends Error {
  status: number;
  body: AxisErrorBody;

  constructor(status: number, body: AxisErrorBody) {
    super(body.message);
    this.name = "AxisApiError";
    this.status = status;
    this.body = body;
  }

  /** True when the authorization engine rejected the payment. */
  isAuthorizationFailure(): boolean {
    return this.status === 403;
  }

  /** True when request body validation failed — check `body.details` for field errors. */
  isValidationError(): boolean {
    return this.status === 400;
  }
}

// Usage example in a React component:
async function submitPayment(walletId: string, amount: number) {
  try {
    const result = await axisRequest("/api/payment-intent", {
      method: "POST",
      apiKey: process.env.NEXT_PUBLIC_AXIS_API_KEY,
      body: { walletId, amount },
    });
    return result;
  } catch (err) {
    if (err instanceof AxisApiError) {
      if (err.isAuthorizationFailure()) {
        switch (err.body.code) {
          case "INSUFFICIENT_FUNDS":
            showToast("Your wallet doesn't have enough funds for this payment.");
            break;
          case "SPEND_LIMIT_PER_TX_EXCEEDED":
            showToast("This payment exceeds the per-transaction spend limit.");
            break;
          case "MERCHANT_NOT_ALLOWED":
            showToast("This merchant is not permitted for your wallet.");
            break;
          case "WALLET_INACTIVE":
          case "WALLET_EXPIRED":
            showToast("Your wallet is no longer active. Please contact support.");
            break;
          default:
            showToast(`Payment declined: ${err.message}`);
        }
      } else if (err.isValidationError() && err.body.details) {
        // Surface field-level errors in a form
        setFieldErrors(err.body.details);
      } else if (err.status === 401) {
        redirectToLogin();
      } else {
        showToast("Something went wrong. Please try again.");
      }
    }
    throw err;
  }
}