Operating policies

An operating policy is the concrete configuration applied to a child app: payment currencies and limits, payout behavior, and payment-method settings. Every selected value must fit within the governing parent's children policy, which defines the choices that parent is allowed to grant.

Note

This feature is available to selected accounts during private beta.

Reusable policies and app snapshots

A parent can apply operating settings in two ways:

Create a named, reusable operating policy, then select it by op_ ID when creating or updating a child app.
Send concrete capabilities inline when creating or updating a child app.

Both forms produce an immutable operating-policy snapshot on the child. A snapshot created from a reusable policy records the selected policy ID and version; later versions of that reusable policy do not silently change existing children. Reapply a policy through Update an app when the child's configuration should change.

Reusable operating policies use immutable versions. The policy id stays stable, while each successful update creates and activates a new version. Lookup returns the latest active version by default or a requested version by number. The page endpoint returns the complete history newest first.

The operating policy object

Properties

TypeScript SDK responseOperatingPolicyv14.1.1

Name
activeVersion
Type
number
Description
Latest active version of this reusable policy.
capabilitiesOperatingPolicyCapabilitiesClick or tap to expand
Concrete payment, payout, and payment-method configuration selected by this version.
Name
childrenPolicyId
Type
string
Description
Children policy against which this version was validated.
Name
childrenPolicyVersion
Type
number
Description
Exact children-policy version against which this version was validated.
Name
createdAt
Type
Date
Description
When version one of the reusable policy was created.
Name
description
Type
string
Description
Optional explanation of the account configuration represented by the policy.
Name
id
Type
string
Description
Stable reusable-policy identifier beginning with op_.
Name
name
Type
string
Description
Human-readable policy name.
Name
updatedAt
Type
Date
Description
When the active version last changed.
Name
version
Type
number
Description
Immutable version represented by this object.
Name
versionCreatedAt
Type
Date
Description
When this exact immutable version was created.

Capability properties

TypeScript SDK responseOperatingPolicyv14.1.1

paymentMethodsOperatingPolicyPaymentMethodsCapabilitiesClick or tap to expand
Optional concrete settings for capabilities.paymentMethods.bankAccount, capabilities.paymentMethods.card, capabilities.paymentMethods.mobileMoney, and capabilities.paymentMethods.motito. Each included method has boolean
capabilities.paymentMethods.bankAccount.confirmsUse
and capabilities.paymentMethods.bankAccount.enabled values.
paymentsOperatingPolicyPaymentsCapabilitiesClick or tap to expand
Optional payment configuration. capabilities.payments.currencies contains unique lowercase three-letter currency codes. capabilities.payments.limits.amount.max and capabilities.payments.limits.amount.min are inclusive amounts in minor currency units.
payoutsOperatingPolicyPayoutsCapabilitiesClick or tap to expand
Optional payout configuration. capabilities.payouts.enabled is a concrete boolean, capabilities.payouts.limits.amount is an inclusive minor-unit range, and capabilities.payouts.btAgingSpec is a platform-owned aging configuration.

Select a policy for an app

The operating_policy request attribute is accepted by both Create an app and Update an app. Send exactly one selection form.

To reuse a named policy, send its ID:

Reusable policy selection
{
  "operating_policy": {
    "id": "op_36xByFj7Qf6gdaYxjPE6pSTpSkgJqC6a6f9rR5cL"
  }
}

The reusable policy must belong to the parent that governs the child. During app creation, that is the resolved placement parent. During an existing child-app update, it is the child's direct placement parent. Inttegro resolves the policy's latest active version and validates it again against that parent's latest active children policy before saving the child snapshot.

To configure the child directly, send inline capabilities:

Inline policy selection
{
  "operating_policy": {
    "capabilities": {
      "payment_methods": {
        "card": {
          "confirms_use": true,
          "enabled": true
        },
        "mobile_money": {
          "confirms_use": true,
          "enabled": true
        }
      },
      "payments": {
        "currencies": ["ghs", "usd"],
        "limits": {
          "amount": {
            "max": 9999999,
            "min": 1
          }
        }
      },
      "payouts": {
        "bt_aging_spec": {
          "id": "bt_aging_spec_168_hourly"
        },
        "enabled": false,
        "limits": {
          "amount": {
            "max": 9999999,
            "min": 25000
          }
        }
      }
    }
  }
}

For inline input, payouts.bt_aging_spec accepts only id; Inttegro resolves the platform-owned t_plus value. Inline capabilities must fit the same governing parent children policy as a reusable selection.

When operating_policy is omitted, Inttegro derives a usable restrictive configuration from the governing children policy: payments keep its permitted currencies and limits; payment methods prefer enabled settings with confirmation; and payouts prefer disabled settings with the longest permitted aging period. If a preferred boolean is not permitted, Inttegro uses an allowed value.

Snapshot returned on app responses

App responses expose operating_policy directly on app. The snapshot contains only the resolved capabilities and their source. It does not expose children_policy_id or children_policy_version.

Template-backed app response excerpt

Object
JSON

SDK versionv14.1.1

AppResponse {
  app: { … },
}

