wacaDevelopers

API reference · Sales

Cars for sale

Search cars for sale, reserve one with a deposit, and follow the purchase through escrow.

get/sales/vehicles

Search cars for sale

Query parameters

  • makestring

    Brand (partial match).

    Example: toyota

  • modelstring

    Model (partial match).

  • citystring

    abuja or lagos.

  • classstring

    economy, sedan, suv, van or luxury.

  • yearMininteger

    Oldest model year.

  • yearMaxinteger

    Newest model year.

  • priceMininteger

    Lowest price, kobo.

  • priceMaxinteger

    Highest price, kobo.

  • sortstring

    price_asc (default), price_desc or newest.

    price_ascprice_descnewest

  • pageinteger

    Page number.

  • limitinteger

    Items per page (1–50).

Response 200

A page: { data: [ … ], page, totalPages, total }. Each item in data:

  • idintegerrequired

    Pass as listingId to reserve.

  • vehicleVehiclerequired
    Show 15 fields
    • idintegerrequired
    • titlestringrequired

      e.g. “2021 Toyota Camry”.

    • makestring
    • modelstring
    • yearinteger
    • classenumrequired

      economysedansuvvanluxury

    • transmissionenum

      automaticmanual

    • fuelenum

      petroldieselhybridelectric

    • seatsinteger
    • colourstring · nullable
    • photosarray of string
    • dailyRateintegerrequired

      Price per 24 hours.

    • depositinteger

      Refundable deposit.

    • locationobjectrequired
      Show 4 fields
      • idinteger
      • codestringrequired
      • namestring
      • citystring
    • ratingobject · nullable
      Show 2 fields
      • averagenumber

        Average of 1 to 5 stars, one decimal.

      • countinteger

        Published reviews of this car.

  • priceintegerrequired

    Amount in kobo (₦1 = 100 kobo).

  • reservationDepositinteger

    What the buyer pays now to hold the car.

  • mileageKminteger
  • conditionenum

    excellentgoodfairneeds_work

  • accidentHistoryenum

    noneminormajor

  • originenum

    nigerian_usedforeign_used_duty_paidnew

  • vinstring

    Chassis number.

  • descriptionstring · nullable
  • statusstring

Errors

  • 401unauthorized: the API key is missing, wrong or revoked.
curl "https://engine-production-0004.up.railway.app/api/v1/sales/vehicles?make=toyota" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"
get/sales/vehicles/{id}

Get a car for sale

Path parameters

  • idintegerrequired

    The listing id.

    Example: 31

Response 200

In data:

  • idintegerrequired

    Pass as listingId to reserve.

  • vehicleVehiclerequired
    Show 15 fields
    • idintegerrequired
    • titlestringrequired

      e.g. “2021 Toyota Camry”.

    • makestring
    • modelstring
    • yearinteger
    • classenumrequired

      economysedansuvvanluxury

    • transmissionenum

      automaticmanual

    • fuelenum

      petroldieselhybridelectric

    • seatsinteger
    • colourstring · nullable
    • photosarray of string
    • dailyRateintegerrequired

      Price per 24 hours.

    • depositinteger

      Refundable deposit.

    • locationobjectrequired
      Show 4 fields
      • idinteger
      • codestringrequired
      • namestring
      • citystring
    • ratingobject · nullable
      Show 2 fields
      • averagenumber

        Average of 1 to 5 stars, one decimal.

      • countinteger

        Published reviews of this car.

  • priceintegerrequired

    Amount in kobo (₦1 = 100 kobo).

  • reservationDepositinteger

    What the buyer pays now to hold the car.

  • mileageKminteger
  • conditionenum

    excellentgoodfairneeds_work

  • accidentHistoryenum

    noneminormajor

  • originenum

    nigerian_usedforeign_used_duty_paidnew

  • vinstring

    Chassis number.

  • descriptionstring · nullable
  • statusstring

Errors

  • 401unauthorized: the API key is missing, wrong or revoked.
  • 404not_found: no such thing, or it is not yours.
curl "https://engine-production-0004.up.railway.app/api/v1/sales/vehicles/31" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"
post/sales/orders

Reserve a car

Idempotent: send an Idempotency-Key

Reserves the car with a deposit (default 2% of the price, at least ₦50,000) and returns the deposit checkoutUrl. Only one buyer can hold a car at a time. The buyer pays the balance by bank transfer into escrow; the seller is paid only after the car and papers are handed over.

