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

# Payments

> Choose between a checkout link, a Shared Payment Token, or a virtual credit card.

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

```mermaid theme={null}
flowchart LR
  T["trip<br/>returns trip_id"] --> C["checkout<br/>prices the trip"]
  C --> H["checkout_url<br/>Human pays"]
  C --> S["agent_spt_params<br/>Agent mints SPT"]
  S --> P["submit_agent_payment"]
  C --> V["VCC available"]
  V --> P

  classDef jinko fill:#FFF4F4,stroke:#FF6363,color:#1A1A1A,stroke-width:2px;
  class T,C,H,S,V,P jinko;
```

## Checkout Link

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

```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_..." }
}
```

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.


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