Refund, hold and capture a payment

v0.0.1

Money can wait on a card before it is taken, and it can go back to the buyer after it was taken. This guide shows how to hold a payment and capture it later, how to refund all or part of a payment, how to answer a dispute and how a site decides how often a payment can be refunded. A Mishka CMS site sets the refund rule in its own keys, so each site can differ.

Before you begin

  • A paid payment for refunds, or a checkout made with capture: :manual for holds. See Take a one-time payment.
  • A provider with the :refund capability. Holds and captures need :capture, which Stripe has and PayPal does not. See Capabilities by provider.

Hold a payment and capture it later

Add capture: :manual to a one-time checkout. The money is held on the card and the payment reads :authorized.

elixir
MishkaPay.capture_payment("stripe", payment.id, site.id)

MishkaPay.capture_payment("stripe", payment.id, site.id,
  amount: %{amount: "10", currency: "USD"}
)

MishkaPay.cancel_payment("stripe", payment.id, site.id)
  • Without amount:, the whole hold is taken. With it, only that part is taken and Stripe lets the rest go.
  • An amount in another currency, or above the hold, is Errors.Invalid on :amount.
  • cancel_payment/3 lets the hold go. A hold also ends by itself after some days (Stripe: 7).
  • A payment captured in part reads :amount_captured, and a refund can give back only that part.
  • Stripe holds no money where it makes an invoice after payment. capture: :manual with invoice: true or merchant_of_record: true is Errors.Invalid on :capture. If the Stripe account's default is Managed Payments, send merchant_of_record: false.

capture: :automatic is the default, and Mishka Pay sends Stripe's faster automatic_async for it. Use capture: :automatic_sync if the site needs the answer only once the money is taken.

Refund a payment

elixir
MishkaPay.refund(%{
  provider: "stripe",
  tenant: site.id,
  payment_id: "pi_...",
  amount: %{amount: "5", currency: "USD"},
  reason: :requested_by_customer
})
  • Leave amount out to refund the whole payment.
  • reason is :requested_by_customer, :duplicate or :fraudulent. Stripe blocks the card in the account's Radar after a :fraudulent refund, so use it only for real fraud.
  • The answer is a %MishkaPay.Refund{}. Read one again with fetch_refund/3, or list a payment's refunds with list_refunds("stripe", site.id, payment_id: id).

Decide how often a payment can be refunded

The site's keys carry a refunds setting.

  • :once (the default) refuses a second refund on the same payment. A buyer who wants more makes a new purchase.
  • :many allows part refunds until the payment is used up. Each one needs its own reference:.
elixir
MishkaPay.refund(%{
  provider: "stripe",
  tenant: site.id,
  payment_id: "pi_...",
  amount: %{amount: "5", currency: "USD"},
  reference: "refund-1"
})

Set the value in your keys plugin. See Keys and options.

Answer a dispute

A dispute is a chargeback: the buyer's bank asks for the money back. The payment reads disputed: true, and the charge.dispute.* webhooks keep the dispute current.

elixir
{:ok, dispute} =
  MishkaPay.fetch_dispute("stripe", "du_...", site.id)

MishkaPay.update_dispute(%{
  provider: "stripe",
  tenant: site.id,
  dispute_id: dispute.id,
  evidence: %{
    "product_description" =>
      "Elixir ebook, delivered by email",
    "customer_email_address" => "[email protected]"
  },
  submit: true
})

MishkaPay.accept_dispute("stripe", dispute.id, site.id)
  • Evidence uses Stripe's own field names, such as "product_description" and "uncategorized_text".
  • File fields ("receipt", "customer_communication", "uncategorized_file" and others) take only a file id. Upload with upload_file/1. Evidence files are PDF, JPEG or PNG up to 5 MB, and a file id works in one request only.
  • Answer before evidence_due_by. Take back access while a payment is disputed by listening to mishka_pay:dispute:changed.
  • An early fraud warning (list_fraud_warnings/3) is a card issuer's heads-up. While its :actionable is true, a full refund can usually stop the dispute and its fee.

Next steps