Skip to main content
Use a Shared Payment Token (SPT) when the agent should pay programmatically without sending the traveler to a payment page. The token is limited to the payment details returned by checkout. The agent never receives the underlying card details.

​
How it works

  1. The agent calls checkout with the trip_id.
  2. Checkout returns the total, its quote_id and expires_at, and agent_spt_params with the maximum amount, currency, and payment profile.
  3. The agent platform uses those parameters to mint a Shared Payment Token.
  4. The agent submits the token with the trip_id and the quote_id the traveler approved.
  5. Jinko authorizes the payment and starts fulfillment.
If the travelers changed since checkout, or the quote passed its expires_at, call checkout again and mint a new token against the new agent_spt_params. A stale quote is refused with QUOTE_EXPIRED, and nothing is charged.

​
Submit the token

MCP: call submit_agent_payment with the trip_id, the quote_id and the token. On success the answer carries the Jinko booking reference booking_ref; get_trip returns the same booking_ref if the reply is lost. REST: send a typed submission to POST /v1/agent_payment/submit with an Idempotency-Key header:
CLI: jinko agent-pay submit --trip-id <id> --quote-id <id> --token <spt> sends the same typed submission. MCP and the CLI derive the idempotency key from the trip_id, the quote_id and the token: calling again with the same three returns the first attempt’s outcome instead of charging again. On REST you choose the key; see Retries never charge twice. A body with only trip_id and shared_payment_token is the older form: it pays the trip’s latest valid quote and ignores Idempotency-Key.

​
Customer authentication

If the traveler’s bank requires customer authentication (3-D Secure), the traveler must complete it before the payment can finish. The submission then answers payment_status: requires_authentication with authentication, a url and its expires_at (the same time as quote_expires_at):
  1. Read your issued token’s next_action.use_stripe_sdk.value with your Stripe secret key.
  2. Send the traveler to authentication.url with #hv= and that value appended, unchanged, before authentication.expires_at. You can instead run stripe.handleNextAction({ hashedValue }) on your own page.
  3. Read the trip until payment_attempt.payment_status is no longer requires_authentication, cancelling or pending.
  4. authorized or captured means the payment went through and fulfillment proceeds. failed, declined or cancelled means it did not: submit a new token before the deadline. expired means the quote expired with it: call checkout again, then mint and submit a new token.

​
Declined token

When the token is declined, the answer carries a checkout_url instead of a booking_ref. The traveler can pay there with another method, or the agent can submit a new token before the quote expires.

​
Outcomes and retries

The REST submission answers with a payment outcome and one recovery action. See Payment outcomes and retries for paying the exact quote the traveler approved, the idempotency rules, and what each recovery action asks you to do.