Refunds
Refund a captured Cardencer payment, fully or partially, from the API or the dashboard, and track the refund status.
A refund returns money that has already been captured. If a payment is still authorized and waiting for capture, cancel it instead, or capture it first.
You can refund from Refunds in the dashboard, or with the API.
Create a refund#
POST /refunds with the payment_id. Omit amount to refund everything still refundable; pass it for a partial refund.
curl https://sandbox.cardencer.com/refunds \
-H "api-key: $CARDENCER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
"amount": 500,
"reason": "Customer returned the item",
"metadata": { "order_reference": "58211" }
}'const refund = await fetch("https://sandbox.cardencer.com/refunds", {
method: "POST",
headers: { "api-key": process.env.CARDENCER_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
payment_id: "pay_mbabizu24mvu3mela5njyhpit4",
amount: 500,
reason: "Customer returned the item",
metadata: { order_reference: "58211" },
}),
}).then((r) => r.json());
console.log(refund.refund_id, refund.status);refund = requests.post(
"https://sandbox.cardencer.com/refunds",
headers={"api-key": os.environ["CARDENCER_API_KEY"]},
json={
"payment_id": "pay_mbabizu24mvu3mela5njyhpit4",
"amount": 500,
"reason": "Customer returned the item",
"metadata": {"order_reference": "58211"},
},
).json()
print(refund["refund_id"], refund["status"])| Field | Required | Description |
|---|---|---|
payment_id |
Yes | The payment to refund. |
amount |
No | Amount in minor units. Omit for a full refund. |
refund_id |
No | Your own unique ID for this refund. Cardencer generates one if omitted. Reusing an ID is rejected, which protects you from double refunds on retries. |
reason |
No | Free text, stored on the refund. |
metadata |
No | Your own key/value data. |
The response contains refund_id, payment_id, amount, currency, status, reason and metadata.
How much you can refund#
refundable = amount_captured − sum of previous refunds that did not fail- You can make several partial refunds until the captured amount is used up.
- The limit is what you captured, not what you authorized: after a partial capture, you can refund only the captured part.
- A payment is refundable when its status is
succeededorpartially_captured. - Failed refunds do not consume the refundable amount.
- Request refunds within 365 days of the payment's creation date.
Refund statuses#
| Status | Meaning |
|---|---|
pending |
Sent, waiting for the final outcome from the acquirer. |
succeeded |
The refund went through. |
failed |
The refund did not go through. You can retry. |
review |
The refund needs manual review. Cardencer support will follow up. |
The create response may already be succeeded; otherwise it is pending. Track it with the refund_succeeded and refund_failed webhooks, or retrieve it:
curl https://sandbox.cardencer.com/refunds/ref_mbabizu24mvu3mela5njyhpit4 \
-H "api-key: $CARDENCER_API_KEY"const refund = await fetch(`https://sandbox.cardencer.com/refunds/${refundId}`, {
headers: { "api-key": process.env.CARDENCER_API_KEY },
}).then((r) => r.json());refund = requests.get(
f"https://sandbox.cardencer.com/refunds/{refund_id}",
headers={"api-key": os.environ["CARDENCER_API_KEY"]},
).json()When the customer sees the money#
A succeeded refund has left Cardencer. It usually appears on the customer's statement within 5 to 10 business days, depending on their bank.
List refunds#
curl https://sandbox.cardencer.com/refunds/list \
-H "api-key: $CARDENCER_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "payment_id": "pay_mbabizu24mvu3mela5njyhpit4" }'See the Refunds API reference for every field.