Authentication & Authorization

Creating API credentials

Go to https://app.trusto.io and open Settings → API Credentials.
As an Organization Owner, generate an API key for your organization.
Save the key when it is created. It cannot be viewed again.
Send the key in the X-API-KEY header with every API request.

The examples below use the production API at https://api.trusto.io.

Alerts

Retrieve all alerts

Returns a paginated collection of alerts available to the organization associated with the API key.

Endpoint

GET /api/v1/alerts

Request headers

Header	Type	Required	Description
X-API-KEY	string	Yes	API key generated in Trusto.
Content-Type	string	No	Use `application/json`.

Query parameters

Parameter	Type	Required	Description
page	integer	No	Zero-based page index. Defaults to `0`.
size	integer	No	Results per page. Defaults to `10`.
startDate	string	No	Alert date on or after this date, in `YYYY-MM-DD` format.
endDate	string	No	Alert date on or before this date, in `YYYY-MM-DD` format.
transactionStartDate	string	No	Transaction date on or after this date, in `YYYY-MM-DD` format.
transactionEndDate	string	No	Transaction date on or before this date, in `YYYY-MM-DD` format.
provider	string	No	One or more comma-separated providers: `ETHOCA`, `VERIFI`, or `CDRN`.
type	string	No	One or more comma-separated alert types.
status	string	No	One or more comma-separated statuses: `OPEN`, `RESOLVED`, `REFUNDED`, `CHARGEBACK`, `EXPIRED`, or `INVALID`.
descriptor	string	No	Merchant descriptor filter.
outcome	string	No	One or more comma-separated outcome values.
expired	boolean	No	Filter by whether `expiredAt` is populated.
expiresIn	integer	No	Return unresolved alerts expiring within this many hours.
sortField	string	No	Alert field used for sorting.
sortOrder	string	No	`ASC` or `DESC`.
q	string	No	Search provider ID, merchant descriptor, card BIN, or last four digits.

Sample request

curl "https://api.trusto.io/api/v1/alerts?page=0&size=10&startDate=2024-10-01&endDate=2024-11-30&provider=ETHOCA" \
  -H "X-API-KEY: YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "c8edf8a4-4e4d-4821-af34-9ed2995cbd8b",
      "providerId": "6d9e6dc7-3cf7-4a9d-ae66-97bcf86b80d2",
      "provider": "ETHOCA",
      "type": "ETHOCA_CONFIRMED_FRAUD",
      "alertTimeStamp": "2024-11-10T19:07:56.293Z",
      "enrollmentId": "554df940-b344-40ab-85fd-fc7b89c86ad1",
      "companyId": "7224a209-dc9c-4101-846d-2bc57eacd2b7",
      "issuer": "BARCLAYS",
      "cardBin": "123456",
      "cardLastFour": "1234",
      "cardExpirationDate": null,
      "acquirerBin": null,
      "status": "OPEN",
      "statusCode": null,
      "ruleType": null,
      "ruleName": null,
      "installmentNumber": null,
      "pricingTier": null,
      "transactionTimeStamp": "2024-11-09T09:30:00.000Z",
      "merchantDescriptor": "SAMPLE STORE",
      "descriptorContact": null,
      "ethocaMerchantId": "ETH123456",
      "merchantId": "54321",
      "merchantOrderId": "ORDER-123",
      "merchantName": "Sample Merchant",
      "partnerId": null,
      "partnerName": null,
      "clientName": null,
      "caid": null,
      "mcc": "5411",
      "amount": "250.75",
      "currency": "EUR",
      "transactionType": "KEYED",
      "initiatedBy": "CARDHOLDER",
      "liability": "YES",
      "authCode": "ABC12345",
      "source": "BARCLAYS",
      "reasonCode": "UNAU",
      "acquirerReferenceNumber": "12345678901234567890123",
      "transactionId": "TRANS123456789",
      "chargebackAmount": null,
      "chargebackCurrency": null,
      "paymentType": null,
      "createdAt": "2024-11-10T19:07:56.293Z",
      "updatedAt": "2024-11-10T19:07:56.293Z",
      "expiredAt": null,
      "hasExternalTransaction": false,
      "outcome": null,
      "hoursLeft": 18
    }
  ],
  "total": 1,
  "page": 0,
  "size": 10,
  "totalPages": 1
}

The outcome property is null until a resolution is recorded. The list response also includes hoursLeft, which is 0 after an outcome exists.

Retrieve an alert by ID

Returns one alert, including its current outcome.

Endpoint

GET /api/v1/alerts/:id

Sample request

curl "https://api.trusto.io/api/v1/alerts/c8edf8a4-4e4d-4821-af34-9ed2995cbd8b" \
  -H "X-API-KEY: YOUR_API_KEY"

Resolved alert response

{
  "id": "c8edf8a4-4e4d-4821-af34-9ed2995cbd8b",
  "providerId": "6d9e6dc7-3cf7-4a9d-ae66-97bcf86b80d2",
  "provider": "ETHOCA",
  "type": "ETHOCA_CONFIRMED_FRAUD",
  "status": "RESOLVED",
  "amount": "250.75",
  "currency": "EUR",
  "hasExternalTransaction": false,
  "createdAt": "2024-11-10T19:07:56.293Z",
  "updatedAt": "2024-11-10T19:12:20.000Z",
  "outcome": {
    "id": "4a0c8f5d-4b8d-4f4d-8f1a-2f8c9c1e5b7b",
    "alertId": "c8edf8a4-4e4d-4821-af34-9ed2995cbd8b",
    "ethocaID": "6d9e6dc7-3cf7-4a9d-ae66-97bcf86b80d2",
    "status": "SUCCESS",
    "outcome": "other",
    "refunded": "refunded",
    "comments": "Customer issue resolved.",
    "disputeReasonCode": null,
    "actionTimestamp": "2024-11-10T19:12:20.000Z"
  }
}

