Ozow Hub

Migrate a payin from the Payments API to One API

Everything needed to move an existing redirect payin 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 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. and its One API counterpart. Start with the migration guide, which maps the field names across, then read the two redirect guides beside each other.

Six changes, in the order the guide takes them: the hash gives way to 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, flat fields become nested resources, the response carries a URL to redirect to rather than a form to post, the per-request notifyUrl becomes one 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. subscription with a Svix signature, the statuses re-map, and refunds move. Refunds are a separate package, migrate-refunds-to-one-api.

SelectedBankId on the Payments API is institutionId on One API. The same UUIDUUID A 128-bit identifier written as 36 characters, such as 497f6eca-6276-4993-bfeb-53cbbbba6f08. Generated rather than assigned in sequence, so two systems can create identifiers without coordinating.Wikipedia identifies the same bank on both.

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 redirect 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. and refunds integration from the Payments API to One API: what changes, what does not, and the order to make the changes in.
  • Redirect to Ozow: Build a redirect payin on the Payments API, the legacy path. Post the payment, redirect the customer, and handle the notification response.
  • Redirect to Ozow: Build a redirect payin with One API. Create a payment request, send the customer to Ozow's hosted page, and confirm the result from the webhook.
  • Verify a webhook signature: 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.

  • 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.
  • Hash calculator: Work out the hashCheck a request carries, and see the exact string it is computed from.
  • Payment method identifiers: The UUID for each payment method Ozow supports, for the fields that take one.
  • 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.