Skip to main content
Choose how the trip should be paid based on who controls the payment. The trip tool builds the trip and returns a trip_id. The agent passes that ID to checkout, which prices the full trip, returns the priced quote’s quote_id, and returns the payment options available for that transaction.

​
Payment flow

Use a Checkout Link when a person should review the trip and enter the payment details. Jinko hosts the payment page. The traveler sees the trip and combined total, then completes the payment in the browser.
  1. The agent builds the trip and receives its trip_id.
  2. The agent calls checkout with that trip_id.
  3. Checkout returns a checkout_url.
  4. The agent sends or opens the link for the traveler.
  5. The traveler reviews the trip and pays on the hosted page.

​
Shared Payment Token

Use a Shared Payment Token when the agent should pay programmatically without sending the traveler to a payment page.
  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 calls submit_agent_payment with the trip_id, the token, and the quote_id the traveler approved.
  5. Jinko authorizes the payment and starts fulfillment.
The token is limited to the payment details returned by checkout. The agent never receives the underlying card details. If the bank requires customer authentication, the traveler must complete that step before payment can finish.

​
Pay the quote the traveler approved

Pass the quote_id from the checkout the traveler approved. The payment is then taken against that quote only:
  • A quote_id that is not one of the trip’s quotes is refused with NOT_FOUND, and nothing is charged.
  • A quote that can no longer be paid, because it passed its expires_at or the travelers changed after it was priced, is refused with QUOTE_EXPIRED, and nothing is charged. Run checkout again, show the new total, and pay the new quote_id.
  • Running checkout again creates a new quote. A payment that names the earlier quote_id still pays the earlier quote while it is valid, so it never moves to a price the traveler did not see.
Without quote_id, the payment is taken against the trip’s latest valid quote, and the answer names the quote it charged as quote_id.

​
Retries never charge twice

Each payment submission carries an idempotency key:
  • MCP submit_agent_payment derives the key from the trip_id, the quote_id and the token. Calling it again with the same three returns the first attempt’s outcome instead of charging again.
  • REST takes the key in the Idempotency-Key header on a typed submission to POST /v1/agent_payment/submit, a body with trip_id, quote_id and payment. The header is required there: without it the request is refused with 400 CREDENTIAL_FORMAT_INVALID. Use 1 to 255 printable ASCII characters and one key per intended payment. The key is compared on the trip, the quote, the credential type and the amount, not on the credential itself: the same key with the same trip and quote replays the first outcome, even when the token differs (the first accepted request wins and the new token is never tried). The same key with a different trip, quote or credential type is refused with 409 IDEMPOTENCY_KEY_REUSED.
The CLI sends the same typed submission with jinko agent-pay submit --trip-id <id> --quote-id <id> --token <spt> and derives the key the way MCP does. 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.

​
Virtual Credit Card

Use a Virtual Credit Card when your secure backend should pay programmatically with a VCC. VCC payments must be enabled for the tenant and listed as available by checkout. A VCC has no customer authentication handoff, so the credential must complete without one.

​
Choose the right path

  1. Choose Checkout Link when a person should review and pay.
  2. Choose Shared Payment Token when an agent platform controls payment.
  3. Choose Virtual Credit Card when your secure backend provides an enabled VCC.
Always use the payment options returned by the latest checkout. Availability can change between trips.