v1.0.0OpenAPI 3.1.1

Demo: Orbit Travel API

Search destinations, flights and seat maps, book and pay, manage saved passengers and Orbit Miles, and receive booking and payment events by webhook or from the Events API.

Every request needs an API key in the x-api-key header, or an OAuth access token from Create an access token in Authorization: Bearer …. Each credential can make 60 requests a minute.

Server

Local

Authentication Required

Your API key. The sample server accepts `otk_test_4f9a2c1b8e7d6a5f`.

x-api-key:

Client Libraries

Shell

Node.js

Python

Java

Shell

Authentication

Operations

POST/v1/oauth/token

Create an access token

POST/v1/oauth/token

Destinations

Operations

List destinations

GET/v1/destinations

Get a destination

GET/v1/destinations/{id}

Flights

Operations

Seats

Operations

Get a seat map

GET/v1/flights/{id}/seats

Hold seats

POST/v1/flights/{id}/seat-holds

Bookings

Operations

Create a booking

POST/v1/bookings

List bookings

GET/v1/bookings

Get a booking

GET/v1/bookings/{id}

Update a booking

PATCH/v1/bookings/{id}

Cancel a booking

POST/v1/bookings/{id}/cancel

Upload a travel documentbeta

POST/v1/bookings/{id}/documents

List travel documents

GET/v1/bookings/{id}/documents

Download a boarding pass

GET/v1/bookings/{id}/boarding-pass

Passengers

Operations

Create a passenger

POST/v1/passengers

List passengers

GET/v1/passengers

Get a passenger

GET/v1/passengers/{id}

Update a passenger

PATCH/v1/passengers/{id}

Delete a passenger

DELETE/v1/passengers/{id}

Payments

Operations

Pay for a booking

Auth Required

Pays for a booking by card, digital wallet or bank transfer; type picks which. Cards and wallets are charged at once and the payment is succeeded or failed (a payment.succeeded or payment.failed webhook follows). Bank transfers stay pending until the money arrives; method.bankTransfer says where to send it.

The Idempotency-Key header is required: retrying with the same key returns the first payment (with Idempotent-Replayed: true) and never charges twice.

Path Parameters

idstringrequired

Booking id.

Example: bk_9Rz4Wt

Headers

Idempotency-Keystringrequired

Unique key per payment attempt (a UUID works). Keys are kept for 24 hours.

Example: 8e03978e-40d5-43e8-bc93-6894a57f9324

Bodyrequiredapplication/json

One of three shapes, told apart by type.

bodyCardPaymentRequestDto | WalletPaymentRequestDto | BankTransferPaymentRequestDto

Responses

201Created

application/json

statusstringrequired

Where the payment is in its life.

Example: succeeded

failureCodestring | nullrequired

Machine-readable reason when status is failed, otherwise null.

Example: card_declined

failureMessagestring | nullrequired

Reason for people when status is failed, otherwise null.

Example: The card was declined.

metadataobjectrequired

Up to 20 key-value pairs of your own, returned on the payment and in its webhooks.

Example: {"orderId":"order-8812","channel":"web"}

createdAtstring · date-timerequired

When the payment was created.

Example: 2026-10-03T12:01:00Z

idstringrequired

Payment id.

Example: pay_3kTq9Z

bookingIdstringrequired

Booking paid for.

Example: bk_7Hq2xP

amountnumberrequired

Amount charged, in cents (the booking total).

Example: 1299900

amountRefundednumberrequired

Amount refunded so far, in cents.

Example: 0

currencystringrequired

ISO 4217 currency code.

Example: USD

methodPaymentMethodDetailsDtorequired

How the customer paid.

Show child attributes

typestringrequired

How the payment was made. Exactly one of the objects below is set.

Example: card

cardCardDetailsDtorequired

Card details when type is card, otherwise null.

Show child attributes

brandstringrequired

Card network.

Example: visa

last4stringrequired

Last four digits.

Example: 4242

expMonthnumberrequired

Expiry month (1–12).

Example: 8

expYearnumberrequired

Expiry year.

Example: 2033

walletstring | anyrequired

Wallet when type is wallet, otherwise null.

Example: null

bankTransferBankTransferInstructionsDtorequired

Where to send the money when type is bank_transfer, otherwise null.

Show child attributes

dueAtstring · date-timerequired

Pay by then, or the booking is cancelled.

Example: 2026-10-11T12:00:00Z

ibanstringrequired

Account to send the money to.

Example: DE89370400440532013000

bicstringrequired

Bank identifier.

Example: COBADEFFXXX

referencestringrequired

Put this in the transfer's reference so we can match it.

Example: ORBIT-BK7HQ2XP

refundsRefundDto[]required

Refunds of this payment, oldest first.

Show child attributes

