Skip to main content

Getting Started

Triple offers two integration paths. Pick the one that matches what you already have:

  • Path A: Embed intake. Use this if the cardholder is about to describe the dispute in your app and you want Triple to collect the statement, classify the case, and run the evaluation.
  • Path B: Call evaluations directly. Use this if you already have the transaction, card, and evidence in structured form.

Both paths land you in the same place: an evaluation result with a confidence score, a proposed card-network reason code, and the gaps weakening the case.

Prerequisites​

  • A Triple account with API access
  • Access to authorization and clearing data for your disputes
  • HTTPS endpoint for receiving webhook notifications (recommended)

Step 1: Get your API key​

API keys are managed through the Triple Dashboard:

  1. Log in to your Triple Dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Copy and securely store your key
caution

Your API key will only be shown once. Store it securely and never expose it in client-side code.

Path A: Embed intake​

The fastest path. Triple's hosted form or chatbot runs inside your app in an iframe. When the cardholder finishes, we hand you back an evaluation.

Beta

The intake endpoints and events shown below are under active development. Field names and event shapes may change before GA.

1. Create an intake session​

The intake request mirrors the evaluations request: transaction and card use the same shape as POST /evaluations/, so you can pass the same data without reshaping it.

curl -X POST https://api.disputes.sandbox.tripledev.app/api/intake/sessions/ \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "transaction": {
    "transaction_id": "txn_12345",
    "card_scheme": "MC",
    "channel_type": "ECOMMERCE",
    "merchant_name": "ACME Store",
    "merchant_country": "USA",
    "transaction_amount": 299.99,
    "transaction_currency": "USD",
    "merchant_id": "MERCHANT123",
    "transaction_timestamp": "2024-01-20T10:30:00Z",
    "settlement_timestamp": "2024-01-22T00:00:00Z",
    "arn": "12345678901234567890123",
    "rrn": "123456789012",
    "merchant_category_code": "5311",
    "terminal_id": "term_01",
    "mobile_wallet": null,
    "avs_result": "NO_MATCH",
    "cvv_match": false,
    "eci_code": "05",
    "batch_id": "batch_001"
  },
  "card": {
    "bin": "54133388",
    "last_4": "1234",
    "emv_chip_enabled": true,
    "emv_pin_preferring": false
  },
  "cardholder": {
    "external_id": "cust_9f3a2"
  }
}'

You get back a short-lived URL:

{
  "id": "is_a1b2c3",
  "url": "https://intake.triple.app/s/is_a1b2c3",
  "expires_at": "2026-04-23T16:30:00Z",
  "status": "pending"
}

2. Embed the returned URL​

<iframe
  src="https://intake.triple.app/s/is_a1b2c3"
  width="480"
  height="640"
  allow="clipboard-write"
></iframe>

3. Listen for completion​

When the cardholder finishes, Triple posts a message to the parent window and (if configured) fires a webhook.

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://intake.triple.app') return;
  if (event.data?.type === 'triple.intake.completed') {
    const { intake_session_id, evaluation_id } = event.data;
    // evaluation_id is ready to fetch
  }
});

4. Fetch the evaluation result​

Same endpoint as Path B, using the evaluation_id you just received. See Receive the result below for the shape.

See Intake integration for the full reference.

Path B: Call evaluations directly​

Use this path when your system already holds the transaction, card, and evidence for the dispute.

1. Submit an evaluation​

curl -X POST https://api.disputes.sandbox.tripledev.app/api/evaluations/ \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "dispute": {
    "disputed_amount": 299.99,
    "disputed_currency": "USD"
  },
  "transaction": {
    "transaction_id": "txn_12345",
    "card_scheme": "MC",
    "channel_type": "ECOMMERCE",
    "merchant_name": "ACME Store",
    "merchant_country": "USA",
    "transaction_amount": 299.99,
    "transaction_currency": "USD",
    "merchant_id": "MERCHANT123",
    "transaction_timestamp": "2024-01-20T10:30:00Z",
    "settlement_timestamp": "2024-01-22T00:00:00Z",
    "arn": "12345678901234567890123",
    "rrn": "123456789012",
    "merchant_category_code": "5311",
    "terminal_id": "term_01",
    "mobile_wallet": null,
    "avs_result": "NO_MATCH",
    "cvv_match": false,
    "eci_code": "05",
    "batch_id": "batch_001"
  },
  "card": {
    "bin": "54133388",
    "last_4": "1234",
    "emv_chip_enabled": true,
    "emv_pin_preferring": false
  },
  "evidences": {
    "cardholder_statement": "I did not make this purchase. My card was in my possession at all times."
  }
}'

Notice there is no category field in the request above. Triple classifies the dispute internally from the transaction, card, and evidence you sent. You don't map your own reason codes to Triple's categories.

The API returns an evaluation ID:

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}
Important

Store this ID. You will need it to retrieve the evaluation result.

2. Store the evaluation ID​

Evaluations are processed asynchronously, so persist the id you got back.

Receive the result​

However the evaluation started (Path A or Path B), results come back the same way. The recommended approach is configuring a webhook endpoint, where your server receives an HTTP POST as soon as the evaluation finishes.

As a fallback, you can poll the result endpoint using the evaluation ID:

curl https://api.disputes.sandbox.tripledev.app/api/evaluations/{evaluation_id}/result \
-H "Authorization: Bearer $API_KEY"

The result contains:

  • Category: The dispute category Triple classified the case as
  • Confidence: high, moderate_high, moderate_low, or low
  • Reason code: Proposed card-network reason code (may be null if the evidence isn't enough for a precise mapping)
  • Failed checks: Specific issues that affected the confidence score, or missing information
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "category": "fraud",
  "confidence": "high",
  "reason_code": "4837",
  "failed_checks": []
}

Next steps​