Yookassa (yookassa v0.1.4)

View Source

The main module for interacting with the YooKassa API.

This module offers high-level functions for creating payments, capturing funds, canceling payments, and processing refunds. It serves as the primary entry point for integrating YooKassa functionality into an Elixir application.

Configuration

Before using the library, configure your credentials in config/config.exs:

config :yookassa,
  shop_id: "your_dev_shop_id",
  secret_key: "your_dev_secret_key",
  api_url: "https://api.yookassa.ru/v3"

The :shop_id and :secret_key are required for authentication.

Idempotency

All POST requests automatically include an Idempotence-Key header with a unique UUIDv4 value. This prevents accidental duplicate operations, ensuring that if a request is sent multiple times, it is processed only once.

Usage

Error Handling

All functions return {:ok, response_body} on success or {:error, reason} on failure. The response_body is the decoded JSON from the YooKassa API. The reason is typically a map containing the HTTP status and error details.

Summary

Functions

cancel_payment(payment_id)

Cancels a payment that is in waiting_for_capture status.

capture_payment(payment_id, opts \\ [])

Captures a payment that is in waiting_for_capture status.

create_payment(value, currency, return_url, description, opts \\ [])

Creates a new payment.

create_refund(payment_id, value, currency)

Creates a refund for a successful payment.

get_payment_info(payment_id)

Retrieves information about a specific payment.

get_refund_info(refund_id)

Retrieves information about a specific refund.

Functions

cancel_payment(payment_id)

Cancels a payment that is in waiting_for_capture status.

This action releases the hold on the user's funds. It is not a refund, as the funds were never captured.

Parameters

  • payment_id: The ID of the payment to be canceled.

Example

Yookassa.cancel_payment("21740069-...")

capture_payment(payment_id, opts \\ [])

Captures a payment that is in waiting_for_capture status.

This function sends a request to capture the full amount or a specified partial amount of an authorized payment. If no amount is provided, the full authorized amount is captured.

Parameters

  • payment_id: The ID of the payment to capture.
  • opts: A keyword list of optional parameters, such as :amount for partial capture.

Examples

# Capture the full amount of a payment
Yookassa.capture_payment("21740069-...")

# Capture a partial amount
Yookassa.capture_payment("21740069-...", amount: 100.00)

create_payment(value, currency, return_url, description, opts \\ [])

Creates a new payment.

This function constructs and sends a request to create a new payment with the specified amount, currency, and confirmation details. By default, payments are created with capture set to true.

Parameters

  • value: The payment amount, provided as a string or number (e.g., "100.00" or 100).
  • currency: The three-letter currency code (e.g., "RUB").
  • return_url: The URL to redirect the user to after payment confirmation.
  • description: A short description of the payment shown to the user.
  • opts: A keyword list of optional parameters, such as :capture or :metadata.

Examples

# Create a standard one-stage payment
Yookassa.create_payment("199.50", "RUB", "https://example.com/thanks", "Order №72")

# Create a two-stage payment (authorize only)
Yookassa.create_payment("199.50", "RUB", "https://example.com/thanks", "Order №72", capture: false)

create_refund(payment_id, value, currency)

Creates a refund for a successful payment.

Parameters

  • payment_id: The ID of the payment to be refunded.
  • value: The refund amount, as a string or number.
  • currency: The three-letter currency code.

Example

Yookassa.create_refund("21740069-...", "50.00", "RUB")

Notes

The YooKassa API has certain business rules for refunds:

  • The decimal separator for the value must be a dot (.), not a comma.
  • After a partial refund, the remaining amount on the payment must be at least 1 RUB.

get_payment_info(payment_id)

Retrieves information about a specific payment.

Returns a Yookassa.Payment struct on success.

Parameters

  • payment_id: The ID of the payment to retrieve.

Example

{:ok, payment} = Yookassa.get_payment_info("21740069-...")

get_refund_info(refund_id)

Retrieves information about a specific refund.

Returns a Yookassa.Refund struct on success.

Parameters

  • refund_id: The ID of the refund to retrieve.

Example

{:ok, refund} = Yookassa.get_refund_info("rfnd_1234567890")