> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dev.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, 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:

```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.dev.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.dev.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.