Protect

23 operations. Authenticate with your secret API key (see Authentication); failures use the shape described in Errors. Example requests read $GIEP_API_URL, your deployment’s API host.

Get the alert auto-resolution policy

GET/v1/alert-policy

The pre-dispute alert auto-resolution policy: whether matched alerts are refunded automatically, whether an exact match is required and the largest amount refunded without a person. source is default until the merchant saves one (nothing is refunded automatically by default).

Authentication: API key (Bearer)
Permission: risk:read
Idempotency-Key: Not used
Success: 200

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/alert-policy" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Set the alert auto-resolution policy

PUT/v1/alert-policy

maxAmount (integer minor units) and currency go together; leave both out for no limit. Alerts outside the policy wait in manual review. Requires risk:manage. Audited.

Authentication: API key (Bearer)
Permission: risk:manage
Idempotency-Key: Not used
Success: 200

Request body · application/jsonrequired

autoRefundbooleanrequired
requireExactMatchboolean
Default false
maxAmountinteger
greater than 0
currencystring
3 chars

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X PUT "$GIEP_API_URL/v1/alert-policy" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "autoRefund": false
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

List pre-dispute alerts

GET/v1/alerts

Pre-dispute alerts, soonest deadline first by default. status is a comma list of received, matched, resolving, resolved, manual_review, expired, or open (everything not finished). Each row carries deadlineState (ok, due_soon within 24 h, overdue, closed), the policy path and the outcome. Paginated with limit / offset.

Authentication: API key (Bearer)
Permission: alert:read
Idempotency-Key: Not used
Success: 200

Query parameters

statusstring
sortstring
One ofdeadline-deadlinereceived-receivedDefault deadline
limitinteger
Default 100min 1 · max 200
offsetinteger
Default 0min 0
storeIdstring · uuid
A store of the merchant; omit for all of the merchant's stores

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/alerts" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Retrieve an alert

GET/v1/alerts/{id}

One alert with its deadline state, outcome, linked refund, the matched payment timeline and notes.

Authentication: API key (Bearer)
Permission: alert:read
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/alerts/d3aba6cf-b25d-4159-a394-62480b99" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Notes on an alert

GET/v1/alerts/{id}/notes

Notes on an alert, oldest first, with the kind of author (team member, API key, GIEP support, system).

Authentication: API key (Bearer)
Permission: alert:read
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/alerts/d3aba6cf-b25d-4159-a394-62480b99/notes" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Add a note to an alert

POST/v1/alerts/{id}/notes

Adds a note for the team (1 to 2000 characters). Requires refund:create (owner, admin, support). Audited.

Authentication: API key (Bearer)
Permission: refund:create
Idempotency-Key: Not used
Success: 201

Path parameters

idstringrequired

Request body · application/jsonrequired

bodystringrequired
min 1 chars · max 2000 chars

Responses

201Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 201 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/alerts/d3aba6cf-b25d-4159-a394-62480b99/notes" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "string"
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Resolve an alert manually (refund or dismiss)

POST/v1/alerts/{id}/resolve

Resolves an alert in manual review: refund (through the same refund path as auto-resolution: row lock, refundable check, per-alert idempotency key; paymentId only when the alert is not matched) or dismiss (tells the network the merchant is not refunding; cannot be undone). Audited.

Authentication: API key (Bearer)
Permission: refund:create
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Request body · application/jsonrequired

Option 1

actionstringrequired
Alwaysrefund
paymentIdstring · uuid
amountinteger
greater than 0
reasonstring
max 500 chars

Option 2

actionstringrequired
Alwaysdismiss
reasonstring
max 500 chars

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/alerts/d3aba6cf-b25d-4159-a394-62480b99/resolve" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "refund"
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Resolve several alerts

POST/v1/alerts/bulk-resolve

The same action on up to 100 alerts. Each alert runs on its own through the single-alert path and gets its own result (ok, outcome or error); one failure never stops the others, and a repeat never refunds twice.

