Refund a payment

Refund a settled payment to the original payer's bank account or to a wallet.

POST/v1/payments/:id/refund
Idempotentpayment

Refunds a settled payment, to either the original payer's bank account or a wallet. Bank refunds are asynchronous (a refund.completed / refund.failed webhook resolves them); wallet refunds settle immediately. Requires an Idempotency-Key. The path :id is the payment.

Try it, for realPOST /payments/:id/refundscope: payment

Test keys only. Never paste a live key. Your key is stored only in this browser (localStorage) and sent only to the same-origin playground proxy.

›Equivalent request (curl / TypeScript)
curl
curl -X POST https://sandbox.api.acute.network/v1/payments/acuinf208844190037pay/refund \
  -H "Authorization: Bearer acuinf_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: …" \
  -d '{"destination":"bank"}'
TypeScript
const res = await fetch("https://sandbox.api.acute.network/v1/payments/acuinf208844190037pay/refund", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ACUTE_TEST_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({"destination":"bank"}),
});
const { data, meta } = await res.json();

# full bank refund to the original payer
curl -X POST https://sandbox.api.acute.network/v1/payments/acuinf208844190037pay/refund \
  -H "Authorization: Bearer acuinf_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b8d1f02-3a4c-4e6d-9f01-2a3b4c5d6e7f" \
  -d '{ "destination": "bank" }'
{
  "success": true,
  "statusCode": 201,
  "data": {
    "id": "acuinf330591472680rfd",
    "paymentId": "acuinf208844190037pay",
    "amount": 250000,
    "destination": "bank",
    "status": "processing",
    "failureReason": null,
    "currency": "NGN",
    "createdAt": "2026-06-24T10:02:18.300Z",
    "completedAt": null
  },
  "meta": { "requestId": "req_4f9c2a7e1b0d8c3a5e6f10a2" }
}

Only settled payments are refundable

A payment must have received money before you can refund it - refunding a pending / expired payment returns 422 (REFUND_PAYMENT_NOT_SETTLED). For wallet refunds, remember destinationWalletId is required.

idstringpathrequired

The payment reference to refund.

destination'bank' | 'wallet'bodyrequired

Where the money goes. bank returns to the original payer; wallet credits an Acute wallet.

amountinteger (kobo)bodyoptional

Amount to refund, in kobo. Defaults to the full received amount minus prior refunds. Exceeding what's refundable returns 422 (REFUND_AMOUNT_EXCEEDS).

destinationWalletIdstringbodyoptional

Required when destination is wallet - the wallet reference to credit. Omitting it for a wallet refund fails validation.

idstringrequired

The refund reference (acuinf…rfd).

paymentIdstringrequired

The payment being refunded.

amountnumber (kobo)required

The refunded amount.

destination'bank' | 'wallet'required

Where the refund went.

status'processing' | 'completed' | 'failed'required

wallet refunds complete synchronously; bank refunds start processing and resolve via webhook.

failureReasonstring | nullrequired

Populated when status is failed.

currencystringrequired

The currency (NGN).

createdAtstringrequired

ISO-8601 timestamp.

completedAtstring | nullrequired

Set when the refund resolves; null while processing.