Skip to main content
View as Markdown

Financial accounts

Use this reference to connect financial accounts, manage their capabilities, and choose where payouts are sent. For an end-to-end setup flow, start with Set up financial accounts.

The financial account object

The response shape varies slightly by operation. Lookup and page return the complete readable state; disconnect and reconnect return a compact account summary. Optional fields are omitted when no value is stored.

Properties​

TypeScript SDK responseFinancialAccountv12.0.0
POST/financial_accounts/connect

Connect a financial account

Register a mobile-money wallet or Ghana bank account for payments and payouts. Dosh accounts can also be registered, but cannot receive payouts. To make a supported account eligible as a payout destination, set pushConfiguration.enabled to true, then map the returned account ID with Set payout destinations.

Validation rules​

Required attributes​

TypeScript SDK requestConnectFinancialAccountRequestv12.0.0

Optional attributes​

TypeScript SDK requestConnectFinancialAccountRequestv12.0.0
  • customDataCustomDataInputClick or tap to expand

    Your metadata object. String values are stored directly; other JSON values are serialized to strings. Keys may be at most 256 characters and the serialized object may be at most 25 KB. See Custom data.

  • Name
    description
    Type
    string
    Description

    Long-form description (up to 200 characters) of how you use this account. Examples: Vendor disbursement wallet, Balance top-up source - owner's MTN, and Customer refund processing. Useful for team context, compliance documentation, and audit trails.

  • pullConfigurationPullPushConfigSet whether pull capability is enabled at connection time. Use Enable pull instead when you need to record authorization context.Click or tap to expand
    • Name
      enabled
      Type
      boolean
      Description
      Set true to create the current mandate.
  • pushConfigurationPullPushConfigSet whether the account is push-enabled at connection time.Click or tap to expand
    • Name
      enabled
      Type
      boolean
      Description
      Set true to enable push capability. Supported wallets and bank accounts can then qualify for payout-destination configuration.

Request

POST/financial_accounts/connect
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.financialAccounts.connect({
  label: "Konadu Tailoring Collections",
  reference: "KONADU-MOMO-SETTLEMENT",
  description: "Primary settlement wallet for Konadu B2C operations.",
  type: Inttegro.FinancialAccountTypes.Wallet,
  currency: "ghs",
  owner: {
    address: {
      city: "Accra",
      country: "Ghana",
      line1: "123 High Street",
      name: "Konadu Tailoring Ltd",
      region: "Greater Accra",
    },
    name: "Konadu Tailoring Ltd",
  },
  wallet: {
    type: Inttegro.wallets.WalletTypes.MobileMoney,
    mobileMoney: {
      network: Inttegro.MobileMoneyNetworks.MTN,
      accountNumber: "0242057831",
    },
  },
  pushConfiguration: {
    enabled: true,
  },
  pullConfiguration: {
    enabled: false,
  },
})

Response

SDK versionv12.0.0
AccountResponse {
  account: { … },
}
POST/financial_accounts/disconnect

Disconnect a financial account

Stop new money movement to a financial account without deleting its history. The account remains available through lookup and page, and the response sets disconnectedAt.

If the account is currently configured as a payout destination for any currency, the request fails unless you either remove it from payout destinations first or set unsetAsPayoutDestination to true. This prevents accidentally breaking automatic payouts.

Disconnecting an already-disconnected account succeeds without changing its original disconnect time.

Request attributes​

TypeScript SDK requestToggleFinancialAccountRequestv12.0.0
  • Name
    accountId
    Type
    string
    Description

    Unique identifier of the account to disconnect. Required.

  • Name
    unsetAsPayoutDestination
    Type
    boolean
    Description

    When true, remove this account from every payout-destination mapping before disconnecting it. Defaults to false.

Request

POST/financial_accounts/disconnect
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.financialAccounts.disconnect({
  accountId: "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
  unsetAsPayoutDestination: true,
})

Response

SDK versionv12.0.0
AccountResponse {
  account: { … },
}
POST/financial_accounts/reconnect

Reconnect a financial account

Restore a disconnected financial account while keeping its account ID and history.

Reconnect only clears the account-level disconnectedAt state. It preserves the same account ID, historical payouts or charges, and any existing push or pull configuration already stored on the record. If you removed this account from payout destinations during disconnect, set those destinations again separately.

Reconnecting an already-connected account succeeds without changing it.

Request attributes​

TypeScript SDK requestReconnectFinancialAccountRequestv12.0.0
  • Name
    accountId
    Type
    string
    Description

    Unique identifier of the account to reconnect. Required.

Request

POST/financial_accounts/reconnect
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.financialAccounts.reconnect({
  accountId: "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
})

Response

SDK versionv12.0.0
AccountResponse {
  account: { … },
}
POST/financial_accounts/create

