> ## Documentation Index > Fetch the complete documentation index at: https://docs.methodfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Balance Transfer > Let borrowers allocate an approved loan across their liability accounts, then release the payoff payments from your backend. export const ParamList = ({items = [], is_child = false}) => { return items.map(item => { const field_props = { id: Math.random().toString(), body: item.name, name: item.name, type: item.type, required: item.required }; const enums = item.enums || []; const items = item.items || []; const has_items = items?.length > 0; const has_enums = enums?.length > 0; const should_default_open = item.defaultOpen || false; const render_child_item = () => { const child_props = { title: has_enums ? "Possible enum values" : "properties" }; if (should_default_open) child_props.defaultOpen = true; const has_inline_enums = has_enums && enums.every(enum_item => typeof enum_item === 'string') && enums.map((enum_item, idx) => { const is_last = idx === enums.length - 1; const is_2nd_to_last = idx === enums.length - 2; return <> {enum_item} {is_last && ''} {is_2nd_to_last && ' or '} {!is_last && !is_2nd_to_last && ', '} ; }); const enum_list = has_enums && !has_inline_enums && {enums.map((enum_item, index) =>
{enum_item.name}

{enum_item.description}

)} ; const item_list = has_items && ; return <>

{item.description} {has_inline_enums && [has_inline_enums.length > 1 ? ' One of ' : ' Must be ', ...has_inline_enums]}

