# Refund a payment

> Everything needed to refund a completed payment through One API, in full or in part, and to handle the statuses a refund moves through.

A refund is its own transaction with its own lifecycle, not a reversal of the
original one. It is submitted against a completed payment, it can be for less
than the full amount, and it settles on its own schedule.

**Refunds reuse status names that also appear on payins and mean something
different there.** A system that reads a refund's status as though it were a
payin's reports the wrong outcome to a customer. Handle every refund status the
statuses page lists.

## What this was built from

- Ozow Hub, commit `e0b2a572`
- `one-api` version 1.0, OpenAPI document: https://hub.ozow.com/api-reference/specs/one-api.yaml
- Build against `https://one.ozow.com/v1` for `one-api`
- 8 pages, 11 operations
- Everything below inlined in one document: https://hub.ozow.com/bundles/refund-a-payment-full.md

## Implement against these

Every field name, order and format on these pages is exact.

- [Refund a payment](https://hub.ozow.com/integration-methods/apis/refunds/refund-a-payment.md): Issue a refund with One API. Refunds are merchant-initiated backend operations with no customer-facing step, so the whole flow is in your backend.
- [Verify a webhook signature](https://hub.ozow.com/integration-methods/apis/payin/verify-a-webhook.md): The signature on a One API webhook, the five steps that check it, and a working implementation in four languages.

## Background

Context for the above. Nothing here is implemented against.

- [How Ozow works](https://hub.ozow.com/getting-started.md): How Ozow connects you to South African banks and payment methods, and the two directions money moves: payins from customers, payouts to recipients.
- [Prerequisites and onboarding](https://hub.ozow.com/getting-started/prerequisites-and-onboarding.md): What to have in place before you write any code: a merchant account, Dashboard access, your credentials, and payout eligibility if you need it.
- [Refunds](https://hub.ozow.com/payment-products/refunds.md): Returning money to a customer through Ozow.
- [Float top-up guide](https://hub.ozow.com/payment-products/settlements-and-float/float-top-up.md): Payouts and refunds are funded from your float balance. Set up your static top-up reference once, then load funds whenever your float runs low.
- [Transaction and settlement statuses](https://hub.ozow.com/integration-methods/statuses.md): Every payin, payout, refund and settlement status, which are final, and what to do about each.
- [Building a secure integration](https://hub.ozow.com/getting-started/building-a-secure-integration.md): Where Ozow's security responsibility ends and yours begins: credentials, webhook endpoints, verifying notifications, and validating amounts.

## The contract

Fetch the OpenAPI document named above to generate a client, or to check a field name or an enum against the schema.

- [one-api#get-/refunds](https://hub.ozow.com/api-reference/one-api/get-refunds.md)
- [one-api#get-/refunds/{id}](https://hub.ozow.com/api-reference/one-api/get-refunds-id.md)
- [one-api#get-/transactions/{id}/refunds](https://hub.ozow.com/api-reference/one-api/get-transactions-id-refunds.md)
- [one-api#get-/webhooks/{id}/secret](https://hub.ozow.com/api-reference/one-api/get-webhooks-id-secret.md)
- [one-api#post-/refunds](https://hub.ozow.com/api-reference/one-api/post-refunds.md)
- [one-api#post-/refunds/{id}/cancel](https://hub.ozow.com/api-reference/one-api/post-refunds-id-cancel.md)
- [one-api#post-/token](https://hub.ozow.com/api-reference/one-api/post-token.md)
- [one-api#post-/transactions/{id}/refunds](https://hub.ozow.com/api-reference/one-api/post-transactions-id-refunds.md)
- [one-api#schema/WebhookEnvelope](https://hub.ozow.com/api-reference/one-api/schemas/webhook-envelope.md)
- [one-api#webhook/refund.complete](https://hub.ozow.com/api-reference/one-api/webhooks/refund-complete.md)
- [one-api#webhook/transaction.complete](https://hub.ozow.com/api-reference/one-api/webhooks/transaction-complete.md)