Submit Agent Payment

Submit a Shared Payment Token (SPT) to schedule the agent fulfillment and authorize the booking server-side in one call. This is the agent-pay alternative to sending the user to a checkout page.

PREREQUISITE: call checkout first (and again if travelers were edited since, or the quote expired, a stale quote is refused with 410 QUOTE_EXPIRED and nothing is charged) to get agent_spt_params, then mint an SPT scoped to those params.

USAGE:
  submit_agent_payment({ trip_id, shared_payment_token })
  submit_agent_payment({ trip_id, shared_payment_token, quote_id })

To bind the payment to the quote the customer approved, pass the quote_id checkout returned. A quote_id that is not one of the trip's quotes is refused and nothing is charged; calling again with the same trip_id, quote_id and token returns the first attempt's outcome instead of charging again. Without quote_id, the trip's latest valid quote is charged and the answer names it as quote_id: if checkout ran again after the customer saw the price, that is the newer quote.

On success the booking proceeds to fulfillment ({ status, payment_verified: true, booking_ref }). booking_ref (JNK-XXXXXX) is the Jinko booking reference, keep it: get_booking, hotel_cancel and flight_refund take it as booking_ref. It is the direct way an agent paying by SPT obtains that reference (no confirmation email); get_trip(trip_id) returns the same booking_ref if this reply is lost. If the issuer requires customer authentication (3DS), the response carries payment_status: requires_authentication, an authentication object ({ url, expires_at }) and no checkout_url, read your issued token's next_action.use_stripe_sdk.value with your Stripe secret key and give the traveler authentication.url + "#hv=" + that value (unchanged) to complete the bank challenge before quote_expires_at, or run stripe.handleNextAction({ hashedValue }) on your own page, then poll get_trip until payment_attempt.payment_status is none of requires_authentication, cancelling or pending (cancelling is a transient cleanup state and pending is still in progress, keep polling): authorized or captured means the payment went through and fulfillment proceeds (watch booking_state); failed, declined or cancelled means it did not, submit again with a new token before the deadline; expired means the quote expired with it, call checkout again to price a new quote, then mint and submit a new token. If the card is declined, the response carries a checkout_url instead of booking_ref, open it in a browser to pay with another method.