Unit.API.Authorizations (Unit v1.0.0)

Copy Markdown View Source

API module for Unit Card Authorizations.

Authorizations represent pending card transactions that have been approved by the card network but not yet settled. They transition to transactions upon settlement, or are reversed if canceled/expired.

Lifecycle

  1. Card is presented at merchant
  2. authorization.created webhook fires → Authorization resource created
  3. Authorization settles → purchaseTransaction created, authorization Completed
  4. Or: authorization expires/is voided → Canceled

Authorization requests (real-time decline)

If your program has real-time authorization control enabled, Unit will send an HTTP request to your endpoint for each authorization. You have ~3 seconds to respond with approve/decline + optional partial amount.

See Unit.API.Authorizations.list_requests/1 and Unit.API.Authorizations.approve_request/3.

Summary

Functions

approve_request(id, params \\ %{}, opts \\ [])

Approve a real-time authorization request.

decline_request(id, reason, opts \\ [])

Decline a real-time authorization request.

get(id, opts \\ [])

Get an authorization by ID.

get_request(id, opts \\ [])

Get a real-time authorization request by ID.

list(opts \\ [])

List authorizations.

list_requests(opts \\ [])

List real-time authorization requests (requires authorization control feature).

Functions

approve_request(id, params \\ %{}, opts \\ [])

@spec approve_request(String.t(), map(), keyword()) :: Unit.Client.response()

Approve a real-time authorization request.

Must be called within ~3 seconds of receiving the authorization request webhook.

Params

  • :amount — approved amount in cents (omit or match original to approve in full; provide less for partial approval)
  • :funding_account — override the funding account
  • :tags

decline_request(id, reason, opts \\ [])

@spec decline_request(String.t(), String.t(), keyword()) :: Unit.Client.response()

Decline a real-time authorization request.

Params

  • :reason — decline reason string (e.g. "AccountClosed", "DoNotHonor")

get(id, opts \\ [])

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

Get an authorization by ID.

get_request(id, opts \\ [])

@spec get_request(
  String.t(),
  keyword()
) :: Unit.Client.response()

Get a real-time authorization request by ID.

list(opts \\ [])

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

List authorizations.

Filter options

  • :account_id
  • :customer_id
  • :card_id
  • :since / :until — ISO 8601 datetime strings

  • :status — "Authorized" | "Completed" | "Canceled" | "Declined"

  • :page_limit, :page_offset

list_requests(opts \\ [])

@spec list_requests(keyword()) :: Unit.Client.response()

List real-time authorization requests (requires authorization control feature).

Authorization requests are pending decisions — your handler must respond within ~3 seconds. These are distinct from the standard Authorization resource.

Filter options

  • :customer_id
  • :card_id
  • :page_limit, :page_offset