mollie_api

# NOTE: This file is auto generated by OpenAPI Generator 7.17.0 (https://openapi-generator.tech).
# Do not edit this file manually.

defmodule MollieAPI.Api.PaymentsAPI do
  @moduledoc """
  API calls for all endpoints tagged `PaymentsAPI`.
  """

  alias MollieAPI.Connection
  import MollieAPI.RequestBuilder

  @doc """
  Cancel payment
  Depending on the payment method, you may be able to cancel a payment for a certain amount of time — usually until the next business day or as long as the payment status is open.  Payments may also be canceled manually from the Mollie Dashboard.  The `isCancelable` property on the [Payment object](get-payment) will indicate if the payment can be canceled.

  ### Parameters

  - `connection` (MollieAPI.Connection): Connection to server
  - `payment_id` (String.t): Provide the ID of the related payment.
  - `opts` (keyword): Optional parameters
    - `:"idempotency-key"` (String.t): A unique key to ensure idempotent requests. This key should be a UUID v4 string.
    - `:body` (CancelPaymentRequest): 

  ### Returns

  - `{:ok, MollieAPI.Model.PaymentResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec cancel_payment(Tesla.Env.client, String.t, keyword()) :: {:ok, MollieAPI.Model.ErrorResponse.t} | {:ok, MollieAPI.Model.PaymentResponse.t} | {:error, Tesla.Env.t}
  def cancel_payment(connection, payment_id, opts \\ []) do
    optional_params = %{
      :"idempotency-key" => :headers,
      :body => :body
    }

    request =
      %{}
      |> method(:delete)
      |> url("/v2/payments/#{payment_id}")
      |> add_optional_params(optional_params, opts)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, MollieAPI.Model.PaymentResponse},
      {404, MollieAPI.Model.ErrorResponse},
      {422, MollieAPI.Model.ErrorResponse},
      {429, MollieAPI.Model.ErrorResponse}
    ])
  end

  @doc """
  Create payment
  Payment creation is elemental to the Mollie API: this is where most payment implementations start off.  Once you have created a payment, you should redirect your customer to the URL in the `_links.checkout` property from the response.  To wrap your head around the payment process, an explanation and flow charts can be found in the 'Accepting payments' guide.  If you specify the `method` parameter when creating a payment, optional additional parameters may be available for the payment method that are not listed below. Please refer to the guide on [method-specific parameters](extra-payment-parameters).

  ### Parameters

  - `connection` (MollieAPI.Connection): Connection to server
  - `opts` (keyword): Optional parameters
    - `:include` (String.t): This endpoint allows you to include additional information via the `include` query string parameter.
    - `:"idempotency-key"` (String.t): A unique key to ensure idempotent requests. This key should be a UUID v4 string.
    - `:body` (PaymentRequest): 

  ### Returns

  - `{:ok, MollieAPI.Model.PaymentResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec create_payment(Tesla.Env.client, keyword()) :: {:ok, MollieAPI.Model.ErrorResponse.t} | {:ok, MollieAPI.Model.PaymentResponse.t} | {:error, Tesla.Env.t}
  def create_payment(connection, opts \\ []) do
    optional_params = %{
      :include => :query,
      :"idempotency-key" => :headers,
      :body => :body
    }

    request =
      %{}
      |> method(:post)
      |> url("/v2/payments")
      |> add_optional_params(optional_params, opts)
      |> ensure_body()
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {201, MollieAPI.Model.PaymentResponse},
      {422, MollieAPI.Model.ErrorResponse},
      {429, MollieAPI.Model.ErrorResponse},
      {503, MollieAPI.Model.ErrorResponse}
    ])
  end

  @doc """
  Get payment
  Retrieve a single payment object by its payment ID.

  ### Parameters

  - `connection` (MollieAPI.Connection): Connection to server
  - `payment_id` (String.t): Provide the ID of the related payment.
  - `opts` (keyword): Optional parameters
    - `:include` (String.t): This endpoint allows you to include additional information via the `include` query string parameter.
    - `:embed` (String.t): This endpoint allows embedding related API items by appending the following values via the `embed` query string parameter.
    - `:testmode` (boolean()): Most API credentials are specifically created for either live mode or test mode. In those cases the `testmode` query parameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting the `testmode` query parameter to `true`.  Test entities cannot be retrieved when the endpoint is set to live mode, and vice versa.
    - `:"idempotency-key"` (String.t): A unique key to ensure idempotent requests. This key should be a UUID v4 string.

  ### Returns

  - `{:ok, MollieAPI.Model.PaymentResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec get_payment(Tesla.Env.client, String.t, keyword()) :: {:ok, MollieAPI.Model.ErrorResponse.t} | {:ok, MollieAPI.Model.PaymentResponse.t} | {:error, Tesla.Env.t}
  def get_payment(connection, payment_id, opts \\ []) do
    optional_params = %{
      :include => :query,
      :embed => :query,
      :testmode => :query,
      :"idempotency-key" => :headers
    }

    request =
      %{}
      |> method(:get)
      |> url("/v2/payments/#{payment_id}")
      |> add_optional_params(optional_params, opts)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, MollieAPI.Model.PaymentResponse},
      {404, MollieAPI.Model.ErrorResponse},
      {429, MollieAPI.Model.ErrorResponse}
    ])
  end

  @doc """
  List payments
  Retrieve all payments created with the current website profile.  The results are paginated.

  ### Parameters

  - `connection` (MollieAPI.Connection): Connection to server
  - `opts` (keyword): Optional parameters
    - `:from` (String.t): Provide an ID to start the result set from the item with the given ID and onwards. This allows you to paginate the result set.
    - `:limit` (integer()): The maximum number of items to return. Defaults to 50 items.
    - `:sort` (Sorting): Used for setting the direction of the result set. Defaults to descending order, meaning the results are ordered from newest to oldest.
    - `:profileId` (String.t): The identifier referring to the [profile](get-profile) you wish to retrieve the resources for.  Most API credentials are linked to a single profile. In these cases the `profileId` must not be sent. For organization-level credentials such as OAuth access tokens however, the `profileId` parameter is required.
    - `:testmode` (boolean()): Most API credentials are specifically created for either live mode or test mode. In those cases the `testmode` query parameter must not be sent. For organization-level credentials such as OAuth access tokens, you can enable test mode by setting the `testmode` query parameter to `true`.  Test entities cannot be retrieved when the endpoint is set to live mode, and vice versa.
    - `:"idempotency-key"` (String.t): A unique key to ensure idempotent requests. This key should be a UUID v4 string.

  ### Returns

  - `{:ok, MollieAPI.Model.ListPayments200Response.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec list_payments(Tesla.Env.client, keyword()) :: {:ok, MollieAPI.Model.ListPayments200Response.t} | {:ok, MollieAPI.Model.ErrorResponse.t} | {:error, Tesla.Env.t}
  def list_payments(connection, opts \\ []) do
    optional_params = %{
      :from => :query,
      :limit => :query,
      :sort => :query,
      :profileId => :query,
      :testmode => :query,
      :"idempotency-key" => :headers
    }

    request =
      %{}
      |> method(:get)
      |> url("/v2/payments")
      |> add_optional_params(optional_params, opts)
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, MollieAPI.Model.ListPayments200Response},
      {400, MollieAPI.Model.ErrorResponse},
      {429, MollieAPI.Model.ErrorResponse}
    ])
  end

  @doc """
  Release payment authorization
  Releases the full remaining authorized amount. Call this endpoint when you will not be making any additional captures. Payment authorizations may also be released manually from the Mollie Dashboard.  Mollie will do its best to process release requests, but it is not guaranteed that it will succeed. It is up to the issuing bank if and when the hold will be released.  If the request does succeed, the payment status will change to `canceled` for payments without captures. If there is a successful capture, the payment will transition to `paid`.

  ### Parameters

  - `connection` (MollieAPI.Connection): Connection to server
  - `payment_id` (String.t): Provide the ID of the related payment.
  - `opts` (keyword): Optional parameters
    - `:"idempotency-key"` (String.t): A unique key to ensure idempotent requests. This key should be a UUID v4 string.
    - `:body` (ReleaseAuthorizationRequest): 

  ### Returns

  - `{:ok, nil}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec release_authorization(Tesla.Env.client, String.t, keyword()) :: {:ok, nil} | {:ok, MollieAPI.Model.ErrorResponse.t} | {:error, Tesla.Env.t}
  def release_authorization(connection, payment_id, opts \\ []) do
    optional_params = %{
      :"idempotency-key" => :headers,
      :body => :body
    }

    request =
      %{}
      |> method(:post)
      |> url("/v2/payments/#{payment_id}/release-authorization")
      |> add_optional_params(optional_params, opts)
      |> ensure_body()
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {202, false},
      {404, MollieAPI.Model.ErrorResponse},
      {422, MollieAPI.Model.ErrorResponse},
      {429, MollieAPI.Model.ErrorResponse}
    ])
  end

  @doc """
  Update payment
  Certain details of an existing payment can be updated.  Updating the payment details will not result in a webhook call.

  ### Parameters

  - `connection` (MollieAPI.Connection): Connection to server
  - `payment_id` (String.t): Provide the ID of the related payment.
  - `opts` (keyword): Optional parameters
    - `:"idempotency-key"` (String.t): A unique key to ensure idempotent requests. This key should be a UUID v4 string.
    - `:body` (UpdatePaymentRequest): 

  ### Returns

  - `{:ok, MollieAPI.Model.PaymentResponse.t}` on success
  - `{:error, Tesla.Env.t}` on failure
  """
  @spec update_payment(Tesla.Env.client, String.t, keyword()) :: {:ok, MollieAPI.Model.ErrorResponse.t} | {:ok, MollieAPI.Model.PaymentResponse.t} | {:error, Tesla.Env.t}
  def update_payment(connection, payment_id, opts \\ []) do
    optional_params = %{
      :"idempotency-key" => :headers,
      :body => :body
    }

    request =
      %{}
      |> method(:patch)
      |> url("/v2/payments/#{payment_id}")
      |> add_optional_params(optional_params, opts)
      |> ensure_body()
      |> Enum.into([])

    connection
    |> Connection.request(request)
    |> evaluate_response([
      {200, MollieAPI.Model.PaymentResponse},
      {404, MollieAPI.Model.ErrorResponse},
      {422, MollieAPI.Model.ErrorResponse},
      {429, MollieAPI.Model.ErrorResponse}
    ])
  end
end