Skip to main content
These rules apply to every payment you submit to Jinko: a Shared Payment Token, and any other payment type checkout lists in accepted_payment_types. A checkout link payment happens on the hosted page and needs none of them.

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 cannot be paid, because it passed its expires_at, the travelers changed after it was priced, an item was added to the trip or removed from it after it was priced (reason: "items_changed"), or it could not price every item (reason: "partial_quote"), is refused with QUOTE_EXPIRED, and nothing is charged. Run checkout again, show the new total, and pay the new quote_id. For partial_quote, first remove or replace the items with quote_status: "failed", unless their failure_reason is provider_error; see When an item cannot be priced.
  • Running checkout again returns the same quote_id while that quote is still valid and the trip has not changed. A partial quote is never reused: checkout prices the trip again and returns a new quote_id. After an item is added to the trip or removed from it, checkout also prices the trip again, and the earlier quote can no longer be paid. When checkout returns a new quote_id, a payment that names the earlier one is still charged the earlier total while that quote is valid, never a price the traveler did not see.
A typed submission must include quote_id: without it the request is refused with 400 CREDENTIAL_FORMAT_INVALID.

Retries never charge twice

A typed submission to POST /v1/agent_payment/submit carries an Idempotency-Key header. The header is required: 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 first accepted request wins. Sending it again with the same key returns that attempt’s outcome instead of charging again.
  • The key is compared on the trip, the quote, the payment type, the card kind (customer_card or vcc, for a card), the amount and the currency, not on the credential itself. The same key with the same trip and quote replays the first outcome even when the credential differs: the new credential is never tried. To pay with another credential, use a new key, and only when the outcome allows another attempt.
  • The same key with a different trip, quote, payment type, card kind, amount or currency is refused with 409 IDEMPOTENCY_KEY_REUSED.
  • A request refused before acceptance with 400 CREDENTIAL_FORMAT_INVALID does not use up its key: correct it and send it again with the same key, unless the Idempotency-Key itself was refused.
  • A timeout is not permission to create a new attempt. Send the same request with the same key, or read the attempt, and follow recovery.action.
  • A 503 TEMPORARILY_UNAVAILABLE answer carries no payment_attempt_id, so it does not tell you whether an attempt was created. Send the same request again with the same key, after Retry-After when the answer carries it. The answer can come with no Retry-After, no payment_error and no recovery; wait a few seconds, then send it again.

Read the outcome

A typed submission answers with a PaymentAttemptOutcome: 200 means a known outcome, including a decline. It does not mean the payment or booking succeeded. 202 means the attempt is still in progress (pending or cancelling). Wait for the Retry-After interval, then poll the attempt:
The {trip_id} in this path accepts either trip_<n> or <n> (for example, trip_123 or 123). A trip_id that is not the attempt’s trip returns 404 NOT_FOUND. Over MCP, read the same attempt as payment_attempt on get_trip. Honor the returned polling interval (Retry-After / retry_after_seconds). Keep reading the same attempt while its action is poll, including during cancellation or an unknown provider outcome. Do not submit a second payment to resolve a pending booking. An attempt that succeeds reads authorized with recovery.action: "poll", then captured with recovery.action: "stop". Stop polling on the action, not on booking_status: an authorized attempt can still read poll after booking_status has become completed.

Recovery actions

Always obey the returned recovery action. A code alone does not establish that cleanup has finished or that the quote is still usable. Each payment_error.code and the action it asks for is listed under Payment outcome codes.

Money outcomes after booking

money reports authorized, captured, released, refunded, and externally_reimbursed as Money objects with display. Use display for presentation. Read resolution_status (pending, resolved, manual_review, external_reimbursement_pending, or externally_reimbursed) and refund_reference when available; missing amounts are not evidence of zero money movement.
  • Definitive booking failure before capture: the authorization is voided and released; the payment becomes cancelled after cleanup.
  • Definitive booking failure after capture: the captured amount is refunded; read refunded and resolution_status: "resolved".
  • Partial delivery: exactly the booked items are captured, with the remainder released; booking_status is partial.
  • Result cannot be verified: RECONCILIATION_REQUIRED / manual_review; contact support. Jinko does not guess whether money moved or a booking succeeded.