Accept Payments

The full payment collection flow from resolving methods to webhook settlement confirmation.

Payment sequence flow

sequenceDiagram
    autonumber
    participant Customer as Customer Browser/App
    participant Merchant as Merchant Backend
    participant OuiPay as OuiPay API
    participant Provider as Provider (Card/Momo/Bank)

    Customer->>Merchant: Initiate Checkout
    Merchant->>OuiPay: GET /v1/payments/methods?customer_id=...
    OuiPay-->>Merchant: Available payment methods
    Merchant-->>Customer: Display method options
    Customer->>Merchant: Select card & click Pay
    Merchant->>OuiPay: POST /v1/payments (Idempotency-Key: checkout_8842)
    OuiPay-->>Merchant: 201 Created (status: pending, redirect_url)
    Merchant-->>Customer: Redirect to 3DS / Provider URL
    Customer->>Provider: Authorize Payment
    Provider-->>OuiPay: Provider Webhook Callback
    OuiPay->>OuiPay: Ledger Credit & Status → completed
    OuiPay->>Merchant: Webhook (payment.completed)
    Merchant->>Merchant: Verify signature & Fulfill order

1. Resolve methods

Query available payment methods for the customer:

curl https://api.ouipay.com/v1/payments/methods?customer_id=01M2S17... \
  -H "Authorization: Bearer sk_test_..."

2. Initiate the payment

curl https://api.ouipay.com/v1/payments \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: checkout-8842" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "01M2S17...",
    "amount_minor": 50000,
    "currency": "NGN",
    "method": "card",
    "reference": "order-8842"
  }'

3. Complete authorization

Depending on method:

card: response includes provider.redirect_url; send the customer there to complete capture.
bank_transfer: customer transfers funds to their virtual account; inbound credit confirms payment.
mobile_money: STK push prompt sent to customer phone.
wallet: immediate wallet debit; completed synchronously.

4. Receive the webhook

When provider completes authorization, OuiPay posts payment.completed:

{
  "event_type": "payment.completed",
  "event_key": "payment.completed:01M2S18...",
  "data": {
    "transaction_id": "01M2S18...",
    "status": "completed",
    "amount_minor": 50000,
    "currency": "NGN",
    "reference": "order-8842"
  }
}

Always verify signature before marking orders paid.

Failure modes to expect

`failure.code`	Cause	Your move
`INSUFFICIENT_FUNDS`	Wallet/funding short	Prompt for another method
`COMPLIANCE_DENIED`	Screening block	Surface as unrecoverable
`LIMIT_EXCEEDED`	KYC/tier limit	Prompt for verification
`PROVIDER_ERROR`	Upstream failure	Retry-safe via idempotency
`METHOD_NOT_SELECTABLE`	Method not enabled for customer	Re-resolve methods