AI Integration Prompt

You are an expert developer helping me integrate NabooPay into my application.

NabooPay is a payment API for West Africa (XOF currency) supporting Wave and Orange Money.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 NABOOPAY API — v2 REFERENCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Base URL:   https://api.naboopay.com
Auth:       Authorization: Bearer {API_KEY}
Currency:   XOF (CFA Franc)
Rate limit: 100 req / 60 s (global)
            2 payouts per recipient phone / 5 min → 409 if exceeded

API KEY SCOPES — your key must carry the right scope or you get 403:
  checkout   → create/read/cancel transactions, process refunds
  read       → read-only access to transactions, payouts, accounts
  write      → create and cancel transactions
  read_write → full read + write on transactions
  payout     → create and read payouts
  management → full admin access, refunds, accounts

── 1. CREATE TRANSACTION (collect payment from customer)
POST /api/v2/transactions
Required scope: checkout | write | read_write
Body:
{
  "method_of_payment": ["wave", "orange_money"],  // required — at least one
  "products": [
    { "name": "...", "price": 5000, "quantity": 1, "description": "..." }
  ],
  "customer": {                  // REQUIRED
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+221771234567"
  },
  "success_url": "https://your-site.com/success",
  "error_url":   "https://your-site.com/error",
  "fees_customer_side": false,   // true = fees added to customer total
                                 // false = fees deducted from your payout
  "is_escrow": false,            // true = hold funds until you release them
  "is_merchant": false
}
Returns: { checkout_url, order_id, amount, transaction_status, customer, ... }
→ Redirect the customer to checkout_url to complete payment.

── 2. GET TRANSACTION
GET /api/v2/transactions/{order_id}
Required scope: checkout | read | read_write
Returns transaction with status: pending | paid | paid_and_blocked | refunded | cancelled

── 3. LIST TRANSACTIONS
GET /api/v2/transactions?page=1&limit=20&status=paid
Required scope: checkout | read | read_write
Filters: status, payment_method, min_amount, max_amount, start_date, end_date,
         customer_phone, is_escrow, is_merchant, include_deleted, search

── 4. CANCEL TRANSACTION
DELETE /api/v2/transactions/{order_id}
Required scope: checkout | write | read_write
Only cancels PENDING (unpaid) transactions.
To refund a paid transaction use endpoint 5 below.

── 5. REFUND TRANSACTION
GET /api/v2/refund/{order_id}          ← GET verb is intentional
Required scope: checkout | write | read_write | management
Requirements:
- Transaction must be in 'paid' or 'paid_and_blocked' status
- Your account must have sufficient balance
- Full refund only — partial refunds not supported
- Supported methods: wave, orange_money

── 6. CREATE PAYOUT (send money to a recipient)
POST /api/v2/payouts
Required scope: payout
Body:
{
  "selected_payment_method": "wave",   // "wave" or "orange_money"
  "amount": 10000,                     // XOF, min 11
                                       // > 2,000,000 → manual review, status = "pending"
  "recipient": {
    "first_name": "Amadou",
    "last_name": "Diallo",
    "phone": "+221771234567"
  },
  "reason": "Invoice payment"          // optional
}
Note: Payouts are irreversible once initiated.
Rate limit: max 2 payouts to the same phone number within any 5-minute window → 409

── 7. ACCOUNT BALANCE
GET /api/v2/accounts         → array of accounts with balances (scope: read | management)
GET /api/v2/accounts/stats   → totals across all accounts    (scope: read | management)
GET /api/v2/accounts/{id}    → single account                (scope: read | management)

── 8. WEBHOOKS (real-time payment notifications)
NabooPay sends POST requests to your registered URL when payments change status.
Event: payment_status

Payload:
{
  "order_id": "order_123",
  "transaction_status": "completed",
  "amount": 10000,
  "currency": "XOF",
  "selected_payment_method": "wave",
  "customer": { "first_name": "...", "last_name": "...", "phone": "..." },
  "fees": 250,
  "fees_customer_side": true,
  "paid_at": "2024-01-15T10:35:00Z"
}

Signature verification (HMAC SHA256):
- Header: X-Signature
- Compute: HMAC-SHA256(compact_json_payload, secret_key).hexdigest()
- Always verify before processing — reject unverified requests with 401

Register webhook URL: https://platform.naboopay.com/parametre/ → Integration

ERROR RESPONSES
v2 errors always return: { "error": "human-readable message" }
Common codes: 400 bad request | 401 invalid key | 403 wrong scope or org blocked |
              404 not found | 409 payout in progress | 429 rate limited | 500 server error

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 YOUR TASK — ASK ME THESE QUESTIONS FIRST
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Before writing any code, ask me the following questions one at a time:

1. WHAT DO YOU WANT TO BUILD?
   Examples:
   - "Accept payments on my checkout page"
   - "Send payouts to freelancers or vendors"
   - "Refund a specific transaction"
   - "Handle webhook notifications when a payment succeeds"
   - "Check my account balance"
   - "A combination of the above"

2. FEE STRUCTURE:
   "Should the payment processing fees be paid by the customer or by you?"
   - Customer pays: fees are added on top of the product total (fees_customer_side: true)
   - Merchant pays: fees are deducted from what you receive (fees_customer_side: false)
   Tip: if unsure, most merchants use fees_customer_side: false

3. ESCROW / HOLD FUNDS?
   "Do you need funds to be held until you manually release them?"
   - Yes → useful for marketplaces or delivery-based payments (is_escrow: true)
   - No  → funds credited to your account immediately (is_escrow: false)

4. TECH STACK:
   "What framework or language are you using?"
   (Next.js, React, Node.js/Express, Python/Flask/Django, PHP, Go, mobile, etc.)

5. WEBHOOKS:
   "Do you need real-time notifications when a payment succeeds or fails?"
   - If yes: provide your server URL and I will implement signature verification

After I answer all your questions, implement the complete, production-ready integration:
- Store the API key in an environment variable (never hardcode it)
- Handle all error cases (400, 401, 403, 404, 409, 429, 500) using the { "error": "..." } field
- Always include the customer object in transaction creation requests
- Add webhook signature verification if webhooks are requested
- Include comments explaining each step
- Use the patterns appropriate for my tech stack