Headers

  • Idempotency-Keystring

    A unique value you choose (a UUID). Repeat the request with the same key and you get the same result, not a second booking.

    Example: 6b2f7c3e-6f0a-4a3e-9d1c-1c2b6f1a9e55

Request body · application/json

  • listingIdintegerrequired
  • buyerobjectrequired
    Show 4 fields
    • namestringrequired
    • emailstringrequired
    • phonestringrequired
    • idNumberstring

      Optional: NIN or passport, for the transfer of ownership.

  • metadataobject
  • returnUrlstring

Response 201

In data:

  • referencestringrequired

    e.g. WS-7KQ2M9XA.

  • statusenumrequired

    pending_paymentreservedpaidcompletedcancelledexpired

  • testboolean
  • vehicleVehiclerequired
    Show 15 fields
    • idintegerrequired
    • titlestringrequired

      e.g. “2021 Toyota Camry”.

    • makestring
    • modelstring
    • yearinteger
    • classenumrequired

      economysedansuvvanluxury

    • transmissionenum

      automaticmanual

    • fuelenum

      petroldieselhybridelectric

    • seatsinteger
    • colourstring · nullable
    • photosarray of string
    • dailyRateintegerrequired

      Price per 24 hours.

    • depositinteger

      Refundable deposit.

    • locationobjectrequired
      Show 4 fields
      • idinteger
      • codestringrequired
      • namestring
      • citystring
    • ratingobject · nullable
      Show 2 fields
      • averagenumber

        Average of 1 to 5 stars, one decimal.

      • countinteger

        Published reviews of this car.

  • buyerCustomer
    Show 3 fields
    • namestringrequired
    • emailstringrequired
    • phonestringrequired

      International format preferred, e.g. +2348031234567.

  • priceobjectrequired
    Show 5 fields
    • currencystring
    • totalinteger

      Amount in kobo (₦1 = 100 kobo).

    • depositinteger

      Amount in kobo (₦1 = 100 kobo).

    • balanceDueinteger

      Amount in kobo (₦1 = 100 kobo).

    • refundedinteger

      Amount in kobo (₦1 = 100 kobo).

  • commissioninteger

    Your referral commission (businesses only).

  • holdExpiresAtdate-time · nullable

    ISO 8601 date-time.

  • reservedUntildate-time · nullable

    While reserved: when the hold ends.

  • metadataobject
  • createdAtdate-time

    ISO 8601 date-time.

  • checkoutUrlstring

    The deposit payment link (while unpaid).

Errors

  • 400invalid: something in the request is wrong. The message says what.
  • 401unauthorized: the API key is missing, wrong or revoked.
  • 404not_found: no such thing, or it is not yours.
  • 409conflict or unavailable: not possible in the current state, or the car was just taken.
curl -X POST "https://engine-production-0004.up.railway.app/api/v1/sales/orders" \
  -H "Authorization: Bearer wc_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6b2f7c3e-6f0a-4a3e-9d1c-1c2b6f1a9e55" \
  -d '{
  "listingId": 31,
  "buyer": {
    "name": "Bola Ade",
    "email": "bola@example.com",
    "phone": "+2348066660002"
  },
  "metadata": {
    "cart": "C-77"
  }
}'
Response · 201
{
  "data": {
    "reference": "WS-4HZ8P2LD",
    "status": "pending_payment",
    "test": false,
    "vehicle": {
      "id": 12,
      "title": "2021 Toyota Camry",
      "make": "Toyota",
      "model": "Camry",
      "year": 2021,
      "class": "sedan",
      "transmission": "automatic",
      "fuel": "petrol",
      "seats": 5,
      "colour": "Silver",
      "photos": [
        "https://api.waca.com.ng/api/media/file/camry-1.jpg"
      ],
      "dailyRate": 4500000,
      "deposit": 8000000,
      "location": {
        "id": 1,
        "code": "ABV",
        "name": "Nnamdi Azikiwe International Airport, Abuja",
        "city": "abuja"
      }
    },
    "buyer": {
      "name": "Bola Ade",
      "email": "bola@example.com",
      "phone": "+2348066660002"
    },
    "price": {
      "currency": "NGN",
      "total": 800000000,
      "deposit": 5000000,
      "balanceDue": 795000000,
      "refunded": 0
    },
    "commission": 1200000,
    "holdExpiresAt": null,
    "reservedUntil": "2026-11-08T12:00:00.000Z",
    "metadata": {
      "cart": "C-77"
    },
    "createdAt": "2026-11-01T12:00:00.000Z",
    "checkoutUrl": "https://checkout.paystack.com/xyz789"
  }
}
get/sales/orders