Authentication: API key (Bearer)
Permission: refund:create
Idempotency-Key: Not used
Success: 200

Request body · application/jsonrequired

alertIdsarray<string> · uuidrequired
min 1 items · max 100 items
actionstringrequired
One ofrefunddismiss
reasonstring
max 500 chars

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/alerts/bulk-resolve" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "alertIds": [
    "e7565f3d-d3ab-4e67-a2f2-1d9fc-16c"
  ],
  "action": "refund"
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Pre-dispute alert outcomes and coverage

GET/v1/analytics/alert-coverage

Alerts received in [from, to) by type and outcome, the amount refunded through them (integer minor units), disputes opened and coverage = saved / (saved + disputes opened), with the same figures for the period of equal length before. No fee data is involved.

Authentication: API key (Bearer)
Permission: payment:read
Idempotency-Key: Not used
Success: 200

Query parameters

fromstring · date-timerequired
ISO 8601 instant with Z or an offset, e.g. 2026-10-24T00:00:00Z
pattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
tostring · date-timerequired
ISO 8601 instant with Z or an offset, e.g. 2026-10-24T00:00:00Z
pattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
currencystring
ISO 4217 code; defaults to the merchant's default currency
pattern ^[A-Za-z]{3}$

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

200 response fieldsAlertCoverage

currencystringrequired
3 chars
fromstringrequired
tostringrequired
receivedintegerrequired
byTypeobjectrequired
Fields: 4 fields
- ethocaobjectrequired
  Fields: 5 fields
  receivedintegerrequired
  refundedintegerrequired
  Resolved with a succeeded refund.
  resolvedNoRefundintegerrequired
  Resolved without a refund (already refunded, dismissed).
  openintegerrequired
  Not finished: received, matched, resolving or in manual review.
  expiredintegerrequired
  Deadline passed without a response.
- cdrnobjectrequired
  Fields: 5 fields
  receivedintegerrequired
  refundedintegerrequired
  Resolved with a succeeded refund.
  resolvedNoRefundintegerrequired
  Resolved without a refund (already refunded, dismissed).
  openintegerrequired
  Not finished: received, matched, resolving or in manual review.
  expiredintegerrequired
  Deadline passed without a response.
- rdrobjectrequired
  Fields: 5 fields
  receivedintegerrequired
  refundedintegerrequired
  Resolved with a succeeded refund.
  resolvedNoRefundintegerrequired
  Resolved without a refund (already refunded, dismissed).
  openintegerrequired
  Not finished: received, matched, resolving or in manual review.
  expiredintegerrequired
  Deadline passed without a response.
- otherobjectrequired
  Fields: 5 fields
  receivedintegerrequired
  refundedintegerrequired
  Resolved with a succeeded refund.
  resolvedNoRefundintegerrequired
  Resolved without a refund (already refunded, dismissed).
  openintegerrequired
  Not finished: received, matched, resolving or in manual review.
  expiredintegerrequired
  Deadline passed without a response.
outcomesobjectrequired
Fields: 4 fields
- refundedintegerrequired
  Resolved with a succeeded refund.
- resolvedNoRefundintegerrequired
  Resolved without a refund (already refunded, dismissed).
- openintegerrequired
  Not finished: received, matched, resolving or in manual review.
- expiredintegerrequired
  Deadline passed without a response.
