Health

26 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.

Confirm a health email recipient (token from the emailed link)

POST/public/notifications/confirm

Confirms a health email recipient with the token from the emailed link. The workspace page posts it only after an explicit click (mail scanners open links). Invalid or used tokens are refused.

Authentication: None (public route)
Permission: Not stated
Idempotency-Key: Not used
Success: 200

Request body · application/jsonrequired

tokenstringrequired
min 10 chars · max 300 chars

Responses

200Success
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/public/notifications/confirm" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "string"
}'

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

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

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

Stop health emails to one address (token from the emailed link)

POST/public/notifications/unsubscribe

Stops health emails to the address the token belongs to. The address can be added again later by the merchant.

Authentication: None (public route)
Permission: Not stated
Idempotency-Key: Not used
Success: 200

Request body · application/jsonrequired

tokenstringrequired
min 10 chars · max 300 chars

Responses

200Success
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/public/notifications/unsubscribe" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "string"
}'

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

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

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

Decline rate, reasons and funnel by processor, country or card brand

GET/v1/analytics/declines

Attempts in [from, to) grouped by by. country is the detected billing country: the billing address, else the caller hint. Unknown/in-flight attempts are excluded from the rate (a timeout is never a decline). Groups under the minimum decided attempts are flagged low. Definitions: apps/api/src/modules/analytics/declines.service.ts.

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)))$
storeIdstring · uuid
A store of the merchant; omit for all of the merchant's stores
bystring
Group key
One ofprocessorcountryissuer_countrycard_brandDefault processor
currencystring
Only payments in this currency; default all
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 fieldsDeclineAnalysis

storeIdstringrequirednullable
bystringrequired
One ofprocessorcountryissuer_countrycard_brand
currencystringrequirednullable
fromstringrequired
tostringrequired
minDecidedAttemptsintegerrequired
totalsobjectrequired
Fields: 7 fields
- approvedintegerrequired
- declinedintegerrequired
- excludedintegerrequired
  Unknown or in-flight attempts: never counted as declines.
- declineRateintegerrequirednullable
  Basis points of decided attempts.
- paymentsintegerrequired
- paidintegerrequired
- topReasonsarray<object>required
  Each item has 3 fields
  categorystringrequired
  codestringrequirednullable
  countintegerrequired
groupsarray<object>required
Each item has 10 fields
- keystringrequired
- labelstringrequirednullable
- confidencestringrequired
  One ofoklow
- approvedintegerrequired
- declinedintegerrequired
- excludedintegerrequired
  Unknown or in-flight attempts: never counted as declines.
- declineRateintegerrequirednullable
  Basis points of decided attempts.
- paymentsintegerrequired
- paidintegerrequired
- topReasonsarray<object>required
  Each item has 3 fields
  categorystringrequired
  codestringrequirednullable
  countintegerrequired
funnelobjectrequired
Fields: 2 fields
- sessionsobjectrequired
  Fields: 3 fields
  createdintegerrequired
  withPaymentAttemptintegerrequired
  paidintegerrequired
- paymentsobjectrequired
  Fields: 3 fields
  createdintegerrequired
  attemptedintegerrequired
  paidintegerrequired

Request · cURL

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