SDK versionv14.1.1

{
  "app": {
    "id": "app_2LBJqPrTzbXW9E7lFZgMhFtfoytCxewNwXqoUAXe",
    "operating_policy": { … }
  }
}

For inline or derived configurations, source.type is inline and source.id and source.version are omitted. For reusable selections, source.type is template and the source includes the exact selected id and version.

POST/operating_policies/create

Create an operating policy

Creates version one of a reusable operating policy. The concrete capabilities must fit the app's latest active children policy.

Request body

TypeScript SDK responsev14.1.1

capabilitiesRecord<string, unknown>requiredClick or tap to expand
Concrete capabilities selected within the active children-policy authority. At least one capability group is required.
Name
description
Type
string
Description
Optional description, up to 500 characters.
Name
name
Type
string
Required
required
Description
Policy name, from 1 to 100 characters.

Response

Returns the created version in operating_policy.

Request

POST/operating_policies/create

SDK versionv14.1.1

import { InttegroClient } from '@inttegro/inttegro-sdk'

const apiKey = process.env.INTTEGRO_API_KEY
if (!apiKey) throw new Error('INTTEGRO_API_KEY is required')

const inttegro = new InttegroClient({ apiKey })
const operatingPolicy = await inttegro.operatingPolicies.create({
  capabilities: {
    payments: { currencies: ['ghs', 'usd'] },
    payouts: {
      btAgingSpec: { id: 'bt_aging_spec_168_hourly' },
      enabled: false,
    },
  },
  description: 'Configuration for standard merchant accounts.',
  name: 'Standard merchant',
})

Response

Object
JSON

SDK versionv14.1.1

OperatingPolicyResponse {
  operatingPolicy: { … },
}

SDK versionv14.1.1

{
  "operating_policy": {
    "active_version": 1,
    "capabilities": { … },
    "children_policy_id": "cp_36vCQl1XPkXvtFGbK5KZ4dZF4lvwURGFoCCqhUcp",
    "children_policy_version": 3,
    "created_at": "2026-11-05T10:00:00Z",
    "description": "Configuration for standard merchant accounts.",
    "id": "op_36xByFj7Qf6gdaYxjPE6pSTpSkgJqC6a6f9rR5cL",
    "name": "Standard merchant",
    "updated_at": "2026-11-05T10:00:00Z",
    "version": 1,
    "version_created_at": "2026-11-05T10:00:00Z"
  }
}

Errors

400 Bad Request — The request is malformed or contains unsupported attributes.
401 Unauthorized — Authentication is missing or invalid.
403 Forbidden — This feature is not available to the account.
409 Conflict — The governing children policy changed before creation completed. Read the active children policy and retry deliberately.
422 Unprocessable Entity — The requested capabilities are invalid or exceed the active children-policy authority.
503 Service Unavailable — Policy validation or storage is temporarily unavailable. Retry with backoff.

POST/operating_policies/lookup

Look up an operating policy

Returns one version of the specified reusable operating policy. Omit version to return the latest active version.

Request body

TypeScript SDK responsev14.1.1

Name
operatingPolicyId
Type
string
Required
required
Description
Reusable policy ID beginning with op_.
Name
version
Type
number
Description
Immutable version to return. Must be at least 1. Omit it to return the latest active version.

Response

Returns the requested version in operating_policy.

Request

POST/operating_policies/lookup

SDK versionv14.1.1

import { InttegroClient } from '@inttegro/inttegro-sdk'

const apiKey = process.env.INTTEGRO_API_KEY
if (!apiKey) throw new Error('INTTEGRO_API_KEY is required')

const inttegro = new InttegroClient({ apiKey })
const operatingPolicy = await inttegro.operatingPolicies.lookup({
  operatingPolicyId: 'op_36xByFj7Qf6gdaYxjPE6pSTpSkgJqC6a6f9rR5cL',
  version: 2,
})

Response

Object
JSON

SDK versionv14.1.1

OperatingPolicyResponse {
  operatingPolicy: { … },
}

SDK versionv14.1.1

{
  "operating_policy": {
    "active_version": 3,
    "capabilities": { … },
    "children_policy_id": "cp_36vCQl1XPkXvtFGbK5KZ4dZF4lvwURGFoCCqhUcp",
    "children_policy_version": 3,
    "created_at": "2026-11-05T10:00:00Z",
    "description": "Configuration for standard merchant accounts.",
    "id": "op_36xByFj7Qf6gdaYxjPE6pSTpSkgJqC6a6f9rR5cL",
    "name": "Standard merchant",
    "updated_at": "2026-11-12T15:00:00Z",
    "version": 2,
    "version_created_at": "2026-11-08T09:30:00Z"
  }
}

Errors

400 Bad Request — The policy ID is malformed, or version is less than 1.
401 Unauthorized — Authentication is missing or invalid.
403 Forbidden — This feature is not available to the account.
404 Not Found — No policy exists with that ID and version.
422 Unprocessable Entity — The policy cannot be returned safely.
503 Service Unavailable — Policy storage is temporarily unavailable. Retry with backoff.