savedintegerrequired
Refunded alerts whose payment has no dispute.
refundedAmountintegerrequired
Sum of the refunds linked to refunded alerts (minor units).
disputesOpenedintegerrequired
coveragenumberrequirednullable
saved / (saved + disputesOpened); null if both are 0.
min 0 · max 1
previousobjectrequired
Fields: 9 fields
- fromstringrequired
- tostringrequired
- receivedintegerrequired
- byTypeobjectrequired
  Fields: 4 fields
  ethocaobjectrequired
  Fields: 5 fields
  receivedintegerrequired
  refundedintegerrequired
  Resolved with a succeeded refund.
  resolvedNoRefundintegerrequired
  Resolved without a refund (already refunded, dismissed).
  openintegerrequired
  Not finished: received, matched, resolving or in manual review.
  expiredintegerrequired
  Deadline passed without a response.
  cdrnobjectrequired
  Fields: 5 fields
  receivedintegerrequired
  refundedintegerrequired
  Resolved with a succeeded refund.
  resolvedNoRefundintegerrequired
  Resolved without a refund (already refunded, dismissed).
  openintegerrequired
  Not finished: received, matched, resolving or in manual review.
  expiredintegerrequired
  Deadline passed without a response.
  rdrobjectrequired
  Fields: 5 fields
  receivedintegerrequired
  refundedintegerrequired
  Resolved with a succeeded refund.
  resolvedNoRefundintegerrequired
  Resolved without a refund (already refunded, dismissed).
  openintegerrequired
  Not finished: received, matched, resolving or in manual review.
  expiredintegerrequired
  Deadline passed without a response.
  otherobjectrequired
  Fields: 5 fields
  receivedintegerrequired
  refundedintegerrequired
  Resolved with a succeeded refund.
  resolvedNoRefundintegerrequired
  Resolved without a refund (already refunded, dismissed).
  openintegerrequired
  Not finished: received, matched, resolving or in manual review.
  expiredintegerrequired
  Deadline passed without a response.
- outcomesobjectrequired
  Fields: 4 fields
  refundedintegerrequired
  Resolved with a succeeded refund.
  resolvedNoRefundintegerrequired
  Resolved without a refund (already refunded, dismissed).
  openintegerrequired
  Not finished: received, matched, resolving or in manual review.
  expiredintegerrequired
  Deadline passed without a response.
- savedintegerrequired
  Refunded alerts whose payment has no dispute.
- refundedAmountintegerrequired
  Sum of the refunds linked to refunded alerts (minor units).
- disputesOpenedintegerrequired
- coveragenumberrequirednullable
  saved / (saved + disputesOpened); null if both are 0.
  min 0 · max 1

Request · cURL

curl -X GET "$GIEP_API_URL/v1/analytics/alert-coverage?from=1&to=1" \
  -H "Authorization: Bearer $GIEP_API_KEY"