reasonstringrequired

Why the money went back.

Example: requested_by_customer

statusstringrequired

Bank transfer refunds stay pending for a few days.

Example: succeeded

createdAtstring · date-timerequired

When the refund was created.

Example: 2026-10-05T10:00:00Z

idstringrequired

Refund id.

Example: re_c81Hq0

paymentIdstringrequired

Payment refunded.

Example: pay_3kTq9Z

amountnumberrequired

Amount refunded, in cents.

Example: 1299900

currencystringrequired

ISO 4217 currency code.

Example: USD

Headers

X-RateLimit-Limitinteger

Requests allowed per minute for this credential.

Example: 60

X-RateLimit-Remaininginteger

Requests left in the current window.

Example: 59

X-RateLimit-Resetinteger

When the window resets, in Unix seconds.

Example: 1949398800

Idempotent-Replayedstring

true when this is the stored response to an earlier request with the same key.

Example: true

400The body is invalid, or the `Idempotency-Key` header is missing.

application/json

statusCodeintegerrequired

HTTP status code, repeated in the body.

Example: 404

messagestring | string[]required

What went wrong, for people. Validation failures list one entry per problem. Do not branch on this text.

Example: Booking not found

errorstring

Short name of the status.

Example: Not Found

401Authentication is missing or invalid.

application/json

statusCodeintegerrequired

HTTP status code, repeated in the body.

Example: 404

messagestring | string[]required

What went wrong, for people. Validation failures list one entry per problem. Do not branch on this text.

Example: Booking not found

errorstring

Short name of the status.

Example: Not Found

403Authenticated, but not allowed to do this.

application/json

statusCodeintegerrequired

HTTP status code, repeated in the body.

Example: 404

messagestring | string[]required

What went wrong, for people. Validation failures list one entry per problem. Do not branch on this text.

Example: Booking not found

errorstring

Short name of the status.

Example: Not Found

404No booking with this id.

application/json

statusCodeintegerrequired

HTTP status code, repeated in the body.

Example: 404

messagestring | string[]required

What went wrong, for people. Validation failures list one entry per problem. Do not branch on this text.

Example: Booking not found

errorstring

Short name of the status.

Example: Not Found

409The booking is cancelled or already paid.

application/json

statusCodeintegerrequired

HTTP status code, repeated in the body.

Example: 404

messagestring | string[]required

What went wrong, for people. Validation failures list one entry per problem. Do not branch on this text.

Example: Booking not found

errorstring

Short name of the status.

Example: Not Found

422This `Idempotency-Key` was already used with a different request.

application/json

statusCodeintegerrequired

HTTP status code, repeated in the body.

Example: 404

messagestring | string[]required

What went wrong, for people. Validation failures list one entry per problem. Do not branch on this text.

Example: Booking not found

errorstring

Short name of the status.

Example: Not Found

429Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.

application/json

statusCodeintegerrequired

HTTP status code, repeated in the body.

Example: 404

messagestring | string[]required

What went wrong, for people. Validation failures list one entry per problem. Do not branch on this text.

Example: Booking not found

errorstring

Short name of the status.

Example: Not Found

Headers

Retry-Afterinteger

Seconds to wait before retrying.

Example: 42

X-RateLimit-Limitinteger

Requests allowed per minute for this credential.

Example: 60

X-RateLimit-Remaininginteger

Requests left in the current window.

Example: 59

X-RateLimit-Resetinteger

When the window resets, in Unix seconds.

Example: 1949398800

500Something failed on the server. Retry with backoff.

application/json

statusCodeintegerrequired

HTTP status code, repeated in the body.

Example: 404

messagestring | string[]required

What went wrong, for people. Validation failures list one entry per problem. Do not branch on this text.

Example: Booking not found

errorstring

Short name of the status.

Example: Not Found

POST/v1/bookings/{id}/payments

curl http://localhost:3010/v1/bookings/bk_9Rz4Wt/payments \
  --request POST \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {
    "orderId": "order-8812",
    "channel": "web"
  },
  "type": "card",
  "token": "tok_visa_4242",
  "saveCard": true
}'

201

400

401

403

404

409

422

429

500

Show Schema

{
  "status": "succeeded",
  "failureCode": "card_declined",
  "failureMessage": "The card was declined.",
  "metadata": {
    "orderId": "order-8812",
    "channel": "web"
  },
  "createdAt": "2026-10-03T12:01:00Z",
  "id": "pay_3kTq9Z",
  "bookingId": "bk_7Hq2xP",
  "amount": 1299900,
  "amountRefunded": 0,
  "currency": "USD",
  "method": {
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "4242",
      "expMonth": 8,
      "expYear": 2033
    },
    "wallet": null,
    "bankTransfer": {
      "dueAt": "2026-10-11T12:00:00Z",
      "iban": "DE89370400440532013000",
      "bic": "COBADEFFXXX",
      "reference": "ORBIT-BK7HQ2XP"
    }
  },
  "refunds": [
    {
      "reason": "requested_by_customer",
      "status": "succeeded",
      "createdAt": "2026-10-05T10:00:00Z",
      "id": "re_c81Hq0",
      "paymentId": "pay_3kTq9Z",
      "amount": 1299900,
      "currency": "USD"
    }
  ]
}