{
  "storeId": "string",
  "by": "processor",
  "currency": "USD",
  "from": "string",
  "to": "string",
  "minDecidedAttempts": 1,
  "totals": {
    "approved": 1,
    "declined": 1,
    "excluded": 1,
    "declineRate": 1,
    "payments": 1,
    "paid": 1,
    "topReasons": [
      {
        "category": "string",
        "code": "string",
        "count": 1
      }
    ]
  },
  "groups": [
    {
      "key": "string",
      "label": "string",
      "confidence": "ok",
      "approved": 1,
      "declined": 1,
      "excluded": 1,
      "declineRate": 1,
      "payments": 1,
      "paid": 1,
      "topReasons": [
        {
          "category": "string",
          "code": "string",
          "count": 1
        }
      ]
    }
  ],
  "funnel": {
    "sessions": {
      "created": 1,
      "withPaymentAttempt": 1,
      "paid": 1
    },
    "payments": {
      "created": 1,
      "attempted": 1,
      "paid": 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"
  }
}

Dispute ratio and alerts per card network

GET/v1/analytics/network-risk

Per card network over [from, to) in one currency: approved payments, disputes opened (attributed through the payment), dispute amount (integer minor units), pre-dispute alerts by type and the dispute ratio, with the same figures for the period of equal length before. status appears only for a named network with enough approved payments, judged against the merchant dispute-ratio band.

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 fieldsNetworkRisk

currencystringrequired
3 chars
fromstringrequired
tostringrequired
thresholdobjectrequired
Fields: 4 fields
- warningnumberrequired
  Dispute ratio at which a network is flagged warning.
- criticalnumberrequired
  Dispute ratio at which a network is flagged critical.
- sourcestringrequired
  custom = the merchant row in health_thresholds; default = domain placeholder.
  One ofcustomdefault
- minSampleintegerrequired
  Approved payments needed before a status is shown.
networksarray<object>required
Each item has 9 fields
- networkstringrequired
  One ofvisamastercardamexdiscoverother
- approvedintegerrequired
  Payments with status succeeded created in the window.
- disputesintegerrequired
  Disputes opened in the window, by the payment network.
- disputeAmountintegerrequired
  Sum of those disputes (minor units).
- alertsobjectrequired
  Fields: 5 fields
  ethocaintegerrequired
  cdrnintegerrequired
  rdrintegerrequired
  otherintegerrequired
  totalintegerrequired
- disputeRationumberrequirednullable
  disputes / approved; null if none approved.
  min 0
- statusstring
  Only when a threshold applies and the sample is large enough.
  One ofgoodwarningcritical
- lowSamplebooleanrequired
- previousobjectrequired
  Fields: 5 fields
  approvedintegerrequired
  Payments with status succeeded created in the window.
  disputesintegerrequired
  Disputes opened in the window, by the payment network.
  disputeAmountintegerrequired
  Sum of those disputes (minor units).
  alertsobjectrequired
  Fields: 5 fields
  ethocaintegerrequired
  cdrnintegerrequired
  rdrintegerrequired
  otherintegerrequired
  totalintegerrequired
  disputeRationumberrequirednullable
  min 0
unattributedobjectrequired
Fields: 2 fields
- disputesintegerrequired
- alertsintegerrequired
previousobjectrequired
Fields: 3 fields
- fromstringrequired
- tostringrequired
- unattributedobjectrequired
  Fields: 2 fields
  disputesintegerrequired
  alertsintegerrequired

Request · cURL

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

{
  "currency": "USD",
  "from": "string",
  "to": "string",
  "threshold": {
    "warning": 1,
    "critical": 1,
    "source": "custom",
    "minSample": 1
  },
  "networks": [
    {
      "network": "visa",
      "approved": 1,
      "disputes": 1,
      "disputeAmount": 4999,
      "alerts": {
        "ethoca": 1,
        "cdrn": 1,
        "rdr": 1,
        "other": 1,
        "total": 4999
      },
      "disputeRatio": 1,
      "status": "good",
      "lowSample": false,
      "previous": {
        "approved": 1,
        "disputes": 1,
        "disputeAmount": 4999,
        "alerts": {
          "ethoca": 1,
          "cdrn": 1,
          "rdr": 1,
          "other": 1,
          "total": 4999
        },
        "disputeRatio": 1
      }
    }
  ],
  "unattributed": {
    "disputes": 1,
    "alerts": 1
  },
  "previous": {
    "from": "string",
    "to": "string",
    "unattributed": {
      "disputes": 1,
      "alerts": 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 health alerts

GET/v1/health/alerts

Health alerts (processor degraded, chargeback ratio, caps, pixel delivery and more). Default status is open,acknowledged.

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

Query parameters

statusstring
Comma-separated: open, acknowledged, resolved.

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/health/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"
  }
}

Acknowledge a health alert

POST/v1/health/alerts/{id}/acknowledge

Marks a health alert as seen. It stays until its condition clears.

Authentication: API key (Bearer)
Permission: health: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 POST "$GIEP_API_URL/v1/health/alerts/a510ad46-0bac-40d4-a957-0452637c/acknowledge" \
  -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"
  }
}

Chargeback ratio methods and thresholds (custom rows and defaults)

GET/v1/health/chargeback-settings

