Question 1

What is the RayProp API and who is it for?

Accepted Answer

RayProp is an API-first infrastructure layer for Africa's short-term rental ecosystem. The API is built for developers, travel platforms, super-apps, agencies, and PMS vendors who want verified shortlet inventory, real-time availability, and booking primitives without operating their own supply, verification, or payment ops.

Question 2

How is RayProp different from a marketplace like Airbnb or Booking.com?

Accepted Answer

RayProp is not a consumer marketplace. We provide the verified inventory, availability, pricing, and booking rails that other products are built on. You bring the audience and the UX; we bring the supply and the infrastructure. You decide how listings appear, what to charge on top, and who owns the customer.

Question 3

Who can sign up — do I need a registered business?

Accepted Answer

Individual developers can sign up and use sandbox keys immediately. To switch to live keys, take real bookings, or move money, we require a registered business, KYC on the principals, and signed commercial terms. Hobby and prototype usage on sandbox is free.

Question 4

How do I get started and how long does onboarding take?

Accepted Answer

Sign up at rayprop.io, generate a sandbox key in about two minutes, and start hitting the API the same day. Most teams build a working integration in 1–3 days. Going live requires business verification and selecting a settlement model (RayProp Collects or Partner Collects); approval typically takes 1–3 business days.

Question 5

What can the API actually do today vs the roadmap?

Accepted Answer

Today: search verified listings, check live availability and pricing, create quotes, place holds, create reservations, confirm payments, sync calendars, receive webhooks, and reconcile payouts. On the roadmap: a public Reviews API, richer search facets, multi-currency settlement, and additional cities and countries beyond Nigeria.

Question 6

How do I make money with the API?

Accepted Answer

Two models. RayProp Collects: we handle checkout, payments, refunds and disputes; you earn a commission with no payment ops. Partner Collects: you set your own markup, run your own checkout, collect from guests, and remit net to RayProp. You can mix models by listing, market, or product line.

Question 7

What is the pricing model and what is included in each plan?

Accepted Answer

Plans bundle a monthly search quota plus an API access fee. Free includes a small sandbox quota for evaluation. Starter and Growth add larger quotas, live keys, and production booking access. Enterprise is custom. Search overages are billed per request, and you also earn on every booking, so most partners see API access pay for itself.

Question 8

Do I pay per booking or per API call?

Accepted Answer

You pay for API capacity (monthly plan plus any search overages). Bookings themselves are not charged per call — instead, our commission or settlement terms apply depending on whether you are on RayProp Collects or Partner Collects.

Question 9

Is there a free trial or sandbox tier?

Accepted Answer

Yes. Sandbox API keys (rp_sandbox_*) are free and give read access to real verified inventory, availability, and quotes. They are rate-limited and cannot move real money, take real bookings, or reveal guest or host PII. You can stay on sandbox as long as you need.

Question 10

What currencies are supported?

Accepted Answer

NGN today. All amounts on the wire are in kobo (1 NGN = 100 kobo) to avoid floating-point errors. Multi-currency settlement is on the roadmap as we expand coverage beyond Nigeria.

Question 11

Which countries and cities are covered?

Accepted Answer

Nigeria is live, with the deepest inventory in Lagos (Lekki, Ikoyi, VI, Ikeja and surrounding neighborhoods), Abuja (Wuse, Maitama, Asokoro, Jabi), and Port Harcourt. We are continuously expanding into other Nigerian cities and preparing for additional African markets.

Question 12

What does "verified" actually mean for a RayProp listing?

Accepted Answer

Verified means the listing has passed our checks for host validity, address accuracy, contact details, media quality, and pricing sanity, and is continuously updated. We do not claim every unit is individually hand-inspected — we combine automated checks, partner vetting, and human review on a refresh cadence.

Question 13

Who owns the customer relationship and the data?

Accepted Answer

Under Partner Collects, the guest is your customer and you own the relationship and the customer-facing data, subject to our acceptable-use rules. Under RayProp Collects, we are the merchant of record for that booking. Either way, partners must not resell or scrape host PII outside the API contract.

Question 14

Can I white-label the booking flow?

Accepted Answer

