Skip to main content
SafarAPI never touches card data. Your bank collects the customer’s payment; Safariat invoices you monthly for the aggregate net amount (the net_amount frozen in each quote). This page is the money model your finance team needs.

​
The cycle

  1. Throughout the month you create bookings; each carries a paid_amount_net.
  2. At month end Safariat aggregates your bookings, refunds, and adjustments into one settlement.
  3. The settlement moves to ISSUED; a settlement.issued webhook fires and a PDF invoice becomes available.
  4. You pay the net_due by bank transfer before due_at.
  5. A Safariat admin marks it PAID once the transfer is received.
A booking’s settlement_id is null until it is invoiced, then points at the settlement that included it.

​
Amounts

net_due = bookings_total − refunds_total + adjustments_total
All values follow the Money shape (MAD, 2-decimal string). SettlementDetail exposes the per-line breakdown:
line_typeSignMeaning
BOOKINGpositiveNet amount of one booking.
REFUNDnegativeReversal of a cancelled booking (per its tier).
ADJUSTMENT±Manual correction by Safariat (rare, always documented).

​
Status lifecycle

StatusMeaning
DRAFTGenerated, under Safariat admin review. Not visible to you.
ISSUEDIssued; PDF invoice available; payment expected.
PAIDTransfer received, marked by a Safariat admin.
OVERDUEPast due_at without payment.
DISPUTEDYou disputed it; blocks future issuances until resolved.
CANCELLEDAdministrative cancellation (exception).

​
Endpoints

  • GET /settlements — list (paginated; DRAFT is never returned).
  • GET /settlements/{id} — detail with lines.
  • GET /settlements/{id}/invoice.pdf — redirect to the pre-signed invoice PDF.
Sandbox (sk_test_*) never issues a settlement — bookings are flagged test_mode=true. Use the response examples to model your reconciliation logic, and validate it end to end only against production.