Counting method per card network and the amber / red thresholds, step-down margin and minimum volume, for the whole merchant, per store and per processor account, with the GIEP defaults that apply where nothing is set.

Authentication: API key (Bearer)
Permission: health: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/health/chargeback-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 chargeback ratio method and thresholds for the merchant, a store or a processor

PUT/v1/health/chargeback-settings

Sets the counting method per network and the thresholds for one scope (merchant, store or processor account). Thresholds are basis points (amberBps above 0, redBps above amber and at most 10000, hysteresisBps inside the gap); volumeMinChargebacks (default 3) and volumeMinSettled (default 100) are the volume below which no alert is raised. Requires processor:manage. Audited.

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

Request body · application/jsonrequired

scopeobjectrequired
Fields: 2 fields
- typestringrequired
  One ofmerchantstoreprocessor
- idstring · uuidnullable
visaMethodstringrequired
One ofrolling_30dvisa_monthlymastercard_monthly
mastercardMethodstringrequired
One ofrolling_30dvisa_monthlymastercard_monthly
amberBpsintegerrequired
min 0 · max 10000
redBpsintegerrequired
min 0 · max 10000
minChargebacksintegerrequirednullable
min 0 · max 1000000
hysteresisBpsintegerrequired
min 0 · max 10000
volumeMinChargebacksinteger
Default 3min 0 · max 1000000
volumeMinSettledinteger
Default 100min 0 · max 100000000

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/health/chargeback-settings" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scope": {
    "type": "merchant"
  },
  "visaMethod": "rolling_30d",
  "mastercardMethod": "rolling_30d",
  "amberBps": 1,
  "redBps": 1,
  "minChargebacks": 1,
  "hysteresisBps": 1
}'

// 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 chargeback ratio settings (the scope inherits again)

DELETE/v1/health/chargeback-settings/{id}

Removes custom settings for a scope; it inherits the merchant setting, then the GIEP default. Requires processor:manage. Audited.

Authentication: API key (Bearer)
Permission: processor: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/health/chargeback-settings/a510ad46-0bac-40d4-a957-0452637c" \
  -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"
  }
}

Chargeback ratio per card network, per processor / store / merchant, with the configured counting method (rules pending client confirmation)

GET/v1/health/chargebacks

Chargebacks against settled payments per card network, per processor, per store and across all stores, with the counting method of each scope, the amber / red level and whether the volume is too low to alert. A chargeback is a dispute past the inquiry stage, counted once per payment.

Authentication: API key (Bearer)
Permission: health: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/health/chargebacks" \
  -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"
  }
}

Disputes behind the chargeback numbers (reason, stage, due date, amount, network)

GET/v1/health/disputes

The disputes behind a chargeback count over the last days (default 90), filtered by processor account, store or network.

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

Query parameters

processorAccountIdstring · uuid
storeIdstring · uuid
networkstring
One ofvisamastercardother
daysinteger
Default 30min 1 · max 400
limitinteger
Default 100min 1 · max 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.
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/health/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"
  }
}

Check health now (the monitor run for the calling merchant; at most every 10 s)

POST/v1/health/evaluate

Runs the health monitor now for the calling merchant only: opens, escalates or resolves alerts, and pauses a processor only where the merchant opted in to auto-pause for that metric. At most once every 10 seconds per merchant (429 too_soon). Requires processor:manage.

Authentication: API key (Bearer)
Permission: processor:manage
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 POST "$GIEP_API_URL/v1/health/evaluate" \
  -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"
  }
}

Processor health overview

GET/v1/health/processors

Per processor account: health score (0-100), approval rate over 24 hours, 7 days and 30 days, error rate, latency, cap usage and the factors behind the score.

Authentication: API key (Bearer)
Permission: health: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/health/processors" \
  -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"
  }
}

Health of one processor account

GET/v1/health/processors/{id}

One processor account: approval by window, top decline reasons, webhook delay, caps and why the score is what it is.

Authentication: API key (Bearer)
Permission: health: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/health/processors/a510ad46-0bac-40d4-a957-0452637c" \
  -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"
  }
}

Per-store health: approval, soft/hard declines, top codes, chargebacks vs baseline

GET/v1/health/stores