Yes. With Partner Collects the guest never sees RayProp branding — you control the search UI, checkout, confirmation emails, and customer comms. Even on RayProp Collects you can embed our hosted flows with your branding via the widget builder.

Question 15

How do refunds, cancellations, and disputes work?

Accepted Answer

Refund eligibility follows our cancellation policy (tiered by lead time before check-in). Cancellations and refunds are issued through the API; on RayProp Collects we settle directly to the guest, on Partner Collects you process the guest refund and we reverse the corresponding settlement. Disputes are mediated by our ops team with full audit trails.

Question 16

What is the SLA and uptime commitment?

Accepted Answer

Production endpoints target 99.9% monthly uptime, with public status at status.rayprop.io. Enterprise contracts add written SLAs, incident response targets, and credits. Sandbox is best-effort.

Question 17

How do I get support and what are response times?

Accepted Answer

Email and in-dashboard support for all plans. Starter and Growth get prioritized response within one business day. Enterprise customers get a dedicated Slack/Teams channel, named contacts, and same-business-day response on critical issues.

Question 18

How do I cancel, downgrade, or pause my plan?

Accepted Answer

You can downgrade or cancel from the developer dashboard at any time; changes take effect at the next billing cycle and quota is not pro-rated mid-cycle. Active reservations and webhook subscriptions continue until completion. Live keys are suspended if billing lapses.

Question 19

What is the base URL and current API version?

Accepted Answer

Production base URL is https://api.rayprop.io/v1. All endpoints are versioned under /v1; breaking changes ship under a new version path (e.g. /v2) with a documented migration window. Responses are JSON; requests use standard HTTP verbs.

Question 20

How do I authenticate API requests?

Accepted Answer

Send your API key in the X-API-Key header on every request. Keys are prefixed: rp_sandbox_* for sandbox, rp_live_* for production. Keys can be scoped (read-only, bookings, webhooks) and optionally IP-allowlisted. Never expose live keys in client-side code.

Question 21

How do I rotate or revoke an API key?

Accepted Answer

Generate a new key in the developer dashboard, deploy it, then revoke the old one. Revocation is immediate. We hash keys with SHA-256 at rest and only show the full secret once at creation — store it securely. We recommend rotating live keys at least every 90 days.

Question 22

What is the difference between sandbox and live keys?

Accepted Answer

Sandbox keys can read verified inventory, availability, and quotes against real data, but cannot create live reservations, hold dates that block real guests, debit wallets, or expose host/guest PII. Live keys unlock production bookings, payments, webhooks, and PII reveal after payment.

Question 23

How are public listing IDs structured?

Accepted Answer

Public listing IDs look like rp_lst_… (prefix + opaque suffix) and are stable across renames. Always use these in URLs, webhooks, and storage. Internal UUIDs are not part of the public contract — do not depend on them.

Question 24

How do I search listings?

Accepted Answer

GET /v1/listings with filters: city, neighborhood, bedrooms, guests, check_in, check_out, amenities, lat/lng + radius, and verified=true. Pagination is cursor-based (limit max 100, cursor + next_cursor). Search is the operation that counts against your monthly quota.

Question 25

How does availability work and is pricing real-time?

Accepted Answer

GET /v1/availability returns date-window availability and a per-night sell rate in kobo, computed live from base price, seasonality, event surge, host rules, and any agent or partner markup. Availability reflects iCal-synced calendars, RayProp bookings, and admin blocks merged into a single source of truth.

Question 26

How do I quote and hold dates before booking?

Accepted Answer

Call POST /v1/quotes with listing_id and dates to get a priced quote with a quote_id. Optionally call POST /v1/holds to soft-block the dates for a short TTL while your guest pays. Holds are subject to per-plan hold quotas to prevent inventory hogging.

Question 27

What is the full booking lifecycle?

Accepted Answer

External reservations move through a five-stage flow: quoted → held → confirmed → checked_in → completed, with cancelled/expired as terminal off-ramps. Internally this maps to our 13-state reservation_status enum, but partners only need to handle the five public stages plus expiry on holds.

Question 28

How are payments handled?

Accepted Answer

