tipalti v0.1.0 Tipalti.API.Payee View Source

Obtain or update payee info.

Details are taken from: https://api.tipalti.com/v6/PayeeFunctions.asmx

Link to this section Summary

Types

All Payee API responses are of this form

Functions

Returns extended details and custom fields of given payees

Returns details of a given payee

Return payable status of payee

Returns the name of the payee’s selected payment method

Updates a payee’s basic info

Link to this section Types

Link to this type payee_response() View Source
payee_response() :: {:ok, map() | :ok} | {:error, any()}

All Payee API responses are of this form.

Link to this section Functions

Link to this function get_extended_payee_details_list(idaps) View Source
get_extended_payee_details_list([Tipalti.idap(), ...]) :: payee_response()

Returns extended details and custom fields of given payees.

Included extended details are:

  • idap
  • alias
  • company_name
  • email
  • first_name
  • middle_name
  • last_name
  • payment_method
  • street1
  • street2
  • city
  • state
  • zip
  • country
  • phone
  • payment_currency
  • payable
  • status
  • preferred_payer_entity
  • actual_payer_entity
  • tax_form_status
  • portal_user
  • withholding_rate
  • tax_form_entity_type
  • tax_form_entity_name
  • tax_form_type
Link to this function get_payee_details(idap) View Source
get_payee_details(Tipalti.idap()) :: payee_response()

Returns details of a given payee.

Included details are:

  • name
  • company_name
  • alias
  • address
  • payment_method
  • email
  • payment_terms_id
  • payment_terms_name

Examples

iex> get_payee_details("somepayee")
  {:ok,
    %{
      address: "123 Somewhere St.",
      alias: "acmepayee",
      company_name: "ACME",
      email: "someone@example.com",
      name: "Some Payee",
      payment_method: "Check",
      payment_terms_id: nil,
      payment_terms_name: nil
    }}

  iex> get_payee_details("badpayee")
  {:error, %{error_code: "PayeeUnknown", error_message: "PayeeUnknown"}}
Link to this function payee_payable(idap, amount \\ 100.0) View Source
payee_payable(Tipalti.idap(), integer() | float()) :: payee_response()

Return payable status of payee.

If a payment request were to be issued, the payee might not get paid. Possible reasons for not being paid are - missing tax documents, payment below threshold, account locked, address missing, or other. Returns true if payable. If false, the reason for not being payable will be included.

Examples

iex> payee_payable("payablepayee", 100)
  {:ok, %{payable: true, reason: nil}}

  iex> payee_payable("unpayablepayee")
  {:ok, %{payable: false, reason: "Tax,No PM"}}

  iex> payee_payable("badpayee", 123.45)
  {:error, %{error_code: "PayeeUnknown", error_message: "PayeeUnknown"}}
Link to this function payee_payment_method(idap) View Source
payee_payment_method(Tipalti.idap()) :: payee_response()

Returns the name of the payee’s selected payment method.

Examples

iex> payee_payment_method("payablepayee")
  {:ok, %{payment_method: "Check"}}

  iex> payee_payment_method("unpayablepayee")
  {:ok, %{payment_method: "No payment method"}}

  iex> payee_payment_method("badpayee")
  {:error, %{error_code: "PayeeUnknown", error_message: "PayeeUnknown"}}
Link to this function payee_status_update(idap, status, reason \\ nil) View Source
payee_status_update(
  Tipalti.idap(),
  :active | :suspended | :blocked,
  String.t() | nil
) :: payee_response()

Update the status of payee.

Valid values for status are: :active, :suspended, or :blocked. When blocking a payee, a blocking reason may be supplied

Examples

iex> payee_status_update("somepayee", :blocked, "Business closed")
  {:ok, :ok}
Link to this function update_or_create_payee_info(idap, params, opts) View Source
update_or_create_payee_info(Tipalti.idap(), map(), keyword()) ::
  payee_response()

Updates a payee’s basic info.

If the payee does not exist, it will be created. The details must match the ones in the payee bank records. State can either be null, or a valid 2 letter US state. If skip_nulls=true the parameters with null values will be ignored. If skip_nulls=false the null values will overwrite existing values. Country is a 2 letter ISO 3166 code.

Possible fields:

  • first_name - string
  • last_name - string
  • street1 - string
  • street2 - string
  • city - string
  • state - string
  • zip - string
  • country - string
  • email - string
  • company - string
  • alias - string
  • preferred_payer_entity - string
  • ap_account_number - string
  • payment_terms_id - string

Required options:

  • skip_nulls - boolean
  • override_payable_country - boolean

Examples

iex> update_or_create_payee_info("newpayee", %{first_name: "John", last_name: "Smith"}, skip_nulls: true, override_payable_country: false)
  {:ok, :ok}

  iex> update_or_create_payee_info("invalidname", %{first_name: "José", last_name: "Valim"}, skip_nulls: true, override_payable_country: false)
  {:error, %{error_code: "ParameterError", error_message: "Invalid payee first name"}}