Per store, whichever processor took the payment: approval over 24 hours and 7 days, soft and hard declines against the 7-day baseline, top decline code and chargebacks.

Authentication: API key (Bearer)
Permission: health: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/health/stores" \
  -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 health thresholds

GET/v1/health/thresholds

Processor health thresholds of the merchant (approval drop, error rate, dispute ratio, latency) and whether each may auto-pause. There is no workspace screen for these in this release.

Authentication: API key (Bearer)
Permission: health: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/health/thresholds" \
  -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 or replace a health threshold

PUT/v1/health/thresholds

Creates or replaces a processor health threshold. Requires processor:manage.

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

Request body · application/jsonrequired

metricstringrequired
One ofapproval_rateerror_ratedispute_ratiorefund_ratio
processorAccountIdstring · uuidnullable
warningnumberrequired
min 0 · max 1
criticalnumberrequired
min 0 · max 1
autoPauseboolean
Default false

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/health/thresholds" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "metric": "approval_rate",
  "warning": 1,
  "critical": 1
}'

// 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 health threshold

DELETE/v1/health/thresholds/{id}

Deletes a health threshold; the default applies again. Requires processor:manage.

Authentication: API key (Bearer)
Permission: processor: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/health/thresholds/a510ad46-0bac-40d4-a957-0452637c" \
  -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"
  }
}

Home screen summary

GET/v1/home

The data behind the workspace Home screen: volume today against a usual day, approval rate against the 30-day norm, open alerts and the nearest deadline, checkout conversion, processor health and caps.

Authentication: API key (Bearer)
Permission: health: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/home" \
  -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"
  }
}

Recent health emails (sent, queued, suppressed by the cooldown, failed)

GET/v1/notifications/deliveries

Recent health emails with their status: queued, sending, sent, failed, not sent, or held back by the quiet period. Requires notification:manage.

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

Query parameters

limitinteger
min 1 · max 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.
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/notifications/deliveries" \
  -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"
  }
}

Health email recipients

GET/v1/notifications/recipients

Health email recipients and their state: waiting for confirmation, confirmed, or stopped by the recipient. Requires notification:manage.

Authentication: API key (Bearer)
Permission: notification:manage
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/notifications/recipients" \
  -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 health email recipient (a confirmation link is mailed)

POST/v1/notifications/recipients

Adds a recipient (at most 20) and emails a confirmation link; nothing else is sent until the address confirms. Requires notification:manage.

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

Request body · application/jsonrequired

emailstring · emailrequired
max 254 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/notifications/recipients" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]"
}'

// 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 health email recipient

DELETE/v1/notifications/recipients/{id}

Removes a recipient; the address gets no more health emails. Requires notification:manage.

Authentication: API key (Bearer)
Permission: notification: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/notifications/recipients/a510ad46-0bac-40d4-a957-0452637c" \
  -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"
  }
}

Mail a new confirmation link to a pending recipient

POST/v1/notifications/recipients/{id}/resend

Emails a new confirmation link to a recipient that has not confirmed yet. At most one a minute (too_soon).

Authentication: API key (Bearer)
Permission: notification: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 POST "$GIEP_API_URL/v1/notifications/recipients/a510ad46-0bac-40d4-a957-0452637c/resend" \
  -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"
  }
}

Health email settings

GET/v1/notifications/settings

Which health alert types are emailed, the minimum severity, the quiet period per alert (hours) and the daily digest hour.

Authentication: API key (Bearer)
Permission: health: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/notifications/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 health email types, severity threshold, cooldown and digest

PUT/v1/notifications/settings

Sets the emailed alert types, minimum severity (warning or critical), quiet period (0 to 168 hours) and the daily digest. Requires notification:manage.

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

Request body · application/jsonrequired

enabledTypesarray<string>required
max 5 items
minSeveritystringrequired
One ofwarningcritical
cooldownMinutesintegerrequired
min 0 · max 10080
dailyDigestbooleanrequired
digestHourintegerrequired
min 0 · max 23

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/notifications/settings" \
  -H "Authorization: Bearer $GIEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "enabledTypes": [
    "processor_health"
  ],
  "minSeverity": "warning",
  "cooldownMinutes": 1,
  "dailyDigest": false,
  "digestHour": 1
}'

// 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"
  }
}