Unit.API.RecurringPayments (Unit v1.0.0)

Copy Markdown View Source

API module for Unit Recurring Payments.

Recurring payments automate scheduled ACH or Book transfers on a configurable interval (daily, weekly, monthly, etc.).

Types

  • recurringCreditAchPayment — outgoing ACH credit on schedule
  • recurringDebitAchPayment — incoming ACH debit on schedule
  • recurringCreditBookPayment — recurring internal book payment

Schedule object

The schedule map defines when payments run:

%{
  start_time: ~D[2024-02-01],     # When first payment fires
  end_time: ~D[2024-12-31],       # Optional end date
  interval: "Monthly",            # Daily | Weekly | Monthly | Yearly
  day_of_month: 1,                # For Monthly (1–28)
  day_of_week: "Monday",          # For Weekly
  total_number_of_payments: 12    # Optional cap
}

Statuses

  • Active — running as scheduled
  • Completed — all payments sent (total_number_of_payments reached or end_time passed)
  • Disabled — paused

Summary

Functions

create_credit_ach(params, opts \\ [])

Create a recurring ACH credit payment.

create_credit_book(params, opts \\ [])

Create a recurring book (internal) credit payment.

create_debit_ach(params, opts \\ [])

Create a recurring ACH debit payment.

disable(id, opts \\ [])

Disable (pause) an active recurring payment.

enable(id, opts \\ [])

Enable (un-pause) a disabled recurring payment.

get(id, opts \\ [])

Get a recurring payment by ID.

list(opts \\ [])

List recurring payments.

update(id, params, opts \\ [])

Update a recurring payment's amount, description, or schedule.

Functions

create_credit_ach(params, opts \\ [])

@spec create_credit_ach(
  map(),
  keyword()
) :: {:ok, Unit.Resource.RecurringPayment.t()} | {:error, term()}

Create a recurring ACH credit payment.

Required params

  • :account_id — source deposit account
  • :amount — in cents (fixed per occurrence)
  • :description
  • :schedule — schedule map (see module doc)
  • :counterparty_id or :counterparty — inline counterparty map

Optional

  • :same_day — boolean
  • :addenda — addenda string
  • :tags
  • :idempotency_key

create_credit_book(params, opts \\ [])

@spec create_credit_book(
  map(),
  keyword()
) :: {:ok, Unit.Resource.RecurringPayment.t()} | {:error, term()}

Create a recurring book (internal) credit payment.

Required params

  • :account_id — source account
  • :counterparty_account_id — destination account
  • :amount
  • :description
  • :schedule

create_debit_ach(params, opts \\ [])

@spec create_debit_ach(
  map(),
  keyword()
) :: {:ok, Unit.Resource.RecurringPayment.t()} | {:error, term()}

Create a recurring ACH debit payment.

Same parameters as create_credit_ach/2 with direction implied as Debit.

disable(id, opts \\ [])

@spec disable(
  String.t(),
  keyword()
) :: {:ok, Unit.Resource.RecurringPayment.t()} | {:error, term()}

Disable (pause) an active recurring payment.

enable(id, opts \\ [])

@spec enable(
  String.t(),
  keyword()
) :: {:ok, Unit.Resource.RecurringPayment.t()} | {:error, term()}

Enable (un-pause) a disabled recurring payment.

get(id, opts \\ [])

@spec get(
  String.t(),
  keyword()
) :: {:ok, Unit.Resource.RecurringPayment.t()} | {:error, term()}

Get a recurring payment by ID.

list(opts \\ [])

@spec list(keyword()) ::
  {:ok, [Unit.Resource.RecurringPayment.t()], map()} | {:error, term()}

List recurring payments.

Filter options

  • :account_id
  • :customer_id

  • :status — "Active" | "Completed" | "Disabled"

  • :type
  • :page_limit, :page_offset

update(id, params, opts \\ [])

@spec update(String.t(), map(), keyword()) ::
  {:ok, Unit.Resource.RecurringPayment.t()} | {:error, term()}

Update a recurring payment's amount, description, or schedule.

Can only be updated when status is Active.