Paysafe.Payments.Payments (Paysafe v1.0.0)

Payment operations for the Paysafe Payments API.

Payments are the final transaction step after a payment handle has reached PAYABLE status. Use the paymentHandleToken from your handle response to create the actual payment.

Examples

# Create a payment
Paysafe.Payments.Payments.create(config, %{
  merchant_ref_num: "order-001",
  amount: 5000,
  currency_code: "USD",
  settle_with_auth: true,
  payment_handle_token: "SCREhpnppPsIqkxO",
  description: "Widget purchase"
})

# Auth-only (settle later)
Paysafe.Payments.Payments.create(config, %{
  merchant_ref_num: "order-002",
  amount: 5000,
  currency_code: "USD",
  settle_with_auth: false,
  payment_handle_token: "SCREhpnppPsIqkxO"
})

Summary

Functions

cancel(config, payment_id, opts \\ [])

Cancel an authorized (not-yet-settled) payment.

create(config, params, opts \\ [])

Create a payment using a paymentHandleToken.

get(config, payment_id, opts \\ [])

Retrieve a payment by ID.

list(config, opts \\ [])

List payments with optional filters.

Functions

cancel(config, payment_id, opts \\ [])

@spec cancel(Paysafe.Config.t(), String.t(), keyword()) ::
  {:ok, Paysafe.Types.Payment.t()} | {:error, Paysafe.Error.t()}

Cancel an authorized (not-yet-settled) payment.

create(config, params, opts \\ [])

@spec create(Paysafe.Config.t(), map(), keyword()) ::
  {:ok, Paysafe.Types.Payment.t()} | {:error, Paysafe.Error.t()}

Create a payment using a paymentHandleToken.

Parameters

:merchant_ref_num (required) — Unique reference number (idempotency key).
:amount (required) — Amount in minor units.
:currency_code (required) — ISO 4217 currency code.
:payment_handle_token (required) — Token from a PAYABLE payment handle.
:settle_with_auth — If true, immediately settle (default: false).
:description — Description of the transaction.
:allow_partial_auth — Enables the Partial Authorization Service (PAS), see below.
:group_id — Links together up to 3 PAS authorization attempts within a single checkout session, see below.

Partial Authorization Service (PAS)

PAS mitigates 3022 insufficient-funds declines by allowing an issuer to approve less than the requested amount. To use it, pass:

Paysafe.Payments.Payments.create(config, %{
  merchant_ref_num: "order-001",
  amount: 10_000,
  currency_code: "EUR",
  payment_handle_token: handle.payment_handle_token,
  allow_partial_auth: true,
  group_id: "checkout-session-abc123"
})

If the cardholder only has funds for part of the amount, the response comes back with the authorized (partial) amount and you offer the cardholder up to two further attempts (same group_id, remaining balance as the new amount) for a maximum of 3 attempts per session. A 4th attempt with the same group_id is blocked with error 5068. PAS is supported for Visa/Mastercard and is currently UK/EEA-acquired merchants only (North America planned for a later date — check current availability with Paysafe). Must be pre-enabled on your merchant account.

get(config, payment_id, opts \\ [])

@spec get(Paysafe.Config.t(), String.t(), keyword()) ::
  {:ok, Paysafe.Types.Payment.t()} | {:error, Paysafe.Error.t()}

Retrieve a payment by ID.

list(config, opts \\ [])

@spec list(
  Paysafe.Config.t(),
  keyword()
) :: {:ok, [Paysafe.Types.Payment.t()]} | {:error, Paysafe.Error.t()}

List payments with optional filters.

Options

:merchant_ref_num — Filter by merchant ref number.
:start_date — ISO 8601 start date.
:end_date — ISO 8601 end date.
:limit — Maximum records to return.
:offset — Pagination offset.