# Take a payment

> Everything needed to take a payment end to end with One API, from credentials through the hosted page to the webhook that confirms it, and the test cases that prove each outcome before you go live.

Your system asks One API for a payment, sends the customer to Ozow's hosted
page, and learns the outcome from a webhook, not from the redirect back.
Implement the pages in the order above.

**One API only.** The Payments API is a separate contract, receives no new
features, and has its own package, `migrate-a-payin-to-one-api`. One API
authenticates
with a bearer token and signs each webhook with a Svix signature. It uses no
hash at all, so computing one means you are on the wrong contract.

**Pay by Bank is what this package takes a payment with.** It is enabled on
every account by default and needs no opt-in, so it is the method a first
integration meets. Card, vouchers, PayShap, crypto and buy now pay later are
opt-ins that arrive on the same request once Ozow enables them, which is why
there is one integration here rather than one per method.

**The webhook is the outcome and the redirect is not.** A customer who closes
the tab must still end up with the right order state. Verify the signature
before acting on a delivery.

Handle every status the statuses page lists. The test cases cover a successful
payment, a cancellation, a failure, a duplicate notification and a status check
against the API.

Build against production. Staging has separate credentials and its own
hostname. Payins can be tested in production.

## 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`
- 11 pages, 11 operations
- Everything below inlined in one document: https://hub.ozow.com/bundles/take-a-payment-full.md

## Implement against these

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

- [Quick start: accept your first payment](https://hub.ozow.com/getting-started/quick-start.md): Accept your first Ozow payment with One API. Get a token, create a payment request, redirect the customer, and read the webhook that confirms it.
- [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.
- [Payin test cases](https://hub.ozow.com/integration-methods/testing/payin-test-cases-one-api.md): The payments to run before you go live with Ozow, what each one delivers, and a handler that survives all of them.

## 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.
- [Pay by Bank](https://hub.ozow.com/payment-products/payin/pay-by-bank.md): The payer authorises the payment directly from their bank account.
- [Choosing a checkout experience](https://hub.ozow.com/integration-methods/apis/payin.md): Where your customer pays decides how much you build and whether you take on PCI DSS scope. Compare redirect, embedded and server to server.
- [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.
- [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-/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#webhook/transaction.complete](https://hub.ozow.com/api-reference/one-api/webhooks/transaction-complete.md)
