Dispute Integration API

Internal/admin endpoints used by Dispute.com integration.

Internal/admin endpoints.

Authentication

All endpoints require:

• Header: x-api-key: <DISPUTE_MASTER_OR_SERVICE_KEY>

Also send:

• Content-Type: application/json

Base path

Paths below are shown as implemented (for example: POST /accounts).

If these routes are hosted behind an internal prefix (like /admin), apply that prefix in your environment.

Accounts

POST /accounts

Create a new Fense account.

Request body

• api_key (string, required)

  • Merchant API key for this account

• name (string, required)

  • Account/company name

• email (string, required)

  • Owner email address

• suppress_notifications (boolean, optional, default: false)

  • Skip all outbound notifications

• suppress_billing (boolean, optional, default: false)

  • Skip billing/charging operations

• dispute_account_id (uuid, optional)

  • UUID linking to the Dispute.com account

Response: 201 Created

{
  "fense_account_id": 123,
  "name": "Company Name",
  "api_key": "merchant_key_xxx",
  "suppress_notifications": false,
  "suppress_billing": false,
  "is_active": true,
  "created_at": "2025-12-04T17:28:21-03:00"
}

GET /accounts/{fense_account_id}

Retrieve a Fense account by ID.

Path parameters

• fense_account_id (integer, required)

Response: 200 OK

{
  "fense_account_id": 123,
  "name": "Company Name",
  "api_key": "merchant_key_xxx",
  "suppress_notifications": false,
  "suppress_billing": false,
  "is_active": true,
  "is_dispute_managed": true,
  "dispute_account_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2025-12-04T17:28:21-03:00",
  "updated_at": "2025-12-04T17:30:00-03:00"
}

POST /accounts/{fense_account_id}

Update an existing Fense account.

All fields are optional.

Path parameters

• fense_account_id (integer, required)

Request body

• api_key (string)

  • Update the merchant API key

• name (string)

  • Update account name

• suppress_notifications (boolean)

  • Toggle notifications

• suppress_billing (boolean)

  • Toggle billing

• is_active (boolean)

  • Activate/deactivate account

• dispute_account_id (uuid)

  • Update Dispute.com link

Response

Returns the updated account.

Usage

GET /accounts/usage and GET /accounts/usage/{fense_account_id}

Get anti-fraud lookup usage metrics.

If fense_account_id is omitted, returns usage for all accounts.

Path parameters

• fense_account_id (integer, optional)

Query parameters (optional)

• start_date (YYYY-MM-DD)

  • Filter start date

• end_date (YYYY-MM-DD)

  • Filter end date

• fense_account_id (integer)

  • Alternative to the path parameter

If `start_date` is provided, `end_date` is required.

Response: 200 OK (single account)

{
  "fense_account_id": 123,
  "period": {
    "start_date": "2025-01-01",
    "end_date": "2025-12-31"
  },
  "usage": {
    "total_lookups": 1500,
    "total_cost": 75.0
  }
}

Response: 200 OK (all accounts)

{
  "period": {
    "start_date": "2025-01-01",
    "end_date": "2025-12-31"
  },
  "accounts": [
    {
      "fense_account_id": 123,
      "name": "Company A",
      "total_lookups": 1000,
      "total_cost": 50.0
    }
  ],
  "summary": {
    "total_accounts": 5,
    "total_lookups": 5000,
    "total_cost": 250.0
  }
}

Errors

All endpoints return a consistent error shape.

• 400 Bad Request

{"error": "Validation failed", "messages": {}}

• 401 Unauthorized

{"error": "Authentication required", "message": "..."}

• 403 Forbidden

{"error": "Forbidden", "message": "..."}

• 404 Not Found

{"error": "Account not found", "message": "..."}

• 500 Internal Server Error

{"error": "...", "message": "..."}