Create Scheduled Transfer

This endpoint creates a new scheduled transfer between two financial accounts. Transfers can be configured as one-time or recurring, with flexible frequency settings and optional end dates. A one-time passcode (OTP) is required to authorize the operation securely.

Endpoint

POST /api/scheduledTransfer

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 a customer wants to schedule a future or recurring transfer between financial accounts — for example, setting up a weekly transfer from a checking account to a savings account, or scheduling a one-time future payment. Both business and personal customers can use scheduled transfers between their own accounts; business customers may additionally schedule internal transfers to other Netevia users.

Request Body

The request body accepts one of two variants:

Variant 1 — Create a new scheduled transfer (createScheduledTransferSecuredRequest)

Variant 2 — Update an existing scheduled transfer (updateScheduledTransferSecuredRequest)

Includes all fields from Variant 1, plus:

{
  "fromFinancialAccountId": "acct-source-001",
  "toFinancialAccountId": "acct-destination-002",
  "amount": 50000,
  "currencyCode": 840,
  "oneTimeCode": "482910",
  "secureOperationType": "ShortMessageCode",
  "name": "Weekly Savings Transfer",
  "memo": "Regular weekly savings",
  "frequency": "1w",
  "isActive": true,
  "nextDate": "2026-06-15T09:00:00Z",
  "endDate": "2026-12-31T23:59:59Z",
  "transferType": "TransferBetweenOwnAccounts"
}

Response

200 OK

{
  "id": 1042,
  "name": "Weekly Savings Transfer",
  "fromFinancialAccountId": "acct-source-001",
  "toFinancialAccountId": "acct-destination-002",
  "isActive": true,
  "transferType": "TransferBetweenOwnAccounts",
  "amount": 50000,
  "currencyCode": 840,
  "frequency": "1w",
  "lastDate": null,
  "nextDate": "2026-06-15T09:00:00Z",
  "endDate": "2026-12-31T23:59:59Z",
  "memo": "Regular weekly savings",
  "minAmount": null,
  "isRejected": false
}

Error Codes

Common Mistakes

• Setting nextDate to a past date or time — the scheduled date must be in the future.
• Providing an invalid frequency pattern — use the format {number}{unit} where unit is y (year), m (month), w (week), or d (day), e.g., 2w for every 2 weeks.
• Omitting oneTimeCode or secureOperationType — both are required for security authorization regardless of transfer type.
• Passing amount as a decimal (e.g., 500.00) instead of an integer in cents (e.g., 50000 for $500.00).
• Using oneTimeCode that has already expired or was previously used — request a fresh OTP before submitting.
• Attempting to update a scheduled transfer using Variant 1 (create) without including the id field — use Variant 2 when updating an existing record.

Related Endpoints

• GET /api/scheduledTransfer — Retrieve a list of all scheduled transfers for the authenticated customer
• GET /api/scheduledTransfer/{id} — Retrieve details of a specific scheduled transfer by ID
• DELETE /api/scheduledTransfer/{id} — Cancel and delete a scheduled transfer
• POST /api/transfer — Execute an immediate (non-scheduled) transfer
• POST /api/batchTransfer — Submit a batch of transfers in a single request

Example

curl -X POST https://api.banking.netevia.dev/api/scheduledTransfer \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fromFinancialAccountId": "acct-source-001",
    "toFinancialAccountId": "acct-destination-002",
    "amount": 50000,
    "currencyCode": 840,
    "oneTimeCode": "482910",
    "secureOperationType": "ShortMessageCode",
    "name": "Weekly Savings Transfer",
    "memo": "Regular weekly savings",
    "frequency": "1w",
    "isActive": true,
    "nextDate": "2026-06-15T09:00:00Z",
    "endDate": "2026-12-31T23:59:59Z",
    "transferType": "TransferBetweenOwnAccounts"
  }'