NearbyMe Food Delivery API

Overview

The payment gateway is Paystack (Nigerian). There are no webhooks involved in the mobile flow — verification is entirely client-driven. The mobile app calls the verify endpoint after the user completes payment inside the Paystack UI.

Must happen before payment. Call this when the customer taps "Proceed to Checkout".

POST /api/orders
Authorization: Bearer <customer_token>

{
  "delivery_address": "12 Olu Adesanya Street, Lagos",
  "delivery_latitude": 6.5244,
  "delivery_longitude": 3.3792,
  "special_instructions": "Leave at gate"   // optional
}

// Response
{
  "success": true,
  "data": {
    "id": "order-uuid-here",       // ← SAVE THIS
    "status": "placed",
    "total_amount": 24000,         // ← SAVE THIS
    "subtotal": 22000,
    "delivery_fee": 1500,
    "service_fee": 500
  }
}

Calls Paystack internally and returns everything the mobile app needs to open the payment UI.

POST /api/payments
Authorization: Bearer <customer_token>

{
  "order_id": "order-uuid-here",
  "payment_method": "card",
  "callback_url": "nearbyme://payment-callback"  // your app deep link
}

// Response
{
  "success": true,
  "data": {
    "id": "payment-uuid-here",                      // ← SAVE → payment_id for verify
    "stripe_payment_intent_id": "CHW-1716-abc123",  // ← SAVE → reference for verify
    "paystack_access_code": "0peioxfhpn",           // ← pass to Paystack SDK
    "paystack_authorization_url": "https://checkout.paystack.com/0peioxfhpn",
    "amount": 24000,
    "status": "pending"
  }
}

Open the Paystack UI using the paystack_access_code from Step 2. Use an in-app WebView or the platform SDK — do not open the device browser.

final charge = Charge()
  ..accessCode = payment.paystackAccessCode
  ..reference  = payment.reference;

final response = await _paystack.checkout(
  context,
  method: CheckoutMethod.selectable,
  charge: charge,
);

if (response.status == true) {
  // call verifyPayment()
}

<WebView
  source={{ uri: authorizationUrl }}
  onNavigationStateChange={(nav) => {
    if (nav.url.startsWith(
      'nearbyme://payment-callback'
    )) {
      closeWebView()
      verifyPayment()
    }
  }}
/>

Call this immediately after the Paystack SDK fires its success callback. Do not wait for user action. Block the UI during this call.

POST /api/payments/verify
Authorization: Bearer <customer_token>

{
  "reference": "CHW-1716-abc123",      // stripe_payment_intent_id from Step 2
  "payment_id": "payment-uuid-here"    // id from Step 2
}

// Success Response
{
  "success": true,
  "data": {
    "id": "payment-uuid-here",
    "status": "completed",
    "order_id": "order-uuid-here",
    "amount": 24000
  }
}

// Failure Response (abandoned / declined)
{
  "success": false,
  "error": "Payment abandoned. Please try again."
}

No Paystack involved. Skip Steps 3 and 4 entirely.

POST /api/payments
{
  "order_id": "order-uuid-here",
  "payment_method": "cash_on_delivery"
}

// Returns payment with status: "pending"
// Order moves forward when rider marks it delivered
// No verification step needed

State the App Must Track

{
  orderId:          string,   // from POST /api/orders
  paymentId:        string,   // from POST /api/payments → data.id
  reference:        string,   // from POST /api/payments → data.stripe_payment_intent_id
  accessCode:       string,   // pass to Paystack SDK
  status: 'idle' | 'creating_order' | 'initializing'
        | 'awaiting_paystack' | 'verifying' | 'success' | 'failed'
}

// Persist paymentId + reference to local storage immediately after Step 2
// so an interrupted payment can be resumed on app restart

Loading & Error States

Edge Cases

Common Mistakes to Avoid