> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gojinko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shared Payment Token

> Let your agent platform pay for the trip programmatically with a token scoped to the checkout.

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, an item was added to the trip or removed from it, or the quote passed its `expires_at`, call checkout again, get the traveler's approval of the new total, and mint a new token against the new `agent_spt_params`. A stale quote is refused with `QUOTE_EXPIRED`, and nothing is charged.

When checkout answers `status: "partial"`, it returns no `agent_spt_params`: some items could not be priced, and a payment of that quote is refused with `QUOTE_EXPIRED` and `reason: "partial_quote"`. See [When an item cannot be priced](https://docs.gojinko.com/guides/trips-and-checkout.md#when-an-item-cannot-be-priced).

## 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:

```http theme={null}
POST /v1/agent_payment/submit
X-API-Key: jnk_t_...
Idempotency-Key: trip-1444-quote-2097152-attempt-1
Content-Type: application/json

{
  "trip_id": "1444",
  "quote_id": "2097152",
  "payment": { "type": "spt", "shared_payment_token": "spt_..." }
}
```

**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](https://docs.gojinko.com/guides/payment-outcomes.md#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](https://docs.gojinko.com/guides/payment-outcomes.md) for paying the exact quote the traveler approved, the idempotency rules, and what each recovery action asks you to do.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.