Two settlement models. RayProp Collects: guests pay via bank transfer or our payment gateway (Payaza); we settle net to your wallet on confirmed bookings. Partner Collects: you collect from guests on your own rails and remit net to RayProp on agreed cycles. Wallet top-ups (for Partner Collects pre-funding) carry a small top-up fee.

Question 29

When are guest and host PII (address, phone) revealed?

Accepted Answer

PII is stripped from all responses until the reservation reaches a paid state (payment captured or admin-confirmed for bank transfers). After payment, the confirm-payment response and subsequent GETs reveal the masked-then-full address, host contact, and check-in instructions, subject to your key scopes.

Question 30

How do webhooks work and how do I verify them?

Accepted Answer

Subscribe to events in the dashboard with a callback URL. Every delivery includes an X-RayProp-Signature header containing an HMAC-SHA256 of the raw request body using your webhook signing secret. Verify the signature before trusting the payload. Deliveries are bound to a subscription_id so changing the URL preserves event history.

Question 31

What canonical webhook events exist?

Accepted Answer

reservation.created, reservation.confirmed, reservation.checked_in, reservation.completed, reservation.cancelled, reservation.expired, payment.captured, payment.refunded, availability.updated, listing.updated. Event names are stable; new events are additive and never repurpose existing names.

Question 32

How do I handle retries and idempotency?

Accepted Answer

Send an Idempotency-Key header on POST requests that create resources (quotes, holds, reservations, payments); retries with the same key return the original result instead of creating duplicates. For webhooks, expect at-least-once delivery and dedupe on event_id. Use exponential backoff with jitter for transient 5xx and timeouts.

Question 33

What is the rate-limiting model?

Accepted Answer

Per-plan requests-per-second plus a monthly search quota. We use soft rate limiting: instead of hard 429s, you get X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Overage headers so traffic keeps flowing while you see overage in near-real-time. Persistent abuse can trigger throttling or suspension.

Question 34

What HTTP status codes and error shapes should I expect?

Accepted Answer

Standard codes: 200/201 success, 400 validation, 401 auth, 403 forbidden/scope, 404 not found, 409 conflict (e.g. dates already booked), 422 business-rule violation, 5xx server. Error bodies are JSON: { "code": "string", "message": "human-readable", "field": "optional path" }. We never return stack traces.

Question 35

How does pagination work?

Accepted Answer

All list endpoints use cursor-based pagination. Pass limit (max 100, default 20) and cursor. Each response includes next_cursor (null when exhausted). Ordering is stable across pages even as data changes, so you will not see duplicates or skipped rows mid-iteration.

Question 36

Are amounts in kobo, and how do I render NGN?

Accepted Answer

Yes — every monetary field on the wire is an integer in kobo. To display NGN, divide by 100 and format with the Intl.NumberFormat NGN currency formatter. Never store amounts as floats; arithmetic should stay in kobo end-to-end.

Question 37

How do I block dates or sync external calendars?

Accepted Answer

For RayProp-managed listings, partners can push blocks via the reservations API; conflicts are validated server-side before insert. For two-way calendar sync (Airbnb, Booking.com, custom PMS), use the iCal feed endpoints — RayProp pulls and pushes iCal on a managed schedule and reconciles conflicts.

Question 38

Are there per-listing or daily booking caps for API partners?

Accepted Answer

Yes. Daily booking caps per developer plan protect inventory and ensure fair access. Caps lift on Growth and are negotiable on Enterprise. Hold quotas also apply to prevent dates being soft-locked without conversion. You can see your current usage on the developer dashboard.

Question 39

What security and compliance practices should I follow?

Accepted Answer

TLS-only, never expose live keys in client code, store webhook signing secrets server-side, enable IP allowlisting on production keys, do not log PII in plaintext, and verify webhook signatures on every callback. Outbound calls back into our webhook ingest must use HMAC signatures, not API keys.

Question 40

Where are the docs, OpenAPI spec, Postman collection, and changelog?

Accepted Answer

Full developer docs live at rayprop.io/docs. The OpenAPI spec, Postman collection, and SDK starters are linked from the docs sidebar. The public changelog is at rayprop.io/changelog — subscribe via the developer dashboard to get notified about breaking changes and new endpoints.

Developer API FAQ

General

Technical