Refunds

Overview

Refunds return money to the original payment method. For card payments, the refund appears on the customer's card statement within 5–10 business days. For mobile money and bank transfers, it arrives within 1–2 business days.

Create a refund

// Full refund
const refund = await xtopay.refunds.create({
  payment_id: "pay_abc123",
  reason: "customer_request",
});

// Partial refund
const refund = await xtopay.refunds.create({
  payment_id: "pay_abc123",
  amount: 2500,  // must be ≤ remaining refundable amount
  reason: "order_partially_cancelled",
});

Refund object

{
  "id": "ref_a1b2c3",
  "payment_id": "pay_abc123",
  "amount": 5000,
  "currency": "GHS",
  "status": "succeeded",
  "reason": "customer_request",
  "created_at": "2026-05-24T12:00:00Z",
  "processed_at": "2026-05-24T12:00:04Z"
}

Refund status

Status	Meaning
`pending`	Refund queued
`processing`	Sent to payment network
`succeeded`	Money returned to customer
`failed`	Refund rejected — contact support

Reasons

Reason	Description
`customer_request`	Customer asked for a refund
`duplicate`	Payment was charged twice
`fraudulent`	Suspected fraudulent transaction
`order_partially_cancelled`	Part of an order was cancelled
`other`	Any other reason

Restrictions

Only succeeded payments can be refunded
You can issue multiple partial refunds up to the original amount
Refunds must be issued within 180 days of the original payment
Refunds cannot be cancelled once initiated

Webhook events

Event	Fired when
`refund.created`	Refund is initiated
`refund.succeeded`	Money returned to customer
`refund.failed`	Refund could not be processed