Travel

You search and price flights and hotel stays through Platnova, then book them. Each booking is paid from your NGN business wallet, or from a checkout your customer has already paid. If a booking cannot be completed, the money goes back to your wallet automatically.

“Pay with Platnova” is not yet available for travel (422 payment_method_not_available).

Travel must be enabled for your business. Until it is, every travel route answers 403 partner_product_disabled. If the service is unavailable, routes answer 503 travel_unavailable.

How a booking works

Search. POST /v1/partner/travel/flights/search returns offers.
Quote. POST /v1/partner/travel/flights/quote with { "offer_id", "currency": "NGN" } returns the price you pay, fee included, as amount_minor, along with expires_at.
Book. POST /v1/partner/travel/orders with that exact amount_minor. Your wallet is debited at once and the answer is 202, with the order processing.
Wait for the outcome. You receive the travel.order.confirmed webhook with the booking reference (PNR), or you can poll GET /v1/partner/travel/orders/{partner_reference}.

All amounts are integers in minor units (kobo for NGN). 100000 is ₦1,000.00. A travel partner_reference is stricter than other partner references: 1 to 64 letters, digits, ., _ or -, and never ... Anything else is refused with 422 partner_reference_invalid.

Search

POST /v1/partner/travel/flights/search

{
  "slices": [ { "origin": "LOS", "destination": "LHR", "departure_date": "2026-12-20" } ],
  "passengers": [ { "type": "adult" }, { "age": 1 } ],
  "cabin_class": "economy"
}

The answer is the offer request: its offers, each with an id and its slices and passengers (the passenger ids you book with). Prices in the search are the airline’s own. Always quote an offer before booking it.

Quote

POST /v1/partner/travel/flights/quote

{ "offer_id": "off_0000AbC…", "currency": "NGN" }

{ "quote_id": "off_0000AbC…", "amount_minor": 123456700, "currency": "NGN", "fee_minor": 150000, "expires_at": "2026-10-22T10:30:00Z", "cost_floor_applied": true }

A booking is never priced below what it costs Platnova. The quote’s fee (fee_minor, included in amount_minor) must cover the airline’s fare, the booking provider’s order fee, the exchange cost and a minimum margin. When the normal fee falls short, the fee is raised and cost_floor_applied: true appears; otherwise the field is left out. The fare itself is never changed. If the cost can’t be worked out, the offer is refused as offer_unavailable, never sold at a guess. Book with exactly the quoted amount_minor. The order is priced the same way, so a quote and its order agree.

Book

POST /v1/partner/travel/orders (needs an Idempotency-Key)

{
  "partner_reference": "SHL-123",
  "product": "flight",
  "offer_id": "off_0000AbC…",
  "amount_minor": 123456700,
  "currency": "NGN",
  "payment": { "method": "wallet" },
  "passengers": [
    {
      "id": "pas_0000…",
      "title": "ms",
      "given_name": "Ada",
      "family_name": "Obi",
      "gender": "f",
      "born_on": "1990-01-01",
      "email": "[email protected]",
      "phone_number": "+2348012345678",
      "infant_passenger_id": "pas_0001…",
      "identity_documents": [
        { "unique_identifier": "A12345678", "type": "passport", "issuing_country_code": "NG", "expires_on": "2030-01-01" }
      ]
    },
    { "id": "pas_0001…", "given_name": "Tobi", "family_name": "Obi", "born_on": "2026-01-10", "gender": "m", "title": "mr" }
  ]
}

Infants travel on an adult’s lap: put the infant’s passenger id in that adult’s infant_passenger_id.
payment.method is one of:
- wallet: your default wallet in currency is debited.
- checkout: send payment.checkout_id as well. The checkout must be one of yours, already paid, in the same currency, and for at least amount_minor less anything refunded from it. A checkout pays for one booking only. Your wallet is debited the booking amount; the checkout’s payment is what funded it.

The answer

