Quickstart
Get started
Quickstart
From a test key to a paid booking and its webhook: quote, book, pay and receive events in test mode.
1. Create a test key
In the partners' portal, API section, create a test key. It starts with mvn_test_ and is shown only once: store it in your secrets manager. For these examples, put it in an environment variable.
export MUVON_API_KEY=mvn_test_…2. Check the key
curl "https://api.muvon.mx/api/v1/ping" \
-H "Authorization: Bearer $MUVON_API_KEY"{
"object": "ping",
"livemode": false,
"partner": {
"id": "p_4c1d9a",
"code": "VIAJESSOL",
"name": "Viajes Sol"
}
}3. Look up places
Take the airport and hotel ids from GET /places. If the place isn't listed, send address with lat and lng.
curl "https://api.muvon.mx/api/v1/places" \
-H "Authorization: Bearer $MUVON_API_KEY"4. Quote
curl -X POST "https://api.muvon.mx/api/v1/quotes" \
-H "Authorization: Bearer $MUVON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"service_type": "airport_pickup",
"pickup_at": "2026-12-20T14:30:00-05:00",
"pickup": {
"place_id": "pl_cun"
},
"dropoff": {
"place_id": "pl_hotel52"
},
"passengers": {
"adults": 2,
"children": 1
},
"bags": 3,
"extras": [
{
"code": "BOOSTER_SEAT",
"quantity": 1
}
]
}'{
"id": "qt_8f3a1c9e2b7d4f60",
"object": "quote",
"livemode": false,
"expires_at": "2026-11-14T18:40:00-05:00",
"currency": "USD",
"request": {
"service_type": "airport_pickup",
"pickup_at": "2026-12-20T14:30:00-05:00",
"pickup": {
"place_id": "pl_cun",
"name": "Cancun Airport (CUN)",
"address": null
},
"dropoff": {
"place_id": "pl_hotel52",
"name": "Hotel 52 Playa del Carmen",
"address": null
},
"hours": null,
"passengers": {
"adults": 2,
"children": 1
},
"bags": 3,
"extras": [
{
"code": "BOOSTER_SEAT",
"quantity": 1
}
]
},
"options": [
{
"vehicle_type_id": "vt_sedan",
"name": "Sedan / SUV / Tesla",
"max_passengers": 3,
"max_bags": 3,
"price_cents": 9500,
"commission_cents": 950,
"km": 54.2
},
{
"vehicle_type_id": "vt_van",
"name": "Van",
"max_passengers": 12,
"max_bags": 12,
"price_cents": 13000,
"commission_cents": 1300,
"km": 54.2
}
]
}5. Book
Pick an option and book. Always send a new Idempotency-Key per booking: if the connection drops, you retry without duplicates.
curl -X POST "https://api.muvon.mx/api/v1/bookings" \
-H "Authorization: Bearer $MUVON_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"quote_id": "qt_8f3a1c9e2b7d4f60",
"vehicle_type_id": "vt_sedan",
"passenger": {
"first_name": "Ana",
"last_name": "García",
"email": "ana@example.com",
"phone": "+5215512345678",
"language": "es"
},
"flight_number": "AA1234",
"notes": "Viajamos con una carriola",
"external_ref": "ORDER-5521",
"return_url": "https://www.example.com/orders/5521"
}'{
"id": "bk_5d2e8a41c07f4b9e",
"object": "booking",
"kind": "transfer",
"code": "TEST-000001",
"livemode": false,
"status": "new",
"payment_status": "unpaid",
"payment_url": "https://api.muvon.mx/pay/r/3c9f0b7e6a5d4c2b1a09f8e7d6c5b4a3",
"hold_expires_at": "2026-11-14T20:10:00-05:00",
"external_ref": "ORDER-5521",
"service_type": "airport_pickup",
"pickup_at": "2026-12-20T14:30:00-05:00",
"pickup": {
"place_id": "pl_cun",
"name": "Cancun Airport (CUN)",
"address": null
},
"dropoff": {
"place_id": "pl_hotel52",
"name": "Hotel 52 Playa del Carmen",
"address": null
},
"hours": null,
"vehicle_type_id": "vt_sedan",
"passengers": {
"adults": 2,
"children": 1
},
"bags": 3,
"extras": [
{
"code": "BOOSTER_SEAT",
"quantity": 1,
"price_cents": 1000
}
],
"flight_number": "AA1234",
"room": null,
"notes": "Viajamos con una carriola",
"passenger": {
"first_name": "Ana",
"last_name": "García",
"email": "ana@example.com",
"phone": "+5215512345678",
"language": "es"
},
"price_cents": 9500,
"currency": "USD",
"commission_cents": 950,
"tracking_url": "https://api.muvon.mx/track?t=a1b2c3d4e5f6",
"cancel_reason": null,
"created_at": "2026-11-14T18:10:00-05:00",
"updated_at": "2026-11-14T18:10:00-05:00"
}6. Collect payment
Send the payment_url to your customer (email, WhatsApp, your own page). In test mode the page uses Stripe in test mode: pay with card 4242 4242 4242 4242, any future date and any CVC. Or simulate it without opening it:
curl -X POST "https://api.muvon.mx/api/v1/test/bookings/TEST-000001/pay" \
-H "Authorization: Bearer $MUVON_API_KEY"7. Receive events
In the portal, save your test webhook URL and copy its whsec_… secret. Every booking change arrives signed: booking.created, booking.paid and then each ride status. Verify the signature as in Webhooks.
8. Go live
Once everything works, ask Muvon to enable live. Create a mvn_live_ key, save your live webhook URL and swap the key on your server. The code doesn't change: the mode comes from the key.