# 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.

Both sides are implemented against: the legacy redirect 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
token, 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
webhook 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
UUID 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

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

## Implement against these

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

- [Migrating to One API](https://hub.ozow.com/integration-methods/apis/deprecated-integrations/migrating-to-one-api.md): Map a redirect payin 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](https://hub.ozow.com/integration-methods/apis/deprecated-integrations/redirect-to-ozow.md): 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](https://hub.ozow.com/integration-methods/apis/payin/redirect-to-ozow.md): 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](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.

- [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.
- [Hash calculator](https://hub.ozow.com/integration-methods/apis/deprecated-integrations/hash-calculator.md): Work out the hashCheck a request carries, and see the exact string it is computed from.
- [Payment method identifiers](https://hub.ozow.com/integration-methods/apis/payin/payment-method-ids.md): The UUID for each payment method Ozow supports, for the fields that take one.
- [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.

## 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-/payments/{id}/transactions](https://hub.ozow.com/api-reference/one-api/get-payments-id-transactions.md)
- [one-api#get-/webhooks](https://hub.ozow.com/api-reference/one-api/get-webhooks.md)
- [one-api#get-/webhooks/{id}/secret](https://hub.ozow.com/api-reference/one-api/get-webhooks-id-secret.md)
- [one-api#post-/payments](https://hub.ozow.com/api-reference/one-api/post-payments.md)
- [one-api#post-/payments/{id}/cancel](https://hub.ozow.com/api-reference/one-api/post-payments-id-cancel.md)
- [one-api#post-/token](https://hub.ozow.com/api-reference/one-api/post-token.md)
- [one-api#post-/webhooks](https://hub.ozow.com/api-reference/one-api/post-webhooks.md)
- [one-api#schema/TransactionCompleteFullData](https://hub.ozow.com/api-reference/one-api/schemas/transaction-complete-full-data.md)
- [one-api#schema/WebhookEnvelope](https://hub.ozow.com/api-reference/one-api/schemas/webhook-envelope.md)
- [one-api#schema/WebhookEventData](https://hub.ozow.com/api-reference/one-api/schemas/webhook-event-data.md)
- [one-api#tag/webhooks](https://hub.ozow.com/api-reference/one-api/tags/webhooks.md)
- [one-api#webhook/transaction.complete](https://hub.ozow.com/api-reference/one-api/webhooks/transaction-complete.md)
- [payments-api#get-/GetTransaction](https://hub.ozow.com/api-reference/payments-api/get-get-transaction.md)
- [payments-api#get-/GetTransactionByReference](https://hub.ozow.com/api-reference/payments-api/get-get-transaction-by-reference.md)
- [payments-api#post-/postpaymentrequest](https://hub.ozow.com/api-reference/payments-api/post-post-payment-request.md)
- [payments-api#webhook/transactionNotification](https://hub.ozow.com/api-reference/payments-api/webhooks/transaction-notification.md)