iyzico v1.5.0 Iyzico.Iyzipay

A module containing payment related functions.

Making a payment

In order to process a payment, one needs to create a Iyzico.PaymentRequest struct, which consists of a payment card, a buyer, two seperate addresses for shipping and billing and basket information (aka items).

payment_request =
  %PaymentRequest{
    locale: @current_locale,
    conversation_id: "123456789",
    price: "0.5",
    paid_price: "0.7",
    currency: :try,
    basket_id: "B67832",
    payment_channel: :web,
    payment_group: :product,
    payment_card: card,
    installment: 1,
    buyer: buyer,
    shipping_address: shipping_address,
    billing_address: billing_address,
    basket_items: [
      binocular_item,
      game_item
    ]
  }

With that Iyzico.PaymentRequest, it is straightforward to process the request.

{:ok, payment, metadata} = process_payment_req(payment_request)

3D Secure support

Authenticity of a transaction can be enhanced using 3D Secure feature, which is optional, although some associations might require the use of 3D Secure explicitly. 3D Secure based transaction could performed with process_secure_payment_req/2 function, which is analogical to its insecure friend process_payment_req/3.

Making a secure payment

Processing a secure payment is on par with insecure payments, what is more, secure payments require a callback URL since remote authority will finalize the transaction by making a call to given URL.

Instantiation

payment_request =
  %SecurePaymentRequest{
    locale: @current_locale,
    conversation_id: "123456789",
    price: "0.5",
    paid_price: "0.7",
    currency: :try,
    basket_id: "B67832",
    payment_channel: :web,
    payment_group: :product,
    payment_card: card,
    installment: 1,
    buyer: buyer,
    shipping_address: shipping_address,
    billing_address: billing_address,
    basket_items: [
      binocular_item,
      game_item
    ],
    callback_url: "https://some.domain.to/be-specified/"
  }

{:ok, artifact, metadata} = init_secure_payment_req(payment_request)

Finalization

handle =
  %SecurePaymentHandle{
    conversation_id: "123456789",
    payment_id: "10533265",
    conversation_data: "some data"
  }

{:ok, payment, metadata} = finalize_secure_payment_req(handle)

Post-payment operations

After payment is successfully completed, it can be revoked (cancelled) or refunded. A revoke operation deletes the payment and can be utilized if and only if transaction has not reconciliated by the bank, which often happens at the end of a day. Successful revoke operations are invisible in card statement.

Some regulations applied by banks on transactions might restrict cancellation operations.

Refund operations could also be performed in order to pay back specified amount of funds and can be performed in any time, without any restrictions. Merchants are able to refund up to full amount of the transaction, and able to do it with proportions of the amount. Multiple refund operations could be performed by making sequential calls.

Discussion

Although utilization of 3D secure featured transactions become overwhelming in terms of duration of the payment it is highly discouraged to perform insecure transactions directly, especially without concerning about customer’s consent. Secure transactions involve two-factor authentication provided by associations, hence displacing the responsibility of the developer to be not concerned about authenticity of the credit card information.

Common options

  • :api_key: API key to be used in authentication, optional. Configuration is used instead if not supplied.

  • :api_secret: API secret key to be used in authentication. Configuration is used instead if not supplied.

Link to this section Summary

Functions

Finalizes a valid secure payment artifact on the remote API

Instantiates the given secure payment request on the remote API

Processes the given payment request on the remote API

Same as process_payment_req/1, but raises an Iyzico.PaymentProcessingError exception in case of failure. Otherwise returns successfully processed payment

Refunds a payment of a successful transaction by given amount

Revokes an existing payment on the remote API. Returns {:error, :unowned} if payment is not owned by the API user

Link to this section Types

Link to this type currency()
currency() :: :try

Link to this section Functions

Link to this function finalize_secure_payment_req(secure_payment_handle, opts \\ [])
finalize_secure_payment_req(Iyzico.SecurePaymentHandle.t, Keyword.t) ::
  {:ok, Iyzico.Payment.t, Iyzico.Metadata.t} |
  {:error, atom}

Finalizes a valid secure payment artifact on the remote API.

Options

See common options.

Link to this function init_secure_payment_req(secure_payment_request, opts \\ [])
init_secure_payment_req(Iyzico.SecurePaymentRequest.t, Keyword.t) ::
  {:ok, Iyzico.SecurePaymentArtifact.t, Iyzico.Metadata.t} |
  {:error, atom}

Instantiates the given secure payment request on the remote API.

Options

See common options.

Link to this function process_payment_req(payment_request, opts \\ [])
process_payment_req(Iyzico.PaymentRequest.t, Keyword.t) ::
  {:ok, Iyzico.Payment.t, Iyzico.Metadata.t} |
  {:error, atom}

Processes the given payment request on the remote API.

Options

See common options.

Link to this function process_payment_req!(payment_request, opts \\ [])

Same as process_payment_req/1, but raises an Iyzico.PaymentProcessingError exception in case of failure. Otherwise returns successfully processed payment.

Link to this function refund_payment(transaction_id, conversation_id, price, currency, opts \\ [])
refund_payment(binary, binary, binary, currency, Keyword.t) ::
  {:ok, Iyzico.Metadata.t} |
  {:error, :excessive_funds} |
  {:error, :unowned}

Refunds a payment of a successful transaction by given amount.

Options

See common options.

Link to this function refund_payment!(transaction_id, conversation_id, price, currency, opts \\ [])
refund_payment!(binary, binary, binary, currency, Keyword.t) ::
  Iyzico.Metadata.t |
  no_return

Same as refund_payment/5, but raises Iyzico.InternalInconsistencyError if there was an error.

Link to this function revoke_payment(payment_id, conversation_id, opts \\ [])
revoke_payment(binary, binary, Keyword.t) ::
  {:ok, Iyzico.Metadata.t} |
  {:error, :unowned}

Revokes an existing payment on the remote API. Returns {:error, :unowned} if payment is not owned by the API user.

Options

See common options.

Link to this function revoke_payment!(payment_id, conversation_id, opts \\ [])
revoke_payment!(binary, binary, Keyword.t) ::
  Iyzico.Metadata.t |
  no_return

Same as revoke_payment/3, but raises Iyzico.InternalInconsistencyError if there was an error.