POST/operating_policies/page

Page operating policy versions

Returns the immutable versions of one operating policy newest first.

Request body

TypeScript SDK responsev14.1.1

Name
number
Type
number
Description
1-based page number. Defaults to 1.
Name
operatingPolicyId
Type
string
Required
required
Description
Reusable policy ID beginning with op_.
Name
size
Type
number
Description
Number of versions per page. Defaults to 20 and cannot exceed 100.

Response

The response contains pagination metadata and complete operating policy objects in page.

TypeScript SDK responsev14.1.1

Name
count
Type
number
Description
Number of versions returned on this page.
Name
hasMore
Type
boolean
Description
Whether another page of older versions is available.
Name
number
Type
number
Description
Current 1-based page number.
Name
size
Type
number
Description
Requested page size.
Name
total
Type
number
Description
Total number of immutable versions.
Name
versions
Type
unknown[]
Description
Full operating policy objects, ordered newest first.

Request

POST/operating_policies/page

SDK versionv14.1.1

import { InttegroClient } from '@inttegro/inttegro-sdk'

const apiKey = process.env.INTTEGRO_API_KEY
if (!apiKey) throw new Error('INTTEGRO_API_KEY is required')

const inttegro = new InttegroClient({ apiKey })
const page = await inttegro.operatingPolicies.page({
  number: 1,
  operatingPolicyId: 'op_36xByFj7Qf6gdaYxjPE6pSTpSkgJqC6a6f9rR5cL',
  size: 2,
})

Response

Object
JSON

SDK versionv14.1.1

PageResponse {
  page: { … },
}

SDK versionv14.1.1

{
  "page": {
    "count": 2,
    "has_more": true,
    "number": 1,
    "size": 2,
    "total": 3,
    "versions": [ … ]
  }
}

Errors

400 Bad Request — The policy ID is malformed, number is less than 1, or size is outside 1–100.
401 Unauthorized — Authentication is missing or invalid.
403 Forbidden — This feature is not available to the account.
404 Not Found — No operating policy exists with that ID.
422 Unprocessable Entity — The versions cannot be returned for this operation.
503 Service Unavailable — Policy storage is temporarily unavailable. Retry with backoff.

POST/operating_policies/update

Create a new operating policy version

Creates and activates a new immutable version. Send the active version you read as expected_version; Inttegro rejects stale writes instead of overwriting a concurrent update. Include at least one of capabilities, description, or name.

Request body

TypeScript SDK responsev14.1.1

capabilitiesRecord<string, unknown>Click or tap to expand
Replacement concrete capabilities. They are validated against the latest active children policy.
Name
description
Type
string
Description
Replacement description, up to 500 characters.
Name
expectedVersion
Type
number
Required
required
Description
Active version returned by the previous lookup. Must be at least 1.
Name
name
Type
string
Description
Replacement name, from 1 to 100 characters.
Name
operatingPolicyId
Type
string
Required
required
Description
Reusable policy ID beginning with op_.

Response

Returns the new active version in operating_policy. Use Page operating policy versions to retrieve previous versions.

Request

POST/operating_policies/update

SDK versionv14.1.1

import { InttegroClient } from '@inttegro/inttegro-sdk'

const apiKey = process.env.INTTEGRO_API_KEY
if (!apiKey) throw new Error('INTTEGRO_API_KEY is required')

const inttegro = new InttegroClient({ apiKey })
const operatingPolicy = await inttegro.operatingPolicies.update({
  expectedVersion: 1,
  name: 'Standard merchant v2',
  operatingPolicyId: 'op_36xByFj7Qf6gdaYxjPE6pSTpSkgJqC6a6f9rR5cL',
})

Errors

400 Bad Request — The request is malformed, does not include a change, or contains unsupported attributes.
401 Unauthorized — Authentication is missing or invalid.
403 Forbidden — This feature is not available to the account.
404 Not Found — No active policy exists with that ID.
409 Conflict — expected_version is stale, or the governing children policy changed during validation. Look up both active policies, review the intended change, and retry with the current version.
422 Unprocessable Entity — The new version is invalid or exceeds the active children-policy authority.
503 Service Unavailable — Policy validation or storage is temporarily unavailable. Retry with backoff.

Look up a children policy version — Inspect the authority that constrains operating settings.
Create an app — Apply a reusable or inline operating policy to a new child.
Lookup an app — Read the immutable operating-policy snapshot.
Update an app — Replace an existing child's operating-policy snapshot.

Reusable policies and app snapshots

The operating policy object

Properties​

Capability properties​

Select a policy for an app

Snapshot returned on app responses​

Template-backed app response excerpt

Create an operating policy

Request body​

Response​

Request

Response

Errors​

Look up an operating policy

Request body​

Response​

Request

Response

Errors​

Page operating policy versions

Request body​

Response​

Request

Response

Errors​

Create a new operating policy version

Request body​

Response​

Request

Errors​

Related resources

Properties

Capability properties

Snapshot returned on app responses

Request body

Response

Errors

Request body

Response

Errors

Request body

Response

Errors

Request body

Response

Errors