Created

Get a payment

GET/v1/payments/{id}

Refund a payment

POST/v1/payments/{id}/refunds

Loyalty

Operations

Get the loyalty account

GET/v1/loyalty/account

List loyalty transactions

GET/v1/loyalty/transactions

Redeem points

POST/v1/loyalty/redemptions

Events

Operations

List events

GET/v1/events

Get an event

GET/v1/events/{id}

Webhooks

Operations

Create a webhook endpoint

POST/v1/webhook-endpoints

List webhook endpoints

GET/v1/webhook-endpoints

Delete a webhook endpoint

DELETE/v1/webhook-endpoints/{id}

Send a test event

POST/v1/webhook-endpoints/{id}/test

Models

BankTransferInstructionsDto

BankTransferPaymentRequestDto

BoardingGroup Boarding group, called in order.

BoardingPassDto

BoardingPassFormat

BoardingPassPassengerDto

BookingDto

BookingListDto

BookingStatus Where the booking is in its life.

CabinClass Cabin.

CabinSeatMapDto

CancelBookingDto

CardBrand Card network.

CardDetailsDto

CardPaymentRequestDto

Climate

CreateBookingDto

CreatePassengerDto

CreateRedemptionDto

CreateRefundDto

CreateSeatHoldDto

CreateWebhookEndpointDto

DestinationDto

DestinationListDto

DocumentKind What the document is, detected from the scan.

DocumentStatus Review status. Boarding needs a verified passport.

EventDataDto

EventDto

EventListDto

FareDto

FlightDto

FlightListDto

GrantType Always `client_credentials`.

LegacyFlightSearchDto

LoyaltyAccountDto

LoyaltyTier Current tier, from lifetime points.

LoyaltyTransactionDto

LoyaltyTransactionListDto

LoyaltyTransactionType

MealPreference Meal served on board.

OAuthErrorCode Machine-readable error code.

OAuthErrorDto

PageInfoDto

PassengerDto

PassengerListDto

PassengerProfileDto

PassportDto

PaymentDto

PaymentMethodDetailsDto

PaymentMethodType How the payment was made. Exactly one of the objects below is set.

PaymentStatus Where the payment is in its life.

RedemptionDto

RedemptionStatus Redemptions complete immediately.

RefundDto

RefundReason Why the money went back.

RefundStatus Bank transfer refunds stay `pending` for a few days.

RewardType Reward to buy. Costs: `cabin_upgrade` 40,000, `booking_credit` 10,000 ($100 off), `extra_baggage` 8,000, `lounge_access` 5,000.

SeatDto

SeatFeature What makes this seat different.

SeatHoldDto

SeatHoldStatus Active until it is used on a booking or expires.

SeatMapDto

SeatPreference Preferred seat, used when seats are auto-assigned.

SeatPriceDto

SeatRowDto

SeatStatus Whether the seat can be held.

TestWebhookEndpointDto

TierProgressDto

TokenRequestDto

TokenResponseDto

TravelDocumentDto

TravelDocumentListDto

TravelPreferencesDto

UpdateBookingDto

UpdatePassengerDto

UpdateTravelPreferencesDto

UploadDocumentDto

WalletPaymentRequestDto

WalletType Wallet the token comes from.

WebhookDeliveryDto

WebhookDeliveryStatus `succeeded` when your endpoint answered with a 2xx status.

WebhookEndpointDto

WebhookEndpointListDto

WebhookEvent

Demo: Orbit Travel API

Authentication

Create an access token

Destinations

List destinations

Get a destination

Flights

Search flights

Get a flight

Legacy flight searchDeprecated

Seats

Get a seat map

Hold seats

Bookings

Create a booking

List bookings

Get a booking

Update a booking

Cancel a booking

Upload a travel documentbeta

List travel documents

Download a boarding pass

Passengers

Create a passenger

List passengers

Get a passenger

Update a passenger

Delete a passenger

Payments

Pay for a booking

Path Parameters

Headers

Bodyrequiredapplication/json

Responses

Get a payment

Refund a payment

Loyalty

Get the loyalty account

List loyalty transactions

Redeem points

Events

List events

Get an event

Webhooks

Create a webhook endpoint

List webhook endpoints

Delete a webhook endpoint

Send a test event

Models