Create a financial account

Add a financial account from wallet, bank-account, or Dosh account details you already have. This does not open an account with the financial institution. Dosh accounts cannot receive payouts. If you are adding a payout destination, use Connect a financial account.

Request and response​

The request attributes and validation rules match Connect a financial account.

Create responses can additionally include supplied provenance.

Request

POST/financial_accounts/create
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.financialAccounts.create({
  label: "Marketplace Seller Sub-Account",
  reference: "SELLER-001-COLLECTION",
  description: "Dedicated collection account for seller 001.",
  type: Inttegro.FinancialAccountTypes.Wallet,
  currency: "ghs",
  owner: {
    address: {
      city: "Accra",
      country: "Ghana",
      line1: "45 Market Road",
      name: "Marketplace Seller Ltd",
      region: "Greater Accra",
    },
    name: "Marketplace Seller Ltd",
  },
  wallet: {
    type: Inttegro.wallets.WalletTypes.MobileMoney,
    mobileMoney: {
      network: Inttegro.MobileMoneyNetworks.MTN,
      accountNumber: "0244123456",
    },
  },
})

Response

SDK versionv12.0.0
AccountResponse {
  account: { … },
}
POST/financial_accounts/lookup

Lookup a financial account

Retrieve a financial account, including its connection state, capabilities, owner, institution, and type-specific details.

Request attributes​

TypeScript SDK requestLookupFinancialAccountRequestv12.0.0
  • Name
    accountId
    Type
    string
    Description

    Non-empty financial-account ID returned by Connect or Create.

Request

POST/financial_accounts/lookup
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.financialAccounts.lookup({
  accountId: "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
})

Response

SDK versionv12.0.0
AccountResponse {
  account: { … },
}
POST/financial_accounts/update

Update a financial account

Change the label, description, reference, owner, or custom data on a financial account. To change its destination details, connect or create a new account. Use the capability operations below to enable or disable push and pull.

currency, type, and the account-type-specific objects are not accepted by this operation. Create or connect a new financial account when the destination itself changes.

Request attributes​

TypeScript SDK requestUpdateFinancialAccountRequestv12.0.0
  • Name
    accountId
    Type
    string
    Description

    Unique identifier of the account to update. Required.

  • customDataCustomDataPatchClick or tap to expand

    Application-specific metadata. Keys are merged into the existing object; a key sent as null is deleted. Maximum size: 25 KB when serialized.

  • Name
    description
    Type
    string
    Description

    New description. Omit it to keep the current value.

  • Name
    label
    Type
    string
    Description

    New human-readable name. Omit it to keep the current value.

  • ownerBankAccountOwnerClick or tap to expand

    Replacement owner object. Supplying it replaces the complete stored owner; omitted nested values become empty or absent rather than being merged from the previous owner.

  • Name
    reference
    Type
    string
    Description

    New reference. Omit it to keep the current value.

Request

POST/financial_accounts/update
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.financialAccounts.update({
  accountId: "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
  label: "Konadu Tailoring - Primary",
  customData: {
    vendor_id: "VNDR-001",
    region: "Greater Accra",
  },
})

Response

SDK versionv12.0.0
AccountResponse {
  account: { … },
}
POST/financial_accounts/enable_pull

Enable pull capability

Authorize a financial account for payment flows that pull funds from it. This operation records the mandate; it does not move money.

You can optionally send the authorization request's ipAddress and userAgent. Omit either field when it is unavailable; the API does not derive these values automatically for this operation.

If pull is already enabled, the request succeeds and preserves the existing mandate, including its original pullConfiguration.enabledAt.

To replace ipAddress or userAgent, disable pull and enable it again with the new authorization context.

Request attributes​

TypeScript SDK requestToggleFinancialAccountRequestv12.0.0
  • Name
    accountId
    Type
    string
    Description

    Unique identifier of the account to enable pull for. Required.

  • Name
    ipAddress
    Type
    string
    Description

    IP address associated with the authorization, when available.

  • Name
    userAgent
    Type
    string
    Description

    User agent associated with the authorization, when available.

Request

POST/financial_accounts/enable_pull
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.financialAccounts.enablePull({
  accountId: "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
})

Response

SDK versionv12.0.0
AccountResponse {
  account: { … },
}
POST/financial_accounts/disable_pull

Disable pull capability

Revoke the account's current pull mandate. The operation removes pullConfiguration from the account response, including the mandate and its pullConfiguration.enabledAt timestamp. Enabling pull later creates a new mandate, so obtain fresh authorization before doing so.

Disabling pull when it is already disabled succeeds without changing the account.

Request attributes​

TypeScript SDK requestToggleFinancialAccountRequestv12.0.0
  • Name
    accountId
    Type
    string
    Description

    Unique identifier of the account to disable pull for. Required.

