# OuiPay Developer Documentation

> Official OuiPay developer documentation: API reference, webhooks, idempotency, transaction lifecycle, payments, transfers, and exchange.

OuiPay is a payment institution technology platform. The OuiPay REST API allows developers to accept payments, execute money transfers, manage multi-currency wallet balances, and issue virtual cards backed by an immutable double-entry ledger.

## API Conventions & Protocol

- **Base URL**: `https://api.ouipay.africa/v1`
- **Authentication**: `Authorization: Bearer sk_live_...`
- **Identifier Format**: ULIDs (e.g., `01M2S17G4A0N9MDMXYSCCX8SPS`)
- **Money Safety**: Integer minor units + ISO 4217 currency code (e.g. `100000 NGN` = ₦1,000.00)
- **Idempotency**: `Idempotency-Key` header required on all money-moving POST requests
- **Error Structure**: Standard JSON payload `{"error": {"code": "...", "message": "...", "request_id": "..."}}`

## AI Documentation Context

- [Markdown Documentation Context](https://developer.ouipay.africa/llms.txt): Machine-readable documentation index for LLM agents.

## Overview

- [OuiPay Documentation](https://developer.ouipay.africa/docs): Build payments, transfers, exchange, and bill services into your product with the OuiPay REST API.

## errors

- [API Error Codes](https://developer.ouipay.africa/docs/errors/api-error-codes): Every error code, its HTTP status, and what to do about it.
- [HTTP Status Codes](https://developer.ouipay.africa/docs/errors/http-status-codes): What each HTTP status code means in the OuiPay API and how to handle it.
- [Troubleshooting](https://developer.ouipay.africa/docs/errors/troubleshooting): Common integration issues, debugging steps, and how to get support.

## Getting Started

- [API Credentials](https://developer.ouipay.africa/docs/getting-started/api-credentials): Obtain and manage your API keys for sandbox and production environments.
- [Authentication](https://developer.ouipay.africa/docs/getting-started/authentication): How to authenticate API requests with secret keys.
- [First Request](https://developer.ouipay.africa/docs/getting-started/first-request): Create a customer and a transaction in under five minutes.
- [Test Transaction](https://developer.ouipay.africa/docs/getting-started/test-transaction): Run a complete sandbox transaction, from customer creation to webhook confirmation.

## Guides

- [Accept Payments](https://developer.ouipay.africa/docs/guides/accept-payments): End-to-end collection flow : methods, initiate, authorize, confirm via webhook.
- [Cross-Border Transfers](https://developer.ouipay.africa/docs/guides/cross-border-transfers): Sending money across currencies : quote, exchange, payout in one flow.
- [Handle Webhooks](https://developer.ouipay.africa/docs/guides/handle-webhooks): Receive, verify, and process OuiPay events safely.
- [Implement Idempotency](https://developer.ouipay.africa/docs/guides/implement-idempotency): How to safely send mutation requests with Idempotency-Key header to prevent double-charging or duplicate payouts.
- [Pay Bills and Top Up](https://developer.ouipay.africa/docs/guides/pay-bills): End-to-end service purchase : catalogue, validate, quote, order, fulfilment webhook.
- [Send Money](https://developer.ouipay.africa/docs/guides/send-money): Payouts : create a beneficiary, submit a transfer, track hold lifecycle, and confirm via webhook.

## Introduction

- [Base URLs & Environments](https://developer.ouipay.africa/docs/introduction/base-urls): API base URLs, sandbox vs live environments, and versioning policy.
- [How the API Works](https://developer.ouipay.africa/docs/introduction/how-it-works): The request pipeline from your API call to ledger posting and webhook delivery.
- [Introduction](https://developer.ouipay.africa/docs/introduction): What OuiPay is, what the API covers, and how the platform is organized.

## Resources

- [Changelog](https://developer.ouipay.africa/docs/resources/changelog): API changes, deprecations, and version history.
- [OpenAPI Specification](https://developer.ouipay.africa/docs/resources/openapi): Download and inspect the official OpenAPI 3.0 specification for the OuiPay API.
- [Postman Collection](https://developer.ouipay.africa/docs/resources/postman): Import the official OuiPay Postman collection and pre-configured environment.

## transactions

- [Idempotency](https://developer.ouipay.africa/docs/transactions/idempotency): Safe retries for money-moving requests : keys, replay, and what "safe" means.
- [Transaction Lifecycle](https://developer.ouipay.africa/docs/transactions/lifecycle): How every money-moving attempt becomes a durable record, from request to settlement.
- [Requery](https://developer.ouipay.africa/docs/transactions/requery): Query a transaction's current status when you need a synchronous check.
- [Transaction Statuses](https://developer.ouipay.africa/docs/transactions/statuses): Every transaction status, its meaning, the webhook it fires, and what to do about it.

## webhooks

- [Webhook Events](https://developer.ouipay.africa/docs/webhooks/events): The full event catalogue, payload shapes, and when each event fires.
- [Webhooks](https://developer.ouipay.africa/docs/webhooks): Signed event delivery for transaction state changes. Subscribe, verify, and process events.
- [Retry Policy](https://developer.ouipay.africa/docs/webhooks/retry-policy): How OuiPay retries failed webhook deliveries, backoff timing, and auto-disable behavior.
- [Webhook Security](https://developer.ouipay.africa/docs/webhooks/security): Signing secrets, timestamp replay protection, IP allowlisting, and secret rotation.
- [Webhook Verification](https://developer.ouipay.africa/docs/webhooks/verification): Verify webhook signatures before processing any event. HMAC-SHA256, timestamp checks, and implementation examples.

## API Reference

- [Authentication](https://developer.ouipay.africa/docs/api-reference/authentication): How every endpoint authenticates : bearer keys, headers, and scopes.
- [Create a beneficiary](https://developer.ouipay.africa/docs/api-reference/beneficiaries/create-beneficiary): POST /v1/beneficiaries : register and verify a payout destination.
- [Beneficiaries](https://developer.ouipay.africa/docs/api-reference/beneficiaries/overview): The beneficiary resource : verified payout destinations.
- [Country context](https://developer.ouipay.africa/docs/api-reference/countries/country-context): GET /v1/countries/{code}/context : boot context for one country.
- [List countries](https://developer.ouipay.africa/docs/api-reference/countries/list-countries): GET /v1/countries : enabled countries and their capability flags.
- [Countries](https://developer.ouipay.africa/docs/api-reference/countries/overview): The country model : home country vs service country, and the public country catalogue.
- [Create a customer](https://developer.ouipay.africa/docs/api-reference/customers/create-customer): POST /v1/customers : register a new customer.
- [Customers](https://developer.ouipay.africa/docs/api-reference/customers/overview): The customer resource : the identity that owns wallets and transacts.
- [Retrieve a customer](https://developer.ouipay.africa/docs/api-reference/customers/retrieve-customer): GET /v1/customers/{id} : fetch a customer by id.
- [Update a customer](https://developer.ouipay.africa/docs/api-reference/customers/update-customer): PATCH /v1/customers/{id} : update mutable customer fields.
- [Create a quote](https://developer.ouipay.africa/docs/api-reference/exchange/create-quote): POST /v1/exchange/quotes : lock an exchange rate for a short window.
- [Execute an exchange](https://developer.ouipay.africa/docs/api-reference/exchange/execute-exchange): POST /v1/exchange : convert currency using a quoted rate.
- [Exchange](https://developer.ouipay.africa/docs/api-reference/exchange/overview): The exchange resource : currency conversion with quoted rates.
- [Create a payment](https://developer.ouipay.africa/docs/api-reference/payments/create-payment): POST /v1/payments : initiate a collection on a resolved method.
- [Payments](https://developer.ouipay.africa/docs/api-reference/payments/overview): The payment resource : collecting funds with a resolved method.
- [Retrieve a payment](https://developer.ouipay.africa/docs/api-reference/payments/retrieve-payment): GET /v1/payments/{id} : fetch a payment's current state.
- [Create a service order](https://developer.ouipay.africa/docs/api-reference/services/create-order): POST /v1/services/orders : place the purchase and start collection.
- [Create a quote](https://developer.ouipay.africa/docs/api-reference/services/create-quote): POST /v1/services/quote : lock the customer price, fee, and FX for a service purchase.
- [List services](https://developer.ouipay.africa/docs/api-reference/services/list-services): GET /v1/services : the service catalogue for a country.
- [Services](https://developer.ouipay.africa/docs/api-reference/services/overview): Bill payments, airtime, data, and utility purchases through one order API.
- [Retrieve a service order](https://developer.ouipay.africa/docs/api-reference/services/retrieve-order): GET /v1/services/orders/{id} : order detail and compact status polling.
- [Service definition](https://developer.ouipay.africa/docs/api-reference/services/service-definition): GET /v1/services/{serviceCode} : form schema, limits, and country context for one service.
- [Service options](https://developer.ouipay.africa/docs/api-reference/services/service-options): Operators, plans, and variants : the selectable catalogues behind a service.
- [Supported networks](https://developer.ouipay.africa/docs/api-reference/services/supported-networks): Operators per service and market : networks, billers, and exam bodies you can sell.
- [Validate a recipient](https://developer.ouipay.africa/docs/api-reference/services/validate-account): POST /v1/services/{serviceCode}/validate : verify a meter, smartcard, or account before quoting.
- [Cancel a transaction](https://developer.ouipay.africa/docs/api-reference/transactions/cancel-transaction): POST /v1/transactions/{id}/cancel : cancel a pending transaction.
- [Create a transaction](https://developer.ouipay.africa/docs/api-reference/transactions/create-transaction): POST /v1/transactions : record a money-moving attempt.
- [Transactions](https://developer.ouipay.africa/docs/api-reference/transactions/overview): The transaction resource : every money-moving attempt as a durable entry.
- [Retrieve a transaction](https://developer.ouipay.africa/docs/api-reference/transactions/retrieve-transaction): GET /v1/transactions/{id} : fetch a transaction and its failure details.
- [Retry a transaction](https://developer.ouipay.africa/docs/api-reference/transactions/retry-transaction): POST /v1/transactions/{id}/retry : retry a failed transaction.
- [Create a transfer](https://developer.ouipay.africa/docs/api-reference/transfers/create-transfer): POST /v1/transfers : submit a payout to a beneficiary.
- [Transfers](https://developer.ouipay.africa/docs/api-reference/transfers/overview): The transfer resource : payouts to beneficiaries.
- [Retrieve a transfer](https://developer.ouipay.africa/docs/api-reference/transfers/retrieve-transfer): GET /v1/transfers/{id} : fetch a transfer's current state.
- [Wallets](https://developer.ouipay.africa/docs/api-reference/wallets/overview): The wallet resource : currency-specific balances, holds, and funding.
- [Retrieve a wallet](https://developer.ouipay.africa/docs/api-reference/wallets/retrieve-wallet): GET /v1/wallets/{id} : fetch a wallet's balance, available funds, and holds.