The example is abbreviated. Alert details use the same alert fields returned inside the list response.

Resolutions

Provide an alert resolution

Records a resolution for an unresolved alert and returns the updated alert with its nested outcome.

Endpoint

PUT /api/v1/alerts/:id/resolution

Request headers

Header	Type	Required	Description
X-API-KEY	string	Yes	API key generated in Trusto.
Content-Type	string	Yes	Must be `application/json`.

Path parameters

Parameter	Type	Description
id	UUID	Trusto alert ID.

Body parameters

Parameter	Type	Required	Description
refunded	string	Yes	Merchant decision: `REFUNDED`, `NOT REFUNDED`, or `INVALID`.
resolution	string or null	For `INVALID`	Reason the alert is invalid. Omit it or send `null` for other decisions.
comments	string	No	Free-form comments, up to 250 characters.

When refunded is INVALID, use one of these resolution values:

Resolution	Meaning
REFUNDED_PREVIOUSLY_REFUNDED	The transaction was refunded before this alert.
NOT_REFUNDED_CHARGEBACK_RECEIVED	A chargeback has already been received.
NOT_REFUNDED_DUPLICATE	The alert is a duplicate.
NOT_REFUNDED_NOT_FOUND	The transaction could not be found.

Resolution results

refunded	resolution	Alert status
REFUNDED	Omitted or `null`	RESOLVED
NOT REFUNDED	Omitted or `null`	CHARGEBACK
INVALID	REFUNDED_PREVIOUSLY_REFUNDED	INVALID
INVALID	NOT_REFUNDED_CHARGEBACK_RECEIVED	INVALID
INVALID	NOT_REFUNDED_DUPLICATE	INVALID
INVALID	NOT_REFUNDED_NOT_FOUND	INVALID

Refunded request

curl -X PUT "https://api.trusto.io/api/v1/alerts/c8edf8a4-4e4d-4821-af34-9ed2995cbd8b/resolution" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refunded": "REFUNDED",
    "resolution": null,
    "comments": "Customer issue resolved."
  }'

Invalid request

{
  "refunded": "INVALID",
  "resolution": "NOT_REFUNDED_NOT_FOUND",
  "comments": "No matching transaction was found."
}

Response

A successful request returns the updated alert object. Its status reflects the decision, and its outcome contains the stored resolution details. A resolution submitted for an alert that already has an outcome returns a conflict error. Provider failures return a bad request error and the resolution is not retained.

Webhooks

Webhooks enable organizations to receive event notifications about subscribed entities.

Supported events

Event	Description
alert.created	Triggered when a new alert is created.
alert.resolved	Triggered when an alert is resolved.

Webhook authentication

Trusto can send either Basic Authentication or custom headers configured for the webhook endpoint.

Appendix

Alert types

ETHOCA_CONFIRMED_FRAUD
ETHOCA_CUSTOMER_DISPUTE
VERIFI_DISPUTE
VERIFI_CANCEL
VERIFI_DISPUTE_NOTICE
VERIFI_FRAUD_NOTICE
VERIFI_CANCEL_NOTICE

Alert outcome fields

Attribute	Type	Description
id	UUID	Outcome ID.
alertId	UUID	Trusto alert ID.
ethocaID	string	Provider alert ID. The legacy field name is retained for all providers.
status	string	Outcome processing status, such as `SUCCESS`.
outcome	string	Internal normalized outcome.
refunded	string	Stored normalized refund decision.
comments	string	Resolution comments.
disputeReasonCode	string or null	Normalized invalid reason.
actionTimestamp	string	Resolution timestamp in ISO 8601 format.

API Reference

Trusto API Documentation

Authentication & Authorization

Creating API credentials

Alerts

Retrieve all alerts

Endpoint

Request headers

Query parameters

Sample request

Response

Retrieve an alert by ID

Endpoint

Sample request

Resolved alert response

Resolutions

Provide an alert resolution

Endpoint

Request headers

Path parameters

Body parameters

Resolution results

Refunded request

Invalid request

Response

Webhooks

Supported events

Webhook authentication

Appendix

Alert types

Alert outcome fields

​Authentication & Authorization

​Creating API credentials

​Alerts

​Retrieve all alerts

​Endpoint

​Request headers

​Query parameters

​Sample request

​Response

​Retrieve an alert by ID

​Endpoint

​Sample request

​Resolved alert response

​Resolutions

​Provide an alert resolution

​Endpoint

​Request headers

​Path parameters

​Body parameters

​Resolution results

​Refunded request

​Invalid request

​Response

​Webhooks

​Supported events

​Webhook authentication

​Appendix

​Alert types

​Alert outcome fields

Authentication & Authorization

Creating API credentials

Alerts

Retrieve all alerts

Endpoint

Request headers

Query parameters

Sample request

Response

Retrieve an alert by ID

Endpoint

Sample request

Resolved alert response

Resolutions

Provide an alert resolution

Endpoint

Request headers

Path parameters

Body parameters

Resolution results

Refunded request

Invalid request

Response

Webhooks

Supported events

Webhook authentication

Appendix

Alert types

Alert outcome fields