Request

POST/financial_accounts/disable_pull
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.financialAccounts.disablePull({
  accountId: "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
})

Response

SDK versionv12.0.0
AccountResponse {
  account: { … },
}
POST/financial_accounts/enable_push

Enable push capability

Enable push capability on a financial account. This adds pushConfiguration; it does not schedule a payout or change destination mappings. A supported wallet or Ghana bank account can then qualify as a payout destination when it is connected and its currency matches the payout. Dosh accounts, disconnected accounts, and archived accounts remain ineligible even when push is enabled.

If push is already enabled, the request succeeds and preserves its original pushConfiguration.enabledAt.

Request attributes​

TypeScript SDK requestToggleFinancialAccountRequestv12.0.0
  • Name
    accountId
    Type
    string
    Description

    Unique identifier of the account to enable push for. Required.

Request

POST/financial_accounts/enable_push
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.financialAccounts.enablePush({
  accountId: "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
})

Response

SDK versionv12.0.0
AccountResponse {
  account: { … },
}
POST/financial_accounts/disable_push

Disable push capability

Remove pushConfiguration so the account can no longer qualify as a payout destination.

If the financial account is configured as a payout destination for any currency, the request fails unless you either remove it from payout destinations first or set unsetAsPayoutDestination to true.

Disabling push when it is already disabled succeeds without changing the account.

Request attributes​

TypeScript SDK requestToggleFinancialAccountRequestv12.0.0
  • Name
    accountId
    Type
    string
    Description

    Unique identifier of the account to disable push for. Required.

  • Name
    unsetAsPayoutDestination
    Type
    boolean
    Description

    When true, remove this account from every payout destination before disabling push. Defaults to false.

Request

POST/financial_accounts/disable_push
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.financialAccounts.disablePush({
  accountId: "fa_Q90wZdd2P7W8hJ1cN9Mx4Rk5sVWBvY3L6pTz8q0",
})

Response

SDK versionv12.0.0
AccountResponse {
  account: { … },
}
POST/financial_accounts/page

Page through financial accounts

Retrieve a numbered page of financial accounts. Results are not guaranteed to be ordered by creation time.

Request attributes​

TypeScript SDK requestPageFinancialAccountsRequestv12.0.0
  • Name
    pageNumber
    Type
    number
    Required
    required
    Description

    1-based page index to fetch. Must be between 1 and 10 inclusive.

  • Name
    pageSize
    Type
    number
    Description

    Requested number of accounts, between 1 and 256. Defaults to 256.

    Response size is the number of accounts actually returned, not the requested size.

Response shape​

Request

POST/financial_accounts/page
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.financialAccounts.page({
  pageNumber: 1,
  pageSize: 50,
})

Response

SDK versionv12.0.0
PageResponse {
  page: { … },
}
POST/financial_accounts/search

Search financial accounts

Find financial accounts from remembered text or exact account attributes. Results are discovery summaries; use the returned account ID with Lookup a financial account before choosing a payout destination or changing account capabilities.

Request attributes​

TypeScript SDK requestResourceSearchRequestv12.0.0
  • Name
    cursor
    Type
    string
    Description

    Opaque continuation cursor returned by the previous page. Replay the same request and add this value for the next page.

  • facetsResourceSearchFacet[]Fields to group and count: currency, status, or type.Click or tap to expand
    • Name
      field
      Type
      string
      Required
      required
      Description
      Route-local facet field.
    • Name
      limit
      Type
      number
      Description
      Maximum buckets, from 1 through 50. Defaults to 10.
  • filtersResourceSearchFilter[]Exact constraints on currency, status, or type.Click or tap to expand
    • Name
      field
      Type
      string
      Required
      required
      Description
      Route-local filter field.
    • Name
      operator
      Type
      ResourceSearchOperator
      Required
      required
      Description
      eq for one value or in for any supplied value.
    • Name
      values
      Type
      string[]
      Required
      required
      Description
      One value for eq; one through 20 values for in.
  • Name
    pageSize
    Type
    number
    Description

    Results per page, from 1 through 100. Defaults to 20.

  • sortResourceSearchSortResult ordering.Click or tap to expand
  • Name
    text
    Type
    string
    Description

    Search text, from 1 through 512 characters. Supply search text, exact filters, or both.

Response​

Returns a typed search page with discovery summaries, requested facet counts, page and total counts, an optional nextCursor, and freshness metadata. Search never replaces a canonical account lookup.

Request

POST/financial_accounts/search
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})

const request: Inttegro.ResourceSearchRequest = {
  text: "primary mobile money",
}
const page = await inttegro.financialAccounts.search(request)

Response excerpt

SDK versionv12.0.0
SearchResponse {
  search: { … },
}