LimitRail - external integrator playbook

This playbook explains how an external system integrates LimitRail to evaluate pricing, limits, customer thresholds and runtime usage. LimitRail does not open accounts, execute payments, own the ledger or calculate accounting balances. The calling system executes the financial operation; LimitRail returns the policy decision.

1. Core concept

The integration revolves around three references.

externalOperationRef does not decide policy. It only correlates the LimitRail decision with the external event.

2. Authentication and scopes

Use OAuth client credentials. The client gets a bearer token with POST /connect/token, then calls v1 APIs.

3. Initial integrator setup

Before runtime requests, the integrator reads catalog data.

1. GET /v1/products?take=25 Returns productId, productCode, status and currency. productId is the value currently required by account registration; productCode is the business code to align in the calling system.

2. GET /v1/operations?take=25 Returns accepted operation codes. The code field is the value sent as operationCode.

3. GET /v1/policy-dimensions Returns data that can influence rules and counters. Dimensions with source REQUEST_METADATA go in runtime metadata; dimensions with source ACCOUNT_ATTRIBUTE are stored on the account.

4. Account lifecycle

When an account enters the LimitRail scope, register the contract:

POST /v1/account-contracts

{
  "externalAccountRef": "ACC_7F3A92_001",
  "productId": "7b2d8b9f-1a4c-4f3b-9c10-35e4b7a98c21",
  "segmentCode": null,
  "openedAtUtc": "2026-07-05T10:00:00Z",
  "attributes": {
    "customer_tier": "STANDARD",
    "residency_country": "ITA"
  }
}

The integrator does not send the condition plan version. LimitRail resolves it from product, segment or account-level assignment. Account deals and policy overrides are backoffice functions, not public onboarding fields.

When product, segment, lifecycle status or operational block changes, update the contract:

PUT /v1/account-contracts/{id}

If status = BLOCKED, also send blockType and blockReasonCode. If status = CLOSED, runtime evaluations are blocked and the contract is not reopened.

5. Account attributes

Account attributes are stable facts reused by rules without sending them in every request. Examples: customer_tier, residency_country, regulatory_status.

PUT /v1/account-contracts/{id}/attributes

{
  "code": "customer_tier",
  "value": "PREMIUM"
}

LimitRail accepts only active attributes registered as ACCOUNT_ATTRIBUTE and compatible with allowed values when configured.

6. Customer-selected thresholds

Some limits can be configurable by the end customer. The customer may only reduce the threshold within product boundaries; it cannot increase it above the product maximum.

Read available thresholds:

GET /v1/accounts/{externalAccountRef}/limit-settings

Set a threshold:

PUT /v1/accounts/{externalAccountRef}/limit-settings/{limitRuleCode}

{
  "limitAmount": 200.00,
  "source": "CUSTOMER",
  "reason": "Customer-selected ATM daily amount limit"
}

For count limits, use limitCount. When the customer threshold is active, the runtime response shows thresholdSource = CUSTOMER_SETTING.

Customer thresholds are not exceptions. An exception temporarily authorizes a bypass; a customer threshold makes the account stricter.

7. Runtime evaluation

The main call is:

POST /v1/policy/evaluate

{
  "externalAccountRef": "ACC_7F3A92_001",
  "operationCode": "ATM_WITHDRAWAL",
  "amount": 120.00,
  "currencyCode": "EUR",
  "externalOperationRef": "OP_20260705_00001",
  "occurredAtUtc": "2026-07-05T10:05:00Z",
  "metadata": {
    "terminal_country": "ITA"
  },
  "mode": "PREVIEW",
  "idempotencyKey": null
}

metadata must contain facts only. Correct examples: destination_country, terminal_country, resulting_balance_after_operation, average_monthly_balance. Avoid: high_amount, discounted_fee, domestic_fee, limit_exceeded.

Runtime modes

If the decision is DENIED_BY_POLICY, the calling system must not proceed. If it is ALLOWED, WARNING or FEE_CALCULATED, the caller continues according to its own operational process.

8. Reserve, commit, cancel and reverse

For asynchronous flows, use two phases.

1. POST /v1/policy/evaluate with mode = RESERVE_CAPACITY. If policy allows the operation, LimitRail returns capacityReservationId.

2. When the external operation is confirmed:

POST /v1/usage/commit

{
  "capacityReservationId": "2b7e4f0c-6f2a-4d34-a76e-9d91f9a53112",
  "idempotencyKey": "COMMIT_OP_20260705_00001",
  "externalAccountRef": "ACC_7F3A92_001",
  "operationCode": "ATM_WITHDRAWAL",
  "amount": 120.00,
  "currencyCode": "EUR",
  "externalOperationRef": "OP_20260705_00001",
  "occurredAtUtc": "2026-07-05T10:05:00Z",
  "metadata": {
    "terminal_country": "ITA"
  }
}

3. If the operation is abandoned before commit:

POST /v1/capacity-reservations/{id}/cancel

4. If already-applied usage must be compensated:

POST /v1/usage/{id}/reverse

with reversalIdempotencyKey.

The same idempotency key with the same payload must return the same outcome. The same key with a different payload is an integration error.

9. Reading the evaluate response

10. Useful reads

Operational lists are paginated and must use time windows. Do not use them as bulk exports.

11. Enums the integrator must know

Use UPPER_SNAKE_CASE values.

Pricing and limit configuration enums belong to the configuration manual, not to the standard integrator payload.

12. Integration checklist

• Get a token with OAuth client credentials.
• Read products, operations and policy inputs before runtime.
• Register each account with an opaque reference.
• Update account status, block, segment and product when they change.
• Store only stable facts as account attributes.
• Send only current-operation facts in metadata.
• Use direct operationCode.
• Do not send externalSystemCode or externalOperationCode.
• Do not send conditionPlanVersionId.
• Use idempotency key for every call that writes state.
• Read decision, fees, rule results and limit impacts before proceeding.