Authentication & connection

The sandbox is live

The sandbox is the airline's demo environment, https://ndc.retailaer.com. Everything below is the contract the production gateway will keep; its URLs are issued at go-live.

Transport

Aspect	Value
Protocol	HTTPS
Method	POST
Path	/24.4/<MessageName> (e.g. /24.4/AirShoppingRQ)
Request body	Content-Type: application/xml — the NDC message
Response body	application/xml — the paired response or an IATA_Acknowledgement
Routing header	IATA-Message-Name: IATA_<MessageName>

The message is routed by both the URL path and the IATA-Message-Name header; send them consistently.

Security

Every caller is a seller: a travel agency — or an aggregator selling for several agencies — that the airline has registered as an NDC client. You authenticate with OAuth 2.0 client-credentials; the token says who you are, which messages you may send, and which agency you sell as.

Getting credentials

The airline registers your agency (it must be an active agency with the airline) and hands you a client_id and client_secret. The secret is shown once — the airline stores only a hash of it and cannot tell it to you again; if you lose it, ask for a rotation. A rotation, or a suspension, takes effect immediately.

OAuth 2.0 client-credentials

curl -X POST https://ndc.retailaer.com/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=client_credentials \
  -d scope='ndc:shop ndc:order ndc:order:write'

HTTP Basic (-u) is preferred; client_id / client_secret in the form body are also accepted. Omit scope to receive every scope you were granted. Send the returned token on every NDC call:

Authorization: Bearer <access_token>

Tokens live 30 minutes — cache the token and refresh on expiry (the Postman collection does this automatically in a pre-request script).

Scopes

Each message needs a scope, checked before the message is processed. Missing it is 403 insufficient_scope.

Scope	Messages
ndc:shop	AirShoppingRQ, OfferPriceRQ, ServiceListRQ, SeatAvailabilityRQ
ndc:order	OrderRetrieveRQ, OrderHistoryRQ, OrderListRQ, OrderRulesRQ, ServiceDeliveryRQ
ndc:order:write	OrderCreateRQ, OrderChangeRQ, OrderReshopRQ, OrderQuoteRQ
ndc:payment	payment functions on orders
ndc:settle	the PaymentClearance* / PaymentClearing* messages
ndc:notif:subscribe	managing notification subscriptions
ndc:aggregator	acting for several sellers (see below)

The distribution chain

Every request carries a DistributionChain:

• the Carrier link names the airline you are buying from — it must be this airline (otherwise 400 distribution_chain_invalid);
• the Seller link names the agency the request is made for, by its IATA number or its agency id. It must be your agency. Leave it out and you act as your own agency.
• An aggregator (scope ndc:aggregator) must name, in the Seller link, one of the agencies it was granted — it then acts as that agency. Anything else is 403 seller_not_authorised.

Orders are yours alone

An order belongs to the seller that created it. Retrieving, listing, changing, paying or cancelling another seller's order is answered exactly like an order that does not exist (404 order_not_found) — there is no way to learn whether someone else's order exists.

Sandbox credentials

A local gateway (pnpm ndc:api) also accepts a shared sandbox client (ndc-dev-client) and API keys (X-API-Key: <your-key>), which sell as a sandbox agency. The hosted sandbox and production accept registered clients only.

Environments

Environment	Base URL (messages at /24.4/<Message>)	Token URL
Sandbox	https://ndc.retailaer.com	https://ndc.retailaer.com/oauth/token
Local	http://localhost:3018	http://localhost:3018/oauth/token
Production	issued at go-live	issued at go-live

The sandbox ships as a ready-to-use Postman environment.

Rate limits

Expect per-credential rate limiting. Treat 429 Too Many Requests as retryable with exponential backoff; honour a Retry-After header when present. Shopping messages (AirShoppingRQ, OfferPriceRQ) are the most limited — cache offers within their validity window rather than re-shopping.

Idempotency & correlation

Carry a correlation id in PayloadAttributes and reuse it on retries of order-mutating requests (OrderCreateRQ, OrderChangeRQ) so a retried call never creates a duplicate order. Match responses back to requests by the same id.

Digital signatures (optional)

NDC supports a W3C XML Digital Signature (xmldsig) in the message Signature element for non-repudiation where a bilateral agreement requires it. It is optional and omitted from the generated examples.

Request size & compression

NDC payloads (especially AirShoppingRS) can be large. Send Accept-Encoding: gzip and, for large requests, Content-Encoding: gzip if your gateway advertises support.