Transfer To/From Lockbox Financial Account

Transfer To/From Lockbox Financial Account

This endpoint allows partners to programmatically move funds into or out of a customer's lockbox financial account. The lockbox model restricts the customer from initiating these transfers directly — only the partner or an authorized system can perform them. This enables controlled fund movement for scenarios such as dispute resolution, compliance holds, or conditional fund release.

Endpoint

POST /netevia/lockfinancialAccount/transfer/{profileId}

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when the partner needs to restrict or release customer funds without requiring the customer to initiate the action. Common scenarios include moving funds into the lockbox to enforce a hold (e.g., during a compliance review or dispute), and moving funds out of the lockbox once conditions are satisfied (e.g., after dispute resolution or regulatory clearance). This operation does not require customer confirmation.

Path Parameters

Request Body

{
  "fromFinancialAccountId": "fa_source_account_id_001",
  "toFinancialAccountId": "fa_lockbox_account_id_002",
  "amount": 50000,
  "currencyCode": 840,
  "memo": "Funds held pending dispute resolution"
}

Response

200 OK

A successful 200 response confirms that the transfer was initiated. The response body is not detailed in the schema; treat a 200 status as confirmation of success.

{}

Error Codes

Common Mistakes

• Passing amount in dollars instead of cents — the amount field expects the value in the smallest currency unit (e.g., 50000 for $500.00 USD).
• Using a fromFinancialAccountId or toFinancialAccountId that does not belong to the customer identified by profileId.
• Including invalid characters in the memo field — only word characters (\w), periods (.), and spaces are permitted.
• Assuming the customer can initiate this transfer — only the partner or an authorized system may call this endpoint.
• Omitting currencyCode when the platform may require it — always supply 840 for USD transactions to avoid ambiguity.

Related Endpoints

• POST /netevia/lockfinancialAccount/{profileId} — Create a lockbox financial account for a customer
• GET /netevia/lockfinancialAccount/{profileId} — Retrieve lockbox financial account details for a customer
• POST /netevia/financialAccount/transfer/{profileId} — Transfer funds between standard financial accounts for a customer

Example

curl -X POST https://api.banking.netevia.dev/netevia/lockfinancialAccount/transfer/123456 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fromFinancialAccountId": "fa_source_account_id_001",
    "toFinancialAccountId": "fa_lockbox_account_id_002",
    "amount": 50000,
    "currencyCode": 840,
    "memo": "Funds held pending dispute resolution"
  }'