Get started
Quickstart
Create a test key, book a flight, pay for it with the mock provider and read its timeline. About ten minutes.
You need the 1fly stack running locally (API on http://localhost:4000, dashboard on http://localhost:3000; see the repository README), curl, and optionally jq to pick values out of responses.
1. Create an account#
Open http://localhost:3000/signup and sign up with your e-mail, a password of at least 12 characters, your name and an account name (your agency or app). You become the owner of a new account on the Free plan.
The same thing over the API, if you prefer:
curl -X POST http://localhost:4000/v1/auth/signup \
-H 'Content-Type: application/json' \
-c cookies.txt \
-d '{"email":"dev@example.uz","password":"correct-horse-battery","name":"Dilnoza Rahimova","accountName":"Sky Travel"}'2. Create a test API key#
Go to http://localhost:3000/app/api-keys and choose Create key:
- Name: something that says where it runs, for example
quickstart. - Mode: Test.
- Scopes:
orders:readandorders:write. Addlogs:readif you want to read request logs with this key. - Expires: 30 days is plenty for a trial.
The secret (1fly_test_ followed by 40 hex characters) is shown once. Copy it into your shell:
export ONEFLY_API_KEY=1fly_test_0123456789abcdef0123456789abcdef012345673. Create an order#
An order books one flight offer for its passengers. In production the offer comes from a search; for this test any well-formed offer works.
curl -X POST http://localhost:4000/v1/orders \
-H "Authorization: Bearer $ONEFLY_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"idempotencyKey": "quickstart-0001",
"scenario": "happy",
"offer": {
"offerId": "off_9d1c",
"supplier": "hy-ndc",
"searchId": "srch_51ab",
"fareBrand": "Standard",
"mix": { "adults": 1, "children": 0, "infants": 0 },
"price": { "amountMinor": 398000000, "currency": "UZS" },
"segments": [
{ "from": "TAS", "to": "IST", "departAt": "2027-03-12T07:40", "arriveAt": "2027-03-12T10:05", "carrier": "HY", "flightNumber": "HY273" },
{ "from": "IST", "to": "TAS", "departAt": "2027-03-19T13:20", "arriveAt": "2027-03-19T19:30", "carrier": "HY", "flightNumber": "HY274" }
]
},
"passengers": [
{ "type": "ADT", "firstName": "AZIZ", "lastName": "KARIMOV", "birthDate": "1990-04-12", "gender": "M",
"citizenship": "UZ", "documentNumber": "FA1234567", "documentExpiry": "2031-05-01" }
],
"contact": { "email": "aziz@example.uz", "phone": "+998901234567" }
}'{ "order": { "id": "ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10", "reference": "K7QX2P", "status": "draft", "mode": "test" }, "created": true }The call returns at once; booking continues in the background. Save the id:
export ORDER_ID=ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10 # use the id from your responseNote
Run the same request again: you get the same order back with "created": false. That is the idempotency key at work. Use one key per purchase, so a retried request can never book twice.
4. Wait for payment#
Within a few seconds the order reaches awaiting_payment: passengers are checked, the price is confirmed and seats are held.
curl -s http://localhost:4000/v1/orders/$ORDER_ID \
-H "Authorization: Bearer $ONEFLY_API_KEY" | jq '{status: .order.status, holdExpiresAt: .order.holdExpiresAt, payUrl: .live.payUrl, paymentId: .payments[0].id}'{ "status": "awaiting_payment", "holdExpiresAt": "2026-11-17T10:15:00.000Z", "payUrl": "http://localhost:4000/v1/mockpay/ord_0d6c…/pay_418230995512", "paymentId": "pay_418230995512" }In production you send the traveller to payUrl. The seats are held until holdExpiresAt (at most 15 minutes).
5. Simulate the payment#
In test mode, play the payment provider yourself by sending the webhook it would send:
export PAYMENT_ID=pay_418230995512 # from step 4
curl -X POST http://localhost:4000/v1/webhooks/mockpay \
-H 'Content-Type: application/json' \
-d "{\"orderId\":\"$ORDER_ID\",\"paymentId\":\"$PAYMENT_ID\",\"status\":\"held\",\"providerEventId\":\"evt_$(date +%s)\"}"{ "received": true, "duplicate": false }The order moves through paid_hold and issuing to issued in a few seconds. Try "status": "declined" with a reason first to see a declined card: the order keeps waiting, and a later held still succeeds.
6. Read the timeline#
curl -s http://localhost:4000/v1/orders/$ORDER_ID/timeline \
-H "Authorization: Bearer $ONEFLY_API_KEY" | jq '.steps[] | {step, state, attempts}'{ "step": "validate_passengers", "state": "succeeded", "attempts": 1 }
{ "step": "recheck_price", "state": "succeeded", "attempts": 1 }
{ "step": "book_seats", "state": "succeeded", "attempts": 1 }
{ "step": "create_payment", "state": "succeeded", "attempts": 1 }
{ "step": "await_payment", "state": "succeeded", "attempts": 1 }
{ "step": "issue_ticket", "state": "succeeded", "attempts": 1 }
{ "step": "capture_payment", "state": "succeeded", "attempts": 1 }
{ "step": "send_ticket", "state": "succeeded", "attempts": 1 }events in the same response has every individual event in order. Read Chronology to learn how to interpret it.
Next#
- Repeat step 3 with a new
idempotencyKeyand"scenario": "flaky_supplier"or"price_up"to watch retries and a price change. All scenarios: Test scenarios. - Handle failures properly: Errors.
- Let an AI agent do all of this: MCP.