List orders

Query parameters

  • statusstring

    pending_payment, reserved, paid, completed, cancelled or expired.

  • listing_idinteger

    Only this listing.

  • emailstring

    The buyer’s email.

  • pageinteger

    Page number, from 1.

    Example: 1

  • limitinteger

    Items per page (1–100). Default 20.

    Example: 20

Response 200

A page: { data: [ … ], page, totalPages, total }. Each item in data:

  • referencestringrequired

    e.g. WS-7KQ2M9XA.

  • statusenumrequired

    pending_paymentreservedpaidcompletedcancelledexpired

  • testboolean
  • vehicleVehiclerequired
    Show 15 fields
    • idintegerrequired
    • titlestringrequired

      e.g. “2021 Toyota Camry”.

    • makestring
    • modelstring
    • yearinteger
    • classenumrequired

      economysedansuvvanluxury

    • transmissionenum

      automaticmanual

    • fuelenum

      petroldieselhybridelectric

    • seatsinteger
    • colourstring · nullable
    • photosarray of string
    • dailyRateintegerrequired

      Price per 24 hours.

    • depositinteger

      Refundable deposit.

    • locationobjectrequired
      Show 4 fields
      • idinteger
      • codestringrequired
      • namestring
      • citystring
    • ratingobject · nullable
      Show 2 fields
      • averagenumber

        Average of 1 to 5 stars, one decimal.

      • countinteger

        Published reviews of this car.

  • buyerCustomer
    Show 3 fields
    • namestringrequired
    • emailstringrequired
    • phonestringrequired

      International format preferred, e.g. +2348031234567.

  • priceobjectrequired
    Show 5 fields
    • currencystring
    • totalinteger

      Amount in kobo (₦1 = 100 kobo).

    • depositinteger

      Amount in kobo (₦1 = 100 kobo).

    • balanceDueinteger

      Amount in kobo (₦1 = 100 kobo).

    • refundedinteger

      Amount in kobo (₦1 = 100 kobo).

  • commissioninteger

    Your referral commission (businesses only).

  • holdExpiresAtdate-time · nullable

    ISO 8601 date-time.

  • reservedUntildate-time · nullable

    While reserved: when the hold ends.

  • metadataobject
  • createdAtdate-time

    ISO 8601 date-time.

  • checkoutUrlstring

    The deposit payment link (while unpaid).

Errors

  • 401unauthorized: the API key is missing, wrong or revoked.
curl "https://engine-production-0004.up.railway.app/api/v1/sales/orders?page=1&limit=20" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"
get/sales/orders/{reference}

Get an order

Status: pending_payment → reserved (deposit paid, car held about 7 days) → paid (balance received into escrow) → completed (car and papers handed over), or cancelled / expired.

Path parameters

  • referencestringrequired

    The order reference.

    Example: WS-4HZ8P2LD

Response 200

In data:

  • referencestringrequired

    e.g. WS-7KQ2M9XA.

  • statusenumrequired

    pending_paymentreservedpaidcompletedcancelledexpired

  • testboolean
  • vehicleVehiclerequired
    Show 15 fields
    • idintegerrequired
    • titlestringrequired

      e.g. “2021 Toyota Camry”.

    • makestring
    • modelstring
    • yearinteger
    • classenumrequired

      economysedansuvvanluxury

    • transmissionenum

      automaticmanual

    • fuelenum

      petroldieselhybridelectric

    • seatsinteger
    • colourstring · nullable
    • photosarray of string
    • dailyRateintegerrequired

      Price per 24 hours.

    • depositinteger

      Refundable deposit.

    • locationobjectrequired
      Show 4 fields
      • idinteger
      • codestringrequired
      • namestring
      • citystring
    • ratingobject · nullable
      Show 2 fields
      • averagenumber

        Average of 1 to 5 stars, one decimal.

      • countinteger

        Published reviews of this car.

  • buyerCustomer
    Show 3 fields
    • namestringrequired
    • emailstringrequired
    • phonestringrequired

      International format preferred, e.g. +2348031234567.

  • priceobjectrequired
    Show 5 fields
    • currencystring
    • totalinteger

      Amount in kobo (₦1 = 100 kobo).

    • depositinteger

      Amount in kobo (₦1 = 100 kobo).

    • balanceDueinteger

      Amount in kobo (₦1 = 100 kobo).

    • refundedinteger

      Amount in kobo (₦1 = 100 kobo).

  • commissioninteger

    Your referral commission (businesses only).

  • holdExpiresAtdate-time · nullable

    ISO 8601 date-time.

  • reservedUntildate-time · nullable

    While reserved: when the hold ends.

  • metadataobject
  • createdAtdate-time

    ISO 8601 date-time.

  • checkoutUrlstring

    The deposit payment link (while unpaid).

