Sandbox walkthrough

This guide walks one flight booking toward fulfillment.status: "completed" in the sandbox environment, paying agentically: no browser, no card, no human at a checkout page.

This walkthrough completes end to end with a sandbox key. Steps 1 to 3, 5 and 6 go to the booking API. Step 4, the test-token mint, goes to a second host: the control plane’s sandbox deployment at https://platform-api.sandbox.gojinko.com. It takes the same sandbox key.Both hosts are REST, so every call here sends the key as X-API-Key. The MCP endpoint takes the same key as Authorization: Bearer instead; see Which header to send.

New keys from the dashboard or platform MCP get_api_key are tenant keys: jnk_t_ in production and jnk_sandbox_t_ in sandbox. Older person-bound keys with the bare jnk_ prefix (no _t_) are still accepted as legacy keys. Set your sandbox key. The example uses today’s UTC date plus 60 days for departure; replace it with the intended travel date when needed.

export JINKO_SANDBOX_KEY="jnk_sandbox_t_your_key"
export JINKO_API="https://api.sandbox.gojinko.com"
export JINKO_PLATFORM_API="https://platform-api.sandbox.gojinko.com"
export DEPARTURE_DATE=$(python3 -c 'from datetime import datetime, timedelta, timezone; print((datetime.now(timezone.utc) + timedelta(days=60)).date())')

What you need

A sandbox API key. Sandbox and production use separate keys; a production key will not authenticate here.
curl, jq, and Python 3 for the relative-date helper.

You do not need a Stripe account, a real card, or a browser.

Sandbox is a fully isolated environment. Payments use Stripe test mode, so no real money moves, and no booking reaches a real airline’s production system. Bookings on Jinko Airline are ticketed with test ticket numbers that start with 999.

How agentic payment works

The normal flow sends a human to a checkout page. The agentic flow replaces that step with a Shared Payment Token (SPT), a Stripe object that authorizes one specific charge up to one specific amount.

checkout → agent_spt_params → mint an SPT scoped to those params → submit → fulfillment

In production your buyer’s platform mints the SPT. In sandbox you mint a test one yourself in step 4, which is what makes this walkthrough self-contained.

SPT payments work in USD and EUR. Your partner’s binding decides which Jinko Stripe account settles the payment, not which currency you can charge. In sandbox, SPT checkout is currently offered only to partners on Jinko’s US test account (the default for an unbound partner); an EU-bound sandbox partner gets no agent_spt_params and pays through checkout_url. Any other SPT currency is refused with CURRENCY_UNSUPPORTED; pay through hosted checkout with the checkout_url from your earlier checkout response instead. This walkthrough uses USD as the example.

1) Price a flight

Search mode needs a route and a date. Pass currency: "USD" so the cart quotes in USD.

Flight coverage and empty results

Use Jinko Airline (ZZ) for sandbox flight tests. It is a fake airline that exists only in sandbox and always behaves the same way: search, booking, ticketing, extras, refund, void and exchange all work, and each flight number triggers one documented behaviour, including failures. Search with include_carriers: ["ZZ"] on one of its routes, such as JFK–LHR, from tomorrow onwards. Flight ZZ101 has no scenario, so the example below books it. See Testing in sandbox for the routes, prices and every scenario. Real airlines also appear in sandbox, through the providers’ test accounts. Use them only when you need real airline data. Their coverage is limited by those accounts and changes without notice: a missing airline or an empty result does not, by itself, mean your integration is broken, and a booking on them can fail even after search and checkout succeeded. Jinko does not publish which real airlines sandbox can search, sell or ticket; treat the real-airline path as best effort and keep your automated tests on Jinko Airline. Every filter that narrows the results is applied as sent: when no itinerary matches a carrier filter, the search returns no offers. The route codes may resolve to a metropolitan area, so inspect the returned departure and arrival airports before treating a real-airline result as a match. The example below uses Jinko Airline and your chosen future date. With include_carriers: ["ZZ"] the results are Jinko Airline only. A search that finds no matching offers returns HTTP 200 with offers: [] and result: "no_matches" (details); a search that could not be completed returns an error. If offers is empty, do not extract an item token or continue to step 2. Jinko Airline does not search departures for today (UTC): choose a departure date from tomorrow onwards, since repeating the same date will not recover the search. For an error, follow the remedy for its error code; retry a 503 or 504 later with the same filters. For no_matches, check the date and filters first: even the tested route returned zero itineraries with a USD 1 price ceiling. Adjust the test search deliberately; an empty result alone does not identify its cause or establish production availability.

curl -sS -X POST "$JINKO_API/v1/flight_search" \
  -H "X-API-Key: $JINKO_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "JFK",
    "destination": "LHR",
    "departure_date": "'"$DEPARTURE_DATE"'",
    "include_carriers": ["ZZ"],
    "trip_type": "oneway",
    "adults": 1,
    "currency": "USD"
  }' > search.json

Keep the ZZ Standard fare of flight ZZ101, the second fare of that offer (789.00 USD):

export ITEM_TOKEN=$(jq -r '.offers[] | select(.outbound.segments[0].flight_number == "101") | .fares[1].trip_item_token' search.json)

