MoneyHub.Payments (MoneyHub v1.0.0)

Copy Markdown View Source

Single Immediate Payments (SIP): initiate a payment authorisation and check payment status.

Creating a payment is a two-step process:

  1. Build the payment request payload and drive the user through MoneyHub.Auth with a mh:payment claim (see MoneyHub.Claims.put_payment/2) and the payment scope - the user authorises the payment at their bank.
  2. After the redirect back to your redirect_uri, exchange the code via MoneyHub.Auth.exchange_code/3 and read the resulting payment id from the verified id_token's mh:payment claim (MoneyHub.Auth.IdToken.fetch/2).

Use status/3 to poll the resulting payment afterwards - Moneyhub payments move through PENDING -> COMPLETED (or ERROR/REJECTED) asynchronously, and are also reported via the paymentCompleted / paymentPending / paymentError webhooks (see MoneyHub.Webhooks).

See Payments Overview, Single Immediate Payments, and Payments Status.

Summary

Types

payment()

Functions

build_request(attrs)

Builds the mh:payment claim value for a payment authorisation request.

list(config, token, opts \\ [])

Lists payments for the user identified by token.

refund(config, token, payment_id, attrs \\ %{})

Initiates a refund of a completed payment, where supported by the originating bank. See Reverse Payments.

status(config, token, payment_id)

Fetches a payment's current status by id.

Types

payment()

@type payment() :: map()

Functions

build_request(attrs)

@spec build_request(map()) :: map()

Builds the mh:payment claim value for a payment authorisation request.

attrs is merged onto required defaults - typically you'll provide at least:

%{
  "amount" => %{"amount" => 10.50, "currency" => "GBP"},
  "creditorAccount" => %{
    "identification" => %{"sortCode" => "010203", "accountNumber" => "12345678"}
  },
  "reference" => "Invoice 123"
}

Pass a "payeeId" instead of "creditorAccount" to pay an existing payee created via MoneyHub.Payees.create/3.

list(config, token, opts \\ [])

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

Lists payments for the user identified by token.

refund(config, token, payment_id, attrs \\ %{})

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

Initiates a refund of a completed payment, where supported by the originating bank. See Reverse Payments.

status(config, token, payment_id)

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

Fetches a payment's current status by id.