Ozow Hub

Migrate refunds from the Payments API to One API

Everything needed to move an existing refunds integration onto One API, with the legacy guide and its One API counterpart side by side.

On this page4 sections
Markdown, linkedMarkdown, everything inlined

Both sides are implemented against: the legacy refunds endpoints and their One API counterparts. Read Step 6 of the migration guide, which maps them, then the two refund guides beside each other.

Authentication and the notification change with the rest of the integration, so read the payinPayin A payment made by a consumer to a merchant. The direction most of this site is about: money coming in. Its counterpart is a payout, which sends money out and is not tied to any payment anyone made you. package first if you have not moved that yet: a refund on One API needs a bearer tokenBearer token An access token sent in the Authorization header as Authorization: Bearer <token>. Anyone holding the token can use it, which is why it belongs on your server and never in a browser or a mobile app.RFC 6750 and a verified Svix signature, and the endpoints changed shape at the same time.

Refunds are funded from your floatFloat The balance held with Ozow that payouts and refunds are paid out of. Both draw on it, and neither will process while it is empty. Payins do not need one, so if you only take payments you never meet it. balance on both APIs. A refund above that balance fails rather than queueing.

Refund statuses reuse names that also appear on payins and mean something different there. Handle every refund status the statuses page lists.

Test and live are separated by environment, not by a flag on the request.

What this was built from

Implement against these

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

  • Migrating to One API: Map a redirectRedirect Sending the payer to the Ozow payment page to complete the payment, and returning them to your site afterwards. The alternative is embedding the checkout in your own page, where the payer never leaves it. payin and refunds integration from the Payments API to One API: what changes, what does not, and the order to make the changes in.
  • Refund a payment: Issue a refund on the Payments API, the legacy path. Refunds are merchant-initiated backend operations, funded from your float balance.
  • Refund a payment: 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: The signature on a One API webhookWebhook A URL of yours that Ozow calls when something happens, rather than you polling to find out. The call carries no credential of yours and arrives at a public URL, so authenticate it before acting on it: a hash field on the Payments API, a Svix signature on One API., the five steps that check it, and a working implementation in four languages.

Background

Context for the above. Nothing here is implemented against.

  • Prerequisites and onboarding: What to have in place before you write any code: a merchant account, Dashboard access, your credentials, and payoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. eligibility if you need it.
  • Float top-up guide: 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: Every payin, payout, refund and settlementSettlement Ozow paying the money you have collected into your bank account. Payins arrive at Ozow first and are settled to you on a schedule, so what a customer paid you today and what has been settled to you today are different amounts. status, which are final, and what to do about each.

The contract

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