ClearBank.Payments.InternalTransfer (ClearBank v1.0.0)

Internal Transfers — move funds between accounts held at ClearBank without going through an external payment scheme.

Key facts

No scheme fees — transfers are between ClearBank-held accounts
Not subject to APP scam reimbursement — unlike FPS scheme routing
Instant — settlement is immediate within ClearBank's ledger
No upper limit — unlike FPS (£1m cap)

When to use

Use internal transfers when:

Moving funds between your own institution accounts (e.g. operational to segregated)
Sweeping from a hub account to a customer payment account (Embedded Banking)
Transferring between a real account and its virtual accounts

vs Faster Payments

When the destination is a ClearBank client and enforce_send_to_scheme: false (default), FPS payments are automatically routed as internal transfers. Use this module when you want explicit internal transfer semantics and the transfer stays within ClearBank.

Examples

{:ok, result} = ClearBank.Payments.InternalTransfer.send(client, %{
  debtor_account_id: "source-acct-uuid",
  creditor_account_id: "dest-acct-uuid",
  amount: "5000.00",
  currency: "GBP",
  reference: "Sweep to segregated"
})

Summary

Functions

send(client, params)

Sends an internal transfer between two ClearBank accounts.

send_bulk(client, transfers)

Sends multiple internal transfers in a single request (bulk).

Functions

send(client, params)

@spec send(ClearBank.Client.t(), map()) :: ClearBank.HTTP.result()

Sends an internal transfer between two ClearBank accounts.

Required params

:debtor_account_id - source account UUID
:creditor_account_id - destination account UUID
:amount - decimal string amount
:currency - ISO 4217 code (default: "GBP")

Optional params

:reference - transfer reference (max 35 chars)
:end_to_end_id - your end-to-end reference for idempotency tracking
:debtor_virtual_account_id - if debiting a virtual account
:creditor_virtual_account_id - if crediting a virtual account

Examples

# Between two real accounts
{:ok, _} = ClearBank.Payments.InternalTransfer.send(client, %{
  debtor_account_id: "ops-acct-uuid",
  creditor_account_id: "segregated-acct-uuid",
  amount: "10000.00",
  currency: "GBP",
  reference: "Daily sweep"
})

# From a real account to a virtual account
{:ok, _} = ClearBank.Payments.InternalTransfer.send(client, %{
  debtor_account_id: "hub-acct-uuid",
  creditor_account_id: "pool-acct-uuid",
  creditor_virtual_account_id: "customer-virt-uuid",
  amount: "250.00",
  currency: "GBP",
  reference: "Customer top-up"
})

send_bulk(client, transfers)

@spec send_bulk(ClearBank.Client.t(), [map()]) :: ClearBank.HTTP.result()

Sends multiple internal transfers in a single request (bulk).

Params

transfers - list of transfer maps (same fields as send/2)

Examples

{:ok, _} = ClearBank.Payments.InternalTransfer.send_bulk(client, [
  %{debtor_account_id: "acct-1", creditor_account_id: "acct-2",
    amount: "100.00", currency: "GBP"},
  %{debtor_account_id: "acct-1", creditor_account_id: "acct-3",
    amount: "200.00", currency: "GBP"}
])