{
  "currency": "USD",
  "from": "string",
  "to": "string",
  "received": 1,
  "byType": {
    "ethoca": {
      "received": 1,
      "refunded": 1,
      "resolvedNoRefund": 1,
      "open": 1,
      "expired": 1
    },
    "cdrn": {
      "received": 1,
      "refunded": 1,
      "resolvedNoRefund": 1,
      "open": 1,
      "expired": 1
    },
    "rdr": {
      "received": 1,
      "refunded": 1,
      "resolvedNoRefund": 1,
      "open": 1,
      "expired": 1
    },
    "other": {
      "received": 1,
      "refunded": 1,
      "resolvedNoRefund": 1,
      "open": 1,
      "expired": 1
    }
  },
  "outcomes": {
    "refunded": 1,
    "resolvedNoRefund": 1,
    "open": 1,
    "expired": 1
  },
  "saved": 1,
  "refundedAmount": 4999,
  "disputesOpened": 1,
  "coverage": 1,
  "previous": {
    "from": "string",
    "to": "string",
    "received": 1,
    "byType": {
      "ethoca": {
        "received": 1,
        "refunded": 1,
        "resolvedNoRefund": 1,
        "open": 1,
        "expired": 1
      },
      "cdrn": {
        "received": 1,
        "refunded": 1,
        "resolvedNoRefund": 1,
        "open": 1,
        "expired": 1
      },
      "rdr": {
        "received": 1,
        "refunded": 1,
        "resolvedNoRefund": 1,
        "open": 1,
        "expired": 1
      },
      "other": {
        "received": 1,
        "refunded": 1,
        "resolvedNoRefund": 1,
        "open": 1,
        "expired": 1
      }
    },
    "outcomes": {
      "refunded": 1,
      "resolvedNoRefund": 1,
      "open": 1,
      "expired": 1
    },
    "saved": 1,
    "refundedAmount": 4999,
    "disputesOpened": 1,
    "coverage": 1
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

List blocklist entries

GET/v1/blocklist

Blocklist entries (email, IP address, country, card BIN, card fingerprint). Expired entries only with includeExpired=true. Requires risk:read.

Authentication: API key (Bearer)
Permission: risk:read
Idempotency-Key: Not used
Success: 200

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/blocklist" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Add a blocklist entry

POST/v1/blocklist

Adds an entry. Matching payments are refused before any payment is created or any processor is called. For card_fingerprint, pass paymentId to block the card that paid that payment. Optional reason and expiresAt. Requires risk:manage. Audited.

Authentication: API key (Bearer)
Permission: risk:manage
Idempotency-Key: Not used
Success: 201

Request body · application/jsonrequired

kindstringrequired
One ofemailcard_fingerprintipbincountry
valuestring
min 1 chars · max 256 chars
paymentIdstring · uuid
reasonstring
max 500 chars
expiresAtany

Responses

201Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 201 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/blocklist" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "email"
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Remove a blocklist entry

DELETE/v1/blocklist/{id}

Removes a blocklist entry. Requires risk:manage. Audited.

Authentication: API key (Bearer)
Permission: risk:manage
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X DELETE "$GIEP_API_URL/v1/blocklist/d3aba6cf-b25d-4159-a394-62480b99" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

List disputes

GET/v1/disputes

Disputes reported by processors, newest first. status is a comma list (open, evidence_submitted, won, lost, accepted, expired, cancelled); optional storeId. Paginated with limit / offset.

Authentication: API key (Bearer)
Permission: alert:read
Idempotency-Key: Not used
Success: 200

Query parameters

statusstring
Comma-separated statuses.
limitinteger
min 1 · max 200
offsetinteger
min 0

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/disputes" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Dispute with payment timeline

GET/v1/disputes/{id}

One dispute with a summary of its payment (amount, status, card brand and last 4) and the payment timeline.

Authentication: API key (Bearer)
Permission: alert:read
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/disputes/d3aba6cf-b25d-4159-a394-62480b99" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

List fraud rules

GET/v1/fraud-rules

The merchant's fraud rules (conditions, block or review action, priority, enabled). There is no workspace screen for fraud rules in this release; manage them through the API.

Authentication: API key (Bearer)
Permission: risk:read
Idempotency-Key: Not used
Success: 200

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/fraud-rules" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Create a fraud rule

POST/v1/fraud-rules

Creates a rule: conditions is rules-engine JSON whose top level is all, any or not, over payment facts such as amount, currency, email, IP, country, card BIN, card fingerprint and 1-hour email / IP velocity; action is block or review; a lower priority is evaluated first and the strictest matching action wins (block over review). Requires risk:manage. Audited.

Authentication: API key (Bearer)
Permission: risk:manage
Idempotency-Key: Not used
Success: 201

Request body · application/jsonrequired

namestringrequired
min 1 chars · max 120 chars
priorityinteger
Default 100min 0 · max 9999
conditionsmap<string, any>required
actionstringrequired
One ofblockreview
enabledboolean
Default true

Responses

201Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 201 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/fraud-rules" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "conditions": {},
  "action": "block"
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Retrieve a fraud rule

GET/v1/fraud-rules/{id}

One fraud rule with its conditions, action, priority and enabled state.

Authentication: API key (Bearer)
Permission: risk:read
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/fraud-rules/d3aba6cf-b25d-4159-a394-62480b99" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Update a fraud rule

PATCH/v1/fraud-rules/{id}

Changes any field of a rule. Requires risk:manage. Audited.

Authentication: API key (Bearer)
Permission: risk:manage
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Request body · application/jsonrequired

namestring
min 1 chars · max 120 chars
priorityinteger
Default 100min 0 · max 9999
conditionsmap<string, any>
actionstring
One ofblockreview
enabledboolean
Default true

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X PATCH "$GIEP_API_URL/v1/fraud-rules/d3aba6cf-b25d-4159-a394-62480b99" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "priority": 100,
  "conditions": {}
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Delete a fraud rule

DELETE/v1/fraud-rules/{id}

Deletes a fraud rule. Requires risk:manage. Audited.

Authentication: API key (Bearer)
Permission: risk:manage
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X DELETE "$GIEP_API_URL/v1/fraud-rules/d3aba6cf-b25d-4159-a394-62480b99" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Dry-run a rule on history

POST/v1/fraud-rules/dry-run

Evaluates the saved rules, or the rules given in the body, against one set of payment facts and returns what would happen. Changes nothing.

Authentication: API key (Bearer)
Permission: risk:read
Idempotency-Key: Not used
Success: 200

Request body · application/jsonrequired

factsobjectrequired
Fields: 10 fields
- amountintegerrequired
  greater than 0
- currencystringrequired
  3 chars
- emailstring
- ipstring
- countrystring
  2 chars
- cardBinstring
- cardFingerprintstring
  max 128 chars
- storeIdstring · uuid
- emailVelocity1hinteger
  min 0
- ipVelocity1hinteger
  min 0
rulesarray<object>
max 50 items
Each item has 3 fields
- namestring
  max 120 chars
- conditionsmap<string, any>required
- actionstringrequired
  One ofblockreview

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X POST "$GIEP_API_URL/v1/fraud-rules/dry-run" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "facts": {
    "amount": 4999,
    "currency": "USD"
  }
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Override the statement descriptor for one processor account

PUT/v1/processor-accounts/{id}/statement-descriptor

Overrides the descriptor for one processor account (MID); null removes the override so the merchant descriptor applies. Requires processor:manage. Audited.

Authentication: API key (Bearer)
Permission: processor:manage
Idempotency-Key: Not used
Success: 200

Path parameters

idstringrequired

Request body · application/jsonrequired

statementDescriptorstringrequirednullable
max 100 chars

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X PUT "$GIEP_API_URL/v1/processor-accounts/d3aba6cf-b25d-4159-a394-62480b99/statement-descriptor" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "statementDescriptor": "string"
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Statement descriptor and support contact

GET/v1/receipt-settings

The statement descriptor and the support contact (email, website) shown to shoppers on the order lookup page, and per-processor-account descriptor overrides.

Authentication: API key (Bearer)
Permission: processor:read
Idempotency-Key: Not used
Success: 200

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X GET "$GIEP_API_URL/v1/receipt-settings" \
  -H "Authorization: Bearer $GIEP_API_KEY"

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}

Set the statement descriptor and support contact

PUT/v1/receipt-settings

The descriptor is at most 22 characters from letters, digits, spaces and . , - & / (stored in upper case).

Authentication: API key (Bearer)
Permission: processor:manage
Idempotency-Key: Not used
Success: 200

Request body · application/jsonrequired

statementDescriptorstringnullable
max 100 chars
supportEmailstring · emailnullable
max 320 chars
supportUrlstring · urinullable
max 500 chars

Responses

200Success
401Missing or invalid credentials Body is an error object with code and message.
403Role not permitted Body is an error object with code and message.
422Validation failed (invalid_request) Body is an error object with code and message.
429Rate limited (rate_limited); see Retry-After Body is an error object with code and message.

The 200 response is a JSON object. The OpenAPI document does not describe its fields.

Request · cURL

curl -X PUT "$GIEP_API_URL/v1/receipt-settings" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "statementDescriptor": "string",
  "supportEmail": "[email protected]",
  "supportUrl": "https://shop.example/support"
}'

// JSON object. The OpenAPI document does not list its fields.

{
  "error": {
    "code": "unauthorized",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable explanation"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Human-readable explanation"
  }
}