2) Build the trip

One call creates the trip, adds the item, and attaches the traveler and contact. Both a traveler and a contact with email and phone are required before a trip can be booked.

curl -sS -X POST "$JINKO_API/v1/trip" \
  -H "X-API-Key: $JINKO_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "add_item": { "trip_item_token": "'"$ITEM_TOKEN"'" },
    "upsert_travelers": {
      "travelers": [{
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1990-01-15",
        "gender": "MALE",
        "passenger_type": "ADULT"
      }],
      "contact": { "email": "you@example.com", "phone": "+33600000000" }
    }
  }' | tee trip.json | jq

export TRIP_ID=$(jq -r '.trip_id' trip.json)

3) Check out and read `agent_spt_params`

checkout quotes the cart and returns everything you need to pay for it.

curl -sS -X POST "$JINKO_API/v1/checkout" \
  -H "X-API-Key: $JINKO_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "trip_id": "'"$TRIP_ID"'" }' | tee checkout.json | jq

{
  "session_id": "cs_1048576",
  "checkout_url": "https://app.gojinko.com/checkout?t=<signed token>",
  "status": "ready",
  "expires_at": "2027-09-02T08:55:34Z",
  "payment_type": "intent",
  "total_amount_money": { "value": 18865, "currency": "USD", "decimal_places": 2, "display": "USD 188.65" },
  "items": [ /* … */ ],
  "agent_spt_params": {
    "max_amount_money": { "value": 18865, "currency": "USD", "decimal_places": 2, "display": "USD 188.65" },
    "expires_at": "2027-09-02T08:55:34Z",
    "stripe_profile": "profile_test_61Uoio…"
  }
}

payment_type: "intent" means nothing has been charged yet: you still have to pay, which is what the next two steps do. agent_spt_params is the mandate for the token you are about to mint. max_amount_money.value is 18865, not 188.65: it is in minor units, hundredths of a dollar, as every value in the money shape is. The response also still carries the deprecated agent_spt_params.max_amount and agent_spt_params.currency, the same limit and currency; read max_amount_money instead.

export MAX_AMOUNT=$(jq -r '.agent_spt_params.max_amount_money.value' checkout.json)
export SPT_CURRENCY=$(jq -r '.agent_spt_params.max_amount_money.currency | ascii_downcase' checkout.json)

No agent_spt_params in the response? Do not mint or submit an SPT. Check that the cart is quoted in USD or EUR; absence alone does not prove it is not. Use checkout_url for hosted checkout, or search again in USD or EUR.Also check expires_at. It is the quote payment deadline. Use the returned timestamp; never assume a fixed duration. If you dawdle between steps, re-run checkout before minting. The checkout_url’s own 4-hour lifetime is a different clock and does not help you here.

4) Mint a test Shared Payment Token

This is the step that replaces your buyer’s payment platform: it mints a Stripe test-mode token so you can authorize a booking without a real card. The sandbox endpoint mints on the Stripe account your partner is bound to (the US test account when unbound), in USD or EUR.

This request goes to a different host. The mint lives on Jinko’s control plane, not on the booking API you have been calling: send it to $JINKO_PLATFORM_API (https://platform-api.sandbox.gojinko.com) with the same sandbox key in X-API-Key. The route exists only in non-production environments, by design, since it mints test-mode tokens. There is no production counterpart, and the booking API host answers it with 404.

curl -sS -X POST "$JINKO_PLATFORM_API/api/v1/devplatform/sandbox/agent-test-token" \
  -H "X-API-Key: $JINKO_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "max_amount": '"$MAX_AMOUNT"', "currency": "'"$SPT_CURRENCY"'" }' | tee spt.json | jq

export SPT=$(jq -r '.shared_payment_token' spt.json)

{
  "shared_payment_token": "spt_1Nq8L2eZvKYlo2C0…",
  "max_amount": 18865,
  "currency": "usd",
  "expires_at": "2027-09-02T09:19:34Z"
}

Field	Rules
`max_amount`	Minor units, 1 to 10,000,000. Pass `agent_spt_params.max_amount_money.value` from step 3 unchanged.
`currency`	Pass `agent_spt_params.max_amount_money.currency` in lowercase: `usd` or `eur`.
`expires_in_seconds`	Optional. Defaults to 1800, capped at 3600. A larger value is clamped silently, not rejected, so don’t infer the TTL from what you sent. Read `expires_at` in the response.

A 503 here means no test minter is configured for the Stripe account your partner is bound to (another account may still be configured). That is a deployment issue, not a bad request. Nothing else returns 503.

5) Submit the payment

Hand the trip and the token to Jinko. This authorizes the charge and schedules fulfillment in one call.

curl -sS -X POST "$JINKO_API/v1/agent_payment/submit" \
  -H "X-API-Key: $JINKO_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trip_id": "'"$TRIP_ID"'",
    "shared_payment_token": "'"$SPT"'"
  }' | jq

{
  "fulfillment_cart_id": 913,
  "status": "processing",
  "payment_verified": true,
  "booking_ref": "JNK-XEVGW5"
}

