Railsr.Resources.Beneficiaries (Railsr v1.0.0)

Copy Markdown View Source

Railsr Beneficiary API.

A beneficiary is an external bank account you can send money to. Supports UK (sort code + account number), EUR (IBAN), and international (IBAN + BIC).

Confirmation of Payee (CoP)

UK FPS payments benefit from CoP verification — Railsr checks whether the account holder name matches the provided details. Always run CoP before the first payment to reduce fraud risk.

{:ok, ben} = Railsr.Resources.Beneficiaries.create(%{
  enduser_id: "eu_xxx",
  name: "Bob Jones",
  uk_account_number: "12345678",
  uk_sort_code: "040004",
  currency: "GBP"
})

{:ok, ben} = Railsr.Resources.Beneficiaries.verify(ben.beneficiary_id, "faster-payment")
# ben.cop_matched => true | false | nil

Summary

Functions

create(params, opts \\ [])

Create a new beneficiary.

get(beneficiary_id, opts \\ [])

Retrieve a beneficiary by ID.

list(query \\ %{}, opts \\ [])

List beneficiaries.

recalculate_firewall(beneficiary_id, opts \\ [])

Manually trigger a compliance firewall recalculation for this beneficiary.

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

Update beneficiary details (triggers compliance firewall re-evaluation).

verify(beneficiary_id, payment_type \\ "faster-payment", opts \\ [])

Run Confirmation of Payee (CoP) for a UK payment.

Functions

create(params, opts \\ [])

@spec create(
  map(),
  keyword()
) :: {:ok, Railsr.Types.Beneficiary.t()} | {:error, Railsr.Error.t()}

Create a new beneficiary.

GBP beneficiary (UK)

  • :name — account holder name
  • :uk_account_number
  • :uk_sort_code
  • :currency — "GBP"
  • :enduser_id (optional, associates with an enduser)

EUR / international beneficiary

  • :name
  • :iban
  • :bic
  • :currency
  • :country

get(beneficiary_id, opts \\ [])

@spec get(
  String.t(),
  keyword()
) :: {:ok, Railsr.Types.Beneficiary.t()} | {:error, Railsr.Error.t()}

Retrieve a beneficiary by ID.

list(query \\ %{}, opts \\ [])

@spec list(
  map(),
  keyword()
) :: {:ok, [Railsr.Types.Beneficiary.t()]} | {:error, Railsr.Error.t()}

List beneficiaries.

Query params (all optional)

  • :enduser_id
  • :status
  • :currency
  • :limit / :offset

recalculate_firewall(beneficiary_id, opts \\ [])

@spec recalculate_firewall(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, Railsr.Error.t()}

Manually trigger a compliance firewall recalculation for this beneficiary.

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

@spec update(String.t(), map(), keyword()) ::
  {:ok, Railsr.Types.Beneficiary.t()} | {:error, Railsr.Error.t()}

Update beneficiary details (triggers compliance firewall re-evaluation).

verify(beneficiary_id, payment_type \\ "faster-payment", opts \\ [])

@spec verify(String.t(), String.t(), keyword()) ::
  {:ok, Railsr.Types.Beneficiary.t()} | {:error, Railsr.Error.t()}

Run Confirmation of Payee (CoP) for a UK payment.

payment_type should be "faster-payment" or "bacs".

Returns the beneficiary struct with :cop_result and :cop_matched populated.

CoP result codes

  • "matched" — name matches exactly
  • "close_match" — name matches closely (proceed with caution)
  • "no_match" — name does not match (block or warn user)
  • "not_available" — receiving bank does not support CoP