Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.safarapi.com/llms.txt

Use this file to discover all available pages before exploring further.

A booking is a confirmed reservation paid for by your customer through your bank’s checkout. SafarAPI never touches the card or payment data — your bank captures payment, sends the booking confirmation to SafarAPI with an HMAC‑signed proof of payment.

​
Lifecycle

Unlike B2C bookings on Safariat, partner bookings have no PENDING state: they are created already CONFIRMED because the payment has already been settled.

​
Required fields

FieldMeaning
quote_idThe quote you obtained from POST /quotes
partner_referenceYour internal booking ID — unique per partner, used for reconciliation
travelerFinal customer information (first/last name, email, phone, language)
payment_confirmationProof of payment captured on your side
The traveler.customer_reference is your bank’s internal customer ID. SafarAPI hashes it with a per‑partner salt before storing it — no cross‑partner traceability is possible, even in the event of a data leak.

​
Payment confirmation

"payment_confirmation": {
  "bank_payment_ref": "YBANK-PAY-2026-99887",
  "paid_amount_total": "3200.00",
  "paid_amount_net": "2880.00",
  "paid_at": "2026-07-01T14:23:55Z",
  "payment_method": "CARD"
}
  • paid_amount_total — what the customer paid your bank (informative)
  • paid_amount_net — what your bank owes SafarAPI; must equal quote.net_amount
  • bank_payment_ref — your bank’s internal payment reference, stored for reconciliation
  • payment_method — one of CARD, BANK_TRANSFER, ACCOUNT_DEBIT, CASH, WAFACASH, OTHER

​
What happens after booking

  1. SafarAPI creates a shadow user in Keycloak (federated identity to your bank)
  2. The booking is linked to the adventure snapshot (frozen content as your customer saw it)
  3. The local agency is notified (system event)
  4. The voucher PDF is generated and emailed to the traveller’s email
  5. The webhook booking.confirmed fires to your registered endpoint (if configured)
  6. The booking’s partner_paid_amount_net is added to your outstanding settlement balance

​
Cancelling

curl -X POST https://api.safarapi.com/v1/bookings/MV-ABC123/cancel \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Idempotency-Key: ...' \
  -H 'X-Timestamp: ...' \
  -H 'X-Signature: ...' \
  -d '{ "reason": "customer_request", "note": "Customer needs to reschedule" }'
The response includes:
  • tier_applied — which cancellation tier matched (frozen on the booking at creation, never moves)
  • refund.net_to_partner — deducted from your next monthly invoice
  • refund.gross_to_traveler_indicative — what you should refund your customer (your decision, not enforced)
Refunds are processed entirely through the monthly settlement cycle. SafarAPI does not initiate any wire transfer to your bank for cancellations — the refund appears as a negative line on your next invoice.

​
Listing your bookings

GET /bookings returns a paginated list of all bookings made under your partner account. Filters:
  • status — CONFIRMED, COMPLETED, CANCELLED
  • created_from, created_to — ISO datetime range
  • travel_date_from, travel_date_to — date range
  • cursor, limit — pagination
Pagination is cursor‑based. Pass back the meta.next_cursor from the previous response to get the next page.