{enum_list} {item_list} ; }; return is_child ? {render_child_item()} : {render_child_item()}; }); }; Mode: `balance_transfer` Opal Balance Transfer lets a borrower direct the proceeds of an approved loan to the liability accounts they want to pay down. This pre-built flow verifies the user's identity, connects their liability accounts, collects any account numbers needed to make those accounts payable, and asks the user how much of the loan to send to each account. When the user confirms, your backend releases the payments. ## What this mode does Use this mode after your team has approved a loan, such as a debt consolidation or balance transfer loan, and knows the approved amount. You pass the approved loan terms when you create the token, and Opal guides the user through the following steps: Opal verifies the user's identity. This step is skipped automatically if the Entity is already verified. Opal shows the user's liability accounts with their current balances. Only accounts that can receive a payment today, or that can become payable once the user provides the account number, are selectable. For each selected account that cannot receive payments yet, the user enters the account number. Accounts that are already payable skip this step. Accounts that still cannot receive payments after verification are removed from the allocation step. Opal prefills an amount for each account, starting with the highest balances, and shows how much of the loan remains to allocate. The user can edit or remove any amount, then confirms. Confirming does not move money. The session waits in `pending_release` until your backend calls [Release Payments](/reference/opal/release_payments). Method then creates one payment per allocated account. ```mermaid theme={null} sequenceDiagram participant App as Your backend participant Method as Method API participant Opal as Opal (end user) App->>Method: POST /opal/token (mode: balance_transfer) Method-->>App: token, session_id App->>Opal: Launch Opal with the token Opal->>Method: Verify identity, select and verify accounts Opal->>Method: Allocate amounts and confirm Opal-->>App: balance_transfer.amounts.confirmed event App->>Method: GET /opal/sessions/{session_id} Method-->>App: bt.payout_status: pending_release App->>Method: POST /opal/sessions/{session_id} (release_payments) Method-->>App: bt.payout_status: released, bt.payment_ids ``` ## Before you start * **Enable the mode.** Balance Transfer must be enabled for your team. Until it is, token creation with `mode: "balance_transfer"` fails with `INVALID_MODE`. Contact your CSM to enable access to this mode. * **Choose a source account.** Payments are funded from a source account that your team can send payments from. Pass it when you release payments, or ask your CSM to configure a default source account for your team. * **Confirm the payment description.** Released payments use a description configured for your team. Contact your CSM to set or change it. ## Parameters All monetary values are in cents. Whether the user can select a single account, multiple accounts, or all eligible accounts. Defaults to multiple. ), enums: ["single", "multiple", "all"], }, { name: "account_filters", type: "object", required: false, description: "Filters to explicitly include or exclude accounts during selection. These work the same way as in Connect mode.", items: [ { name: "account_filters.include", type: "object", required: false, description: "Accounts to explicitly include.", items: [ { name: "account_filters.include.account_types", type: "string[]", required: false, description: "Only surface these liability types for selection.", enums: [ { name: "credit_card" }, { name: "auto_loan" }, { name: "mortgage" }, { name: "student_loan" }, { name: "personal_loan" }, ], }, { name: "account_filters.include.products", type: "string[]", required: false, description: "Only surface accounts that support these products.", enums: [ { name: "balance" }, { name: "sensitive" }, { name: "payoff" }, { name: "update" }, { name: "payment" }, ], }, ], }, { name: "account_filters.exclude", type: "object", required: false, description: "Accounts to mark as ineligible.", items: [ { name: "account_filters.exclude.account_types", type: "string[]", required: false, description: "Mark specific liability types as ineligible.", enums: [ { name: "credit_card" }, { name: "auto_loan" }, { name: "mortgage" }, { name: "student_loan" }, { name: "personal_loan" }, ], }, { name: "account_filters.exclude.mch_ids", type: "string[]", required: false, description: "Mark accounts tied to the provided merchant IDs as ineligible.", }, { name: "account_filters.exclude.unverified_account_numbers", type: "boolean", required: false, description: "Mark accounts with unverified account numbers as ineligible.", }, ], }, ], }, { name: "skip_pii", type: "string[]", required: false, description: "The PII to skip during identity verification.", enums: ["name", "dob", "address", "ssn_4"], }, ]} /> ## Allocation rules Method validates every amount the user enters. Each allocation must be: * At least `minimum_payment`. * No more than the smallest of `maximum_payment`, the account's current balance, and the portion of `loan_amount` not yet allocated to other accounts. When the user confirms, Method also checks that: * At least one account has an allocation. * The total allocated does not exceed `loan_amount`. * If `residual_amount_max` is set, the unallocated amount (`loan_amount` minus the total allocated) does not exceed `residual_amount_max`. * Every allocated account can still receive a payment. Opal enforces the same rules in its interface, so the user cannot confirm until every rule is met. Any unallocated amount stays with your team, and Opal tells the user that your team handles it. Choose `residual_amount_max` based on how you plan to disburse leftover funds. Use `0` if the full loan must go to the user's liability accounts. Omit it if you disburse any remainder to the borrower another way, such as a deposit to their bank account. ## Create a token You can create a balance transfer token using one of the supported patterns: * Existing entity: provide `entity_id` + `mode` + `balance_transfer` * Create new entity: provide `entity` + `mode` + `balance_transfer` * Resume session: provide `session_id` only (omit `mode` and `balance_transfer`) ### Existing Entity ```json theme={null} { "entity_id": "ent_...", "mode": "balance_transfer", "balance_transfer": { "loan_amount": 1000000, "minimum_payment": 5000, "maximum_payment": 500000, "residual_amount_max": 0, "account_filters": { "include": { "account_types": ["credit_card"] } } } } ``` ### Create New Entity ```json theme={null} { "entity": { "type": "individual", "individual": {} }, "mode": "balance_transfer", "balance_transfer": { "loan_amount": 1000000, "minimum_payment": 0, "maximum_payment": 1000000 } } ``` ### Response ```json theme={null} { "token": "otkn_...", "valid_until": "2026-09-23T22:50:53.024Z", "session_id": "osess_..." } ``` Store the `session_id`. You need it to check the session status and release payments. ## Launch Opal ```tsx theme={null} import { OpalProvider, useOpal } from "@methodfi/opal-react"; function Screen() { const { open } = useOpal({ env: "dev", onEvent: (e) => { if (e.type === "balance_transfer.amounts.confirmed") { notifyBackend(e.data); } }, onExit: (e) => {}, }); const start = async () => { const { token } = await getTokenFromBackend(); open({ token }); }; return ; } ``` ```tsx theme={null} import { OpalProvider, useOpal } from "@methodfi/opal-react-native"; function Screen() { const { open } = useOpal({ env: "dev", onEvent: (e) => { if (e.type === "balance_transfer.amounts.confirmed") { notifyBackend(e.data); } }, onExit: (e) => {}, }); const start = async () => { const { token } = await getTokenFromBackend(); open({ token }); }; return