Errors

  • 401unauthorized: the API key is missing, wrong or revoked.
  • 404not_found: no such thing, or it is not yours.
curl "https://engine-production-0004.up.railway.app/api/v1/sales/orders/WS-4HZ8P2LD" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"
Response · 200
{
  "data": {
    "reference": "WS-4HZ8P2LD",
    "status": "reserved",
    "test": false,
    "vehicle": {
      "id": 12,
      "title": "2021 Toyota Camry",
      "make": "Toyota",
      "model": "Camry",
      "year": 2021,
      "class": "sedan",
      "transmission": "automatic",
      "fuel": "petrol",
      "seats": 5,
      "colour": "Silver",
      "photos": [
        "https://api.waca.com.ng/api/media/file/camry-1.jpg"
      ],
      "dailyRate": 4500000,
      "deposit": 8000000,
      "location": {
        "id": 1,
        "code": "ABV",
        "name": "Nnamdi Azikiwe International Airport, Abuja",
        "city": "abuja"
      }
    },
    "buyer": {
      "name": "Bola Ade",
      "email": "bola@example.com",
      "phone": "+2348066660002"
    },
    "price": {
      "currency": "NGN",
      "total": 800000000,
      "deposit": 5000000,
      "balanceDue": 795000000,
      "refunded": 0
    },
    "commission": 1200000,
    "holdExpiresAt": null,
    "reservedUntil": "2026-11-08T12:00:00.000Z",
    "metadata": {
      "cart": "C-77"
    },
    "createdAt": "2026-11-01T12:00:00.000Z"
  }
}
post/sales/orders/{reference}/cancel

Cancel an order

A buyer can withdraw before paying. After the deposit, our support team decides the refund: you get a 409.

Path parameters

  • referencestringrequired

    The order reference.

    Example: WS-4HZ8P2LD

Response 200

In data:

  • referencestringrequired

    e.g. WS-7KQ2M9XA.

  • statusenumrequired

    pending_paymentreservedpaidcompletedcancelledexpired

  • testboolean
  • vehicleVehiclerequired
    Show 15 fields
    • idintegerrequired
    • titlestringrequired

      e.g. “2021 Toyota Camry”.

    • makestring
    • modelstring
    • yearinteger
    • classenumrequired

      economysedansuvvanluxury

    • transmissionenum

      automaticmanual

    • fuelenum

      petroldieselhybridelectric

    • seatsinteger
    • colourstring · nullable
    • photosarray of string
    • dailyRateintegerrequired

      Price per 24 hours.

    • depositinteger

      Refundable deposit.

    • locationobjectrequired
      Show 4 fields
      • idinteger
      • codestringrequired
      • namestring
      • citystring
    • ratingobject · nullable
      Show 2 fields
      • averagenumber

        Average of 1 to 5 stars, one decimal.

      • countinteger

        Published reviews of this car.

  • buyerCustomer
    Show 3 fields
    • namestringrequired
    • emailstringrequired
    • phonestringrequired

      International format preferred, e.g. +2348031234567.

  • priceobjectrequired
    Show 5 fields
    • currencystring
    • totalinteger

      Amount in kobo (₦1 = 100 kobo).

    • depositinteger

      Amount in kobo (₦1 = 100 kobo).

    • balanceDueinteger

      Amount in kobo (₦1 = 100 kobo).

    • refundedinteger

      Amount in kobo (₦1 = 100 kobo).

  • commissioninteger

    Your referral commission (businesses only).

  • holdExpiresAtdate-time · nullable

    ISO 8601 date-time.

  • reservedUntildate-time · nullable

    While reserved: when the hold ends.

  • metadataobject
  • createdAtdate-time

    ISO 8601 date-time.

  • checkoutUrlstring

    The deposit payment link (while unpaid).

Errors

  • 401unauthorized: the API key is missing, wrong or revoked.
  • 404not_found: no such thing, or it is not yours.
  • 409conflict or unavailable: not possible in the current state, or the car was just taken.
curl -X POST "https://engine-production-0004.up.railway.app/api/v1/sales/orders/WS-4HZ8P2LD/cancel" \
  -H "Authorization: Bearer wc_test_YOUR_KEY"