If the response carries a checkout_url, the agentic path stopped. The card issuer asked for a 3DS step-up, or declined. Send a human to that URL to finish. This is the designed fallback, not an error, so handle it in production code.

6) Poll until it lands

get_trip is a cheap read rather than a live provider call, so polling every few seconds is fine.

while true; do
  status=$(curl -sS "$JINKO_API/v1/trip/$TRIP_ID" \
    -H "X-API-Key: $JINKO_SANDBOX_KEY" \
    | jq -r '.fulfillment.status // .status')
  echo "Status: $status"
  case "$status" in
    completed|partial|failed|cancelled|expired_quote|exchange_partial_failure|expired) break ;;
  esac
  sleep 5
done

curl -sS "$JINKO_API/v1/trip/$TRIP_ID" \
  -H "X-API-Key: $JINKO_SANDBOX_KEY" | jq '.bookings'

At completed you get one entry per item:

[
  {
    "item_id": "prod_f5pyznimu4",
    "kind": "flight",
    "booking_reference": "XM9L2K",
    "pnr": "XM9L2K"
  }
]

The item’s booking_reference is the supplier confirmation. Use the trip-level booking_ref for lookup and servicing. That is a full agentic booking. See the fulfillment table for the fulfillment outcomes, and remember that partial means some items booked and some did not.

The polling loop also works for trips paid through the ordinary hosted checkout. When fulfillment is absent, it reads the trip’s top-level status and stops if the trip is expired.

When something goes wrong

Symptom	Cause	Fix
`result: "no_matches"`	No offer satisfied every filter sent. With `include_carriers: ["ZZ"]`, no Jinko Airline itinerary matched the route, date and other filters (times, cabin, stops, price); on real airlines, sandbox coverage also affects results	Stop before extracting a token. Read the `instruction` and adjust one filter, then retry with the Jinko Airline example.
No offers for a departure today (UTC)	Jinko Airline does not search same-day departures	Choose a departure date from tomorrow (UTC) onwards.
`503` on a flight search	No airline source could serve the search right now; this does not mean there are no flights	Stop before extracting a token. Retry with the same filters after the `Retry-After` delay.
`504` on a flight search	No airline source answered in time; this does not mean there are no flights	Stop before extracting a token. Retry the request with the same filters.
Booking fails after payment on a real airline	The provider test account did not confirm that airline’s booking	Use Jinko Airline (`ZZ`) for sandbox flight tests; see flight coverage. On Jinko Airline a failure is a documented scenario of the flight number you booked.
`401` on any call, the mint included	Production key against sandbox, or the reverse	Keys are environment-scoped. Enable Sandbox mode in the dashboard sidebar, then choose Developers → API keys → Create key. If the account is not provisioned in Sandbox, provisioning is required first.
No `agent_spt_params` on `checkout`	No SPT payment parameters are available for this checkout	Check the cart is quoted in USD or EUR; use `checkout_url` or re-search in USD or EUR.
`400 CURRENCY_UNSUPPORTED` on submit	The SPT currency is neither USD nor EUR	Use the `checkout_url` from your earlier `checkout` response for hosted checkout, or re-search in USD or EUR.
`400` on the mint	Unsupported currency or `max_amount` out of range	Use `usd` or `eur`; `max_amount` is minor units, 1 to 10,000,000.
`503` on the mint	No test minter is configured for your partner’s bound Stripe account	Email dev@gojinko.com.
`404` on the mint	Sent to the booking API host, or to a production host: the route lives on the control plane, and only in non-production environments	Send it to `$JINKO_PLATFORM_API`, `https://platform-api.sandbox.gojinko.com`. See step 4.
`checkout_url` on the submit response	3DS step-up or decline	Expected fallback. Send a human to the URL.
`410 QUOTE_EXPIRED` on submit	The returned `expires_at` elapsed between checkout and submit	Nothing was charged and no payment object exists. Re-run `checkout` (this re-quotes), then mint a fresh token against the new `agent_spt_params`.

What’s next?

Webhooks so you learn a booking landed without polling.
Flight booking guide for the browser-based checkout flow.
Car rental guide: the same agentic path books a car in sandbox. Search with "currency": "USD" there too.
Errors for the full status-code reference, including what happens when a price moves.

Getting started

Guides

Marketing claim

Authentication

Connect

Developer Platform

Concepts

What you need

How agentic payment works

1) Price a flight

Flight coverage and empty results

2) Build the trip

3) Check out and read `agent_spt_params`

4) Mint a test Shared Payment Token

5) Submit the payment

6) Poll until it lands

When something goes wrong

What’s next?

​What you need

​How agentic payment works

​1) Price a flight

​Flight coverage and empty results

​2) Build the trip

​3) Check out and read agent_spt_params

​4) Mint a test Shared Payment Token

​5) Submit the payment

​6) Poll until it lands

​When something goes wrong

​What’s next?

What you need

How agentic payment works

1) Price a flight

Flight coverage and empty results

2) Build the trip

3) Check out and read `agent_spt_params`

4) Mint a test Shared Payment Token

5) Submit the payment

6) Poll until it lands

When something goes wrong

What’s next?