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: :manualfor holds. See Take a one-time payment. - A provider with the
:refundcapability. 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.
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.Invalidon:amount. cancel_payment/3lets 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: :manualwithinvoice: trueormerchant_of_record: trueisErrors.Invalidon:capture. If the Stripe account's default is Managed Payments, sendmerchant_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
MishkaPay.refund(%{
provider: "stripe",
tenant: site.id,
payment_id: "pi_...",
amount: %{amount: "5", currency: "USD"},
reason: :requested_by_customer
})- Leave
amountout to refund the whole payment. reasonis:requested_by_customer,:duplicateor:fraudulent. Stripe blocks the card in the account's Radar after a:fraudulentrefund, so use it only for real fraud.- The answer is a
%MishkaPay.Refund{}. Read one again withfetch_refund/3, or list a payment's refunds withlist_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.:manyallows part refunds until the payment is used up. Each one needs its ownreference:.
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.
{: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 withupload_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 tomishka_pay:dispute:changed. - An early fraud warning (
list_fraud_warnings/3) is a card issuer's heads-up. While its:actionableis true, a full refund can usually stop the dispute and its fee.
Next steps
- Receive and verify webhooks: refunds and disputes change a payment after your call returns.
- Errors and telemetry: what
RejectedandInvalidmean on a refund. - Test code that takes payments: the test card that opens a dispute.