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:
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:
{ "received": true, "duplicate": false }What 1fly does with it, in order:
- Stores the raw callback, keyed by provider and
providerEventId. - Writes a
payment.webhook_receivedevent to the order timeline (with therequestId). - Forwards the result to the booking:
held: the booking moves topaid_hold, issues the ticket, then captures the money.declined: the attempt is recorded asPAYMENT_DECLINEDand the order keeps waiting inawaiting_paymentuntilholdExpiresAt, 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_paymenttool with"outcome": "held"or"declined". - Use the
payment_declinedandpayment_timeouttest scenarios withPOST /v1/dev/simulate, which plays the provider for you.