Concepts

Webhooks & payments

How payment providers report results to 1fly, and how duplicates are made harmless.

Travellers pay at the provider’s page (live.payUrl on the order). The provider then calls 1fly back with the result. 1fly forwards it to the waiting booking, which issues the ticket or keeps waiting for another try.

Provider Endpoint Status
mockpay (test mode) POST /v1/webhooks/mockpay Available
Click same contract, own endpoint and signature check Planned
Payme same contract, own endpoint and signature check Planned
Stripe same contract, own endpoint and signature check Planned

Partners do not receive webhooks from 1fly yet. To follow an order, poll GET /v1/orders/{id} (see Following an order).

The payment webhook#

The provider sends one request per payment event:

HTTP
POST /v1/webhooks/mockpay HTTP/1.1
Content-Type: application/json

{
  "orderId": "ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10",
  "paymentId": "pay_418230995512",
  "status": "held",
  "providerEventId": "evt_9c1d2e3f"
}
Field Required Meaning
orderId yes The 1fly order the payment belongs to.
paymentId yes The payment 1fly created for this order (payments[].id on the order).
status yes held: the money is authorised (held, not captured). declined: the bank refused.
reason no Why it was declined, e.g. Insufficient funds. Shown in the timeline.
providerEventId yes The provider’s unique id for this event. Used to drop duplicates.

The endpoint needs no API key; it answers 200:

JSON
{ "received": true, "duplicate": false }

What 1fly does with it, in order:

  1. Stores the raw callback, keyed by provider and providerEventId.
  2. Writes a payment.webhook_received event to the order timeline (with the requestId).
  3. Forwards the result to the booking:
    • held: the booking moves to paid_hold, issues the ticket, then captures the money.
    • declined: the attempt is recorded as PAYMENT_DECLINED and the order keeps waiting in awaiting_payment until holdExpiresAt, so the traveller can pay with another card.

The money is captured only after the ticket is issued. If issuing fails, the hold is released instead.

Deduplication#

Providers retry callbacks, sometimes many times. 1fly keeps exactly one copy per providerEventId:

  • The first callback with an id is processed as above.
  • Any repeat returns 200 {"received": true, "duplicate": true} and changes nothing: no second timeline event, no second signal to the booking.

So a provider (or you, in tests) can resend safely. Use a new providerEventId for each new event, for example a second attempt after a decline.

Warning

Real provider endpoints verify the provider’s signature before reading the body. The mock endpoint does not: it is for test mode only.

Testing payments#

  • Send the webhook yourself, as in Quickstart step 5.
  • Through MCP, call the simulate_payment tool with "outcome": "held" or "declined".
  • Use the payment_declined and payment_timeout test scenarios with POST /v1/dev/simulate, which plays the provider for you.
API version v0.0.1 · Spec generated from source on 2026-11-22Changelog · Prices in so‘m (UZS)