HTTP	`data.order.status`	Meaning
`202`	`processing`	Accepted and being booked. Wait for the webhook.
`202`	`submitting`	We debited your wallet but did not hear back in time. We check within 30 minutes. If it was not booked, the money comes back.
`409` `price_changed`	`failed`	The price moved. Nothing was booked and your wallet is already refunded. `data.quote` is the new price, so book again with a new `partner_reference`.
`422` `offer_unavailable` (or another refusal code)	`failed`	Refused. Nothing was booked; already refunded.

Before any money moves, these are refused:

Refusal	When
`422` `insufficient_balance`	Your wallet does not hold `amount_minor`.
`422` `wallet_not_found`	You have no wallet in `currency`.
`422` `checkout_not_paid`	That checkout is not paid, or is not yours.
`422` `checkout_amount_short`	The checkout was paid in another currency, or for less.
`409` `checkout_already_used`	That checkout already paid for a booking.
`400` `travel_order_invalid`	A field is missing or malformed. `message` says which.
`422` `partner_per_transaction_cap` / `partner_daily_cap` / `partner_currency_not_enabled`	Your travel limits.

The order object:

{
  "partner_reference": "SHL-123",
  "product": "flight",
  "status": "booked",
  "order_id": "…",
  "amount_minor": 123456700,
  "currency": "NGN",
  "transaction_ref": "BPTRVL…",
  "payment_method": "wallet",
  "booking_reference": "ABC123",
  "e_tickets": [ { "passenger_id": "pas_0000…", "ticket_number": "…" } ],
  "refund_minor": 0,
  "created_at": "…",
  "updated_at": "…"
}

status moves through:

submitting, then processing, then booked
or failed (refunded in full)
or cancelled (refunded what the airline returns)
or attention: something unexpected happened and a Platnova person is looking at it. Your money is held, not lost, and we contact you.

Hotels (stays)

A stay follows the same steps and the same order routes as a flight: search, quote, book with POST /v1/partner/travel/orders, then read, cancel and receive webhooks by partner_reference.

Search

POST /v1/partner/travel/stays/search

{
  "rooms": 1,
  "guests": [ { "type": "adult" }, { "type": "child", "age": 7 } ],
  "location": { "radius": 5, "geographic_coordinates": { "latitude": 6.4281, "longitude": 3.4219 } },
  "check_in_date": "2026-12-12",
  "check_out_date": "2026-12-14",
  "currency": "NGN"
}

The answer lists results, each a property with a search result id, its accommodation (name, address, photos, rating, amenities) and its cheapest rate. With currency, each result also carries cheapest_amount_minor: an indicative price in your currency, fee included. The quote is the price you pay.

Rates

POST /v1/partner/travel/stays/rates with { "search_result_id": "ssr_…" } returns every room and rate for that property. Each rate has an id, its cancellation_timeline and its conditions. Prices there are the property’s own; quote a rate for yours.

Quote

POST /v1/partner/travel/stays/quote

{ "rate_id": "rat_…", "currency": "NGN" }

{
  "quote_id": "quo_…",
  "amount_minor": 31500000,
  "currency": "NGN",
  "fee_minor": 1500000,
  "due_at_accommodation_amount": "12.00",
  "due_at_accommodation_currency": "USD",
  "check_in_date": "2026-12-12",
  "check_out_date": "2026-12-14",
  "rooms": 1,
  "accommodation_id": "acc_…",
  "accommodation_name": "…",
  "cancellation_timeline": [
    { "before": "2026-12-01T12:00:00Z", "refund_minor": 30000000 },
    { "before": "2026-12-10T12:00:00Z", "refund_minor": 15000000 }
  ],
  "expires_at": "2026-10-22T12:00:00Z"
}

A quote is yours alone and lasts until expires_at (two hours). Book it before then.
due_at_accommodation_amount, when present, is paid by the guest at the property, in its own currency. It is not in amount_minor. Tell your guest.
cancellation_timeline is the refund if the booking is cancelled before each before, in your currency, at the price you pay now. Our booking fee is never refunded. An empty timeline means the room is non-refundable.

Book

POST /v1/partner/travel/orders (needs an Idempotency-Key)

{
  "partner_reference": "SHL-STAY-1",
  "product": "stay",
  "quote_id": "quo_…",
  "amount_minor": 31500000,
  "currency": "NGN",
  "payment": { "method": "wallet" },
  "guests": [ { "given_name": "Ada", "family_name": "Obi" } ],
  "email": "[email protected]",
  "phone_number": "+2348012345678",
  "special_requests": "Late check-in"
}

A stay needs quote_id, at least one guest, email and phone_number, and takes no offer_id or passengers. payment works as for flights. The answers are the flight answers, plus:

HTTP	Meaning
`422` `quote_expired`	The quote is older than two hours, or was not made for your business. Nothing was booked; already refunded. Quote again.
`422` `rate_unavailable`	The room is no longer available. Nothing was booked; already refunded.

booking_reference on the order and on travel.order.confirmed is the property’s confirmation code.

Cancel a stay

The same two calls as a flight. The refund comes from the quote’s cancellation_timeline: the best step whose before is still more than five minutes away.

The cancellation quote’s expires_at is when that step runs out, or 15 minutes, whichever is sooner.
Confirming after it answers 409 cancellation_expired. Ask for a new quote.
202 cancellation_pending means the property has not answered yet. Send the same call again.

Cancel a booking

POST /v1/partner/travel/orders/{partner_reference}/cancellation-quote tells you what comes back:
{ "cancellation_id": "ore_…", "refund_minor": 98000000, "refund_currency": "NGN", "expires_at": "…" }
For a flight, the refund is the airline’s refund at the rate you booked at. Our booking fee is not returned. A refund that the airline makes as credit or a voucher, or in another currency, shows as 0.
POST /v1/partner/travel/orders/{partner_reference}/cancellation with { "cancellation_id": "ore_…" } (needs an Idempotency-Key) confirms it. The answer is the cancelled order, and refund_minor is already in your wallet.
- 202 cancellation_pending: the airline has not answered yet. Send the same call again shortly.
- 409 cancellation_mismatch: the id is not your latest quote.
- 409 travel_order_not_cancellable: only a booked order can be cancelled.

Webhooks

Subscribe to travel.order.*. Each event carries the order:

{
  "id": "…",
  "type": "travel.order.confirmed",
  "created_at": "…",
  "partner_reference": "SHL-123",
  "data": {
    "partner_reference": "SHL-123",
    "order_id": "…",
    "product": "flight",
    "status": "booked",
    "booking_reference": "ABC123",
    "amount_minor": 123456700,
    "currency": "NGN",
    "transaction_ref": "BPTRVL…",
    "details": { "booking_reference": "ABC123", "e_tickets": [ { "passenger_id": "pas_0000…", "ticket_number": "…" } ] }
  }
}

details holds, on confirmed, the airline order with its e-tickets, and on failed and cancelled, the reason and the refund.

Event	When	Money
`travel.order.confirmed`	The airline or property confirmed. `booking_reference` is the PNR, or the property’s confirmation code.	—
`travel.order.failed`	The airline or property refused.	`refund` is the full amount, already credited to your wallet.
`travel.order.cancelled`	Cancelled by you, the airline or the property.	`refund` is what came back, already credited.
`travel.order.changed`	The airline changed the schedule. Coming soon.	—

data.product is flight or stay. Each order is refunded at most once, however many times an event is delivered.

Get Started

Customers

Cards

Virtual Accounts

Payments

Payment Links

Checkout

Invoices

Transactions

Wallets

Bills

Webhooks

Partners

How a booking works

Search

Quote

Book

The answer

Hotels (stays)

Search

Rates

Quote

Book

Cancel a stay

Cancel a booking

Webhooks

​How a booking works

​Search

​Quote

​Book

​The answer

​Hotels (stays)

​Search

​Rates

​Quote

​Book

​Cancel a stay

​Cancel a booking

​Webhooks

How a booking works

Search

Quote

Book

The answer

Hotels (stays)

Search

Rates

Quote

Book

Cancel a stay

Cancel a booking

Webhooks