MoneyHub.RecurringPayments (MoneyHub v1.0.0)

Copy Markdown View Source

Variable Recurring Payments (VRP): set up a recurring payment consent once, then trigger individual payments ("sweeps") against it without further user interaction, up to the consented limits.

Setup mirrors single payments: drive the user through MoneyHub.Auth with a mh:recurring_payment claim (MoneyHub.Claims.put_recurring_payment/2) and the recurring_payment scope. The resulting consent enforces limits such as maximumIndividualAmount and a periodic cap - individual sweep payments must stay within them.

A common pattern (see Moneyhub's "Smart Saver" recipe) is to combine this with MoneyHub.Webhooks balanceThreshold events: when a current-account balance crosses a configured threshold, trigger a sweep of the surplus into a savings account.

See Recurring Payments (VRP).

Summary

Types

consent()
sweep()

Functions

confirm_funds(config, token, consent_id, attrs)

Checks whether sufficient funds are currently available for a sweep, without actually creating a payment. Requires the recurring-payment:funds_confirmation scope.

get(config, token, consent_id)

Fetches a recurring payment consent's current status by id.

list(config, token)

Lists recurring payment consents created by this API client.

revoke(config, token, consent_id)

Revokes a recurring payment consent, preventing further sweeps.

sweep(config, token, consent_id, attrs)

Triggers a single sweep payment against an established VRP consent.

Types

consent()

@type consent() :: map()

sweep()

@type sweep() :: map()

Functions

confirm_funds(config, token, consent_id, attrs)

@spec confirm_funds(MoneyHub.Config.t(), String.t(), String.t(), map()) ::
  {:ok, map()} | {:error, MoneyHub.Error.t()}

Checks whether sufficient funds are currently available for a sweep, without actually creating a payment. Requires the recurring-payment:funds_confirmation scope.

get(config, token, consent_id)

@spec get(MoneyHub.Config.t(), String.t(), String.t()) ::
  {:ok, consent()} | {:error, MoneyHub.Error.t()}

Fetches a recurring payment consent's current status by id.

list(config, token)

@spec list(MoneyHub.Config.t(), String.t()) ::
  {:ok, [consent()]} | {:error, MoneyHub.Error.t()}

Lists recurring payment consents created by this API client.

revoke(config, token, consent_id)

@spec revoke(MoneyHub.Config.t(), String.t(), String.t()) ::
  :ok | {:error, MoneyHub.Error.t()}

Revokes a recurring payment consent, preventing further sweeps.

sweep(config, token, consent_id, attrs)

@spec sweep(MoneyHub.Config.t(), String.t(), String.t(), map()) ::
  {:ok, sweep()} | {:error, MoneyHub.Error.t()}

Triggers a single sweep payment against an established VRP consent.

attrs carries the sweep's amount/reference, similar to a single payment request - it must stay within the consent's configured limits or the bank will reject it. Requires the recurring-payment:create scope.