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

> ## Agent Instructions
> Agentcard is for companies whose agent buys for their users. Pick one path: the opencommerce SDK (@agent-cards/commerce-sdk) gives your agent one buy tool that finds the product, builds the cart, gets the user's approval and places the order at real stores; the Agentcard SDK (@agent-cards/sdk) pays with the user's own card when your agent already shops in a browser (Browser Use, Kernel, Browserbase, Anchor or Notte); the Purchase API (POST /buy) does the same purchase flow over plain HTTP in any language; Issuing gives the agent its own card.
> Start with `npx agent-cards init` in the app's folder (Node 22 or later). No invite is needed: it creates your Agentcard account if you don't have one, installs the opencommerce SDK and puts the credentials in the env file, kept out of git. From a coding agent, run `npx agent-cards init --print --categories all --implementation tool --wallet vault --skip-install` to get the setup steps to apply yourself.
> Vault is by invitation: request it at https://agentcard.com/get-started?utm_source=docs&utm_medium=llms&utm_campaign=agent-instructions. opencommerce needs no invite.
> Never ask a user for a card number, expiry date or CVV in chat. Send them the Vault link; they add their card on Agentcard's page, and the agent never sees the number.
> Every purchase is approved by the user, with a passkey or Face ID, or by an auto-approval they granted. An approval covers one merchant and one exact total. If the total changes, ask again. When a result says the user already said yes, don't ask again.
> `init` writes PRODUCTION credentials, which place real orders, so test in sandbox first. For opencommerce, run `npx agent-cards credentials --mode sandbox` and put the two lines it prints in place of the production ones in the env file `init` wrote, because that command only prints them; sandbox then runs the whole flow against real stores and stops before payment, so no order is placed and nobody is charged. For Vault and Issuing, sandbox credentials issue test cards that no real merchant accepts; try the checkout against shop.agentcard.sh, a test store on Stripe test mode.
> Tell the user an order is placed only after Agentcard reports it placed.
> Vault is free up to 5,000 users (https://agentcard.com/pricing). opencommerce takes 1% of each completed order. Full docs in one file: https://docs.agentcard.com/llms-full.txt

# Jinko

> Use Agentcard with Jinko to pay a travel quote with the traveller's own card from their Vault, while your app keeps its own Jinko integration.

[Jinko](https://gojinko.com) books travel through one API. Your app keeps its own Jinko integration: it searches under its own Jinko key, builds the trip, adds the travellers and calls Jinko's checkout. When the quote accepts a customer card, your app asks Agentcard to pay it instead of collecting a card. The traveller approves the exact total with their passkey, and Agentcard sends their own card to Jinko as a customer card. Jinko charges that card, so the traveller earns their card's usual points, and the card number never reaches your servers.

1. Your app calls Jinko's checkout and gets a quote.
2. Your app sends the quote to Agentcard, and Agentcard answers with an approval link.
3. The traveller opens the link and approves the total with their passkey.
4. Agentcard sends the traveller's card to Jinko and hands you Jinko's answer.
5. Your app follows the payment attempt and the booking with Jinko, as it does today.

> [!NOTE]
>
> Jinko payments are in beta. A field can still change before the API is final.

## What you need

Set these up once in sandbox, and once again in production.

1. Your company's `client_id` and `client_secret`, exchanged for an access token ([Create an access token](https://docs.agentcard.com/api-reference/access-tokens/create.md)). The Commerce SDK uses the same token.
2. The traveller connected to your company with a card in their Vault ([Adding a card](https://docs.agentcard.com/vault/adding-a-card.md), [Check for stored cards](https://docs.agentcard.com/vault/checking-for-stored-cards.md)).
3. Customer cards turned on for your Jinko tenant. Ask Jinko at [dev@gojinko.com](mailto:dev@gojinko.com) to enable the `customer_card` kind, in sandbox and in production separately. Jinko's checkout lists a card entry only for the kinds your tenant has.
4. Jinko's authorization for Agentcard to submit payments on your quotes, in each environment. Agentcard sets this up with you and Jinko before your first payment, and the calls on this page stay the same whichever way Jinko authorizes Agentcard.
5. A webhook endpoint subscribed to `jinko_payment.updated`, if you want each change pushed to you instead of reading the payment.

> [!NOTE]
>
> The way Jinko authorizes Agentcard is being finalized with Jinko. Either Jinko issues Agentcard a key that can only submit payments, or you share a Jinko key with Agentcard, which stores it encrypted.

## Get a quote from Jinko

Call Jinko's checkout with your own Jinko key, as you do today:

```bash theme={null}
curl -X POST https://api.gojinko.com/v1/checkout \
  -H "X-API-Key: $JINKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "trip_id": "<TRIP_ID>" }'
```

Jinko answers with the quote, its deadline and the ways it can be paid. Look for the card entry whose `card_kinds` holds `customer_card`:

```json theme={null}
{
  "quote_id": "<QUOTE_ID>",
  "expires_at": "<QUOTE_EXPIRES_AT>",
  "accepted_payment_types": [
    {
      "type": "card",
      "card_kinds": ["customer_card"],
      "collector": "jinko",
      "submit_url": "https://pay.gojinko.com/v1/agent_payment/submit",
      "authentication": "customer_handoff"
    }
  ]
}
```

A quote with no such entry cannot be paid through Agentcard. Jinko leaves the entry out when your tenant does not have customer cards turned on, so ask Jinko to enable them. [Jinko's card payment guide](https://docs.gojinko.com/guides/partner-card-payments.md) shows the whole answer.

Four parts of the quote become the payment:

| From Jinko's checkout | Send to Agentcard as |
| - | - |
| The trip you checked out | `trip_id` |
| `quote_id` | `quote_id` |
| The card entry's `submit_url` | `submit_url`, unchanged |
| The quote's total and its currency | `amount` and `currency` |

## Ask Agentcard to pay

Get an access token with your client credentials:

```bash theme={null}
curl https://api.agentcard.sh/api/v2/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'
```

Send the quote, the traveller and a key of your own for this payment. Here the quote's total is `$482.30`:

```bash theme={null}
curl -X POST https://api.agentcard.sh/buy/v1/jinko/payments \
  -H "Authorization: Bearer $AGENTCARD_ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "traveller_42",
    "trip_id": "<TRIP_ID>",
    "quote_id": "<QUOTE_ID>",
    "submit_url": "https://pay.gojinko.com/v1/agent_payment/submit",
    "amount": 48230,
    "currency": "USD",
    "idempotency_key": "trip-8841-quote-1-attempt-1"
  }'
```

Agentcard answers `202` with the payment and the link the traveller approves on:

```json theme={null}
{
  "id": "jpay_7c2e9a41d05b3f68",
  "status": "awaiting_approval",
  "trip_id": "<TRIP_ID>",
  "quote_id": "<QUOTE_ID>",
  "amount": 48230,
  "currency": "USD",
  "idempotency_key": "trip-8841-quote-1-attempt-1",
  "approval_url": "https://app.agentcard.sh/a/jpay_7c2e9a41d05b3f68.Y3PU...",
  "expires_at": "2026-11-17T18:45:00Z",
  "jinko": null
}
```

| Field | What to send |
| - | - |
| `external_user_id` or `user_id` | Exactly one. `external_user_id` is your own id for the traveller; `user_id` is the id Agentcard gave you when they connected. |
| `trip_id` | The Jinko trip the quote belongs to. |
| `quote_id` | The `quote_id` from Jinko's checkout. |
| `submit_url` | The card entry's `submit_url`, unchanged. Agentcard pays only at `pay.gojinko.com` and `pay.sandbox.gojinko.com`. |
| `amount` | The quote's total, as an integer in the currency's smallest unit: `48230` is `$482.30`. |
| `currency` | The quote's currency, a three-letter ISO 4217 code such as `USD`. |
| `idempotency_key` | Your key for this payment. The same key returns the same payment. |

Before Agentcard opens the approval, Agentcard reads the quote from Jinko's checkout under your company's Jinko authorization. Agentcard refuses a request whose quote, total or `submit_url` differs from what checkout answers now, so the traveller never approves a total Jinko will not charge:

```text theme={null}
422 {"error":"amount_mismatch","code":"amount_mismatch","message":"amount is 48200 USD, and the quote's total is 48230 USD. Send the quote's total."}
```

Send the quote's total and currency, with a new `idempotency_key`.

## Send the approval link

Send `approval_url` to the traveller wherever you already talk to them: a chat thread, an iMessage, an email, your app ([Choose a platform](https://docs.agentcard.com/vault/platforms/overview.md)). The traveller opens the link, sees the total, and confirms with Face ID, Touch ID, fingerprint, or their master password.

`expires_at` is when the approval link stops working. The quote keeps its own deadline in Jinko's `expires_at`, so send the link as soon as you have it. A quote that lapses before the traveller approves ends the payment as `expired`, and no card is sent. Your webhook endpoint hears the expiry within a minute, whether or not you read the payment.

## Follow the payment

Read the payment at any time:

```bash theme={null}
curl https://api.agentcard.sh/buy/v1/jinko/payments/jpay_7c2e9a41d05b3f68 \
  -H "Authorization: Bearer $AGENTCARD_ORG_TOKEN"
```

| `status` | What it means | What to do |
| - | - | - |
| `awaiting_approval` | The traveller has not approved yet. | Wait, or remind the traveller. |
| `submitting` | The traveller approved, and Agentcard is sending their card to Jinko. | Wait. Never pay the same quote again meanwhile. |
| `submitted` | Jinko answered. `jinko` holds the answer exactly as Jinko sent it. | Act on `jinko.recovery.action`, as the next section shows. |
| `refused` | Jinko holds no payment attempt from this payment. `reason` says why. | Follow [Read a refusal](#read-a-refusal). |
| `expired` | The approval or the quote lapsed before the card was sent. | Call Jinko's checkout again, and create a new payment. |

A submitted payment carries Jinko's payment attempt. Here the traveller's bank asks for 3D Secure:

```json theme={null}
{
  "id": "jpay_7c2e9a41d05b3f68",
  "status": "submitted",
  "trip_id": "<TRIP_ID>",
  "quote_id": "<QUOTE_ID>",
  "amount": 48230,
  "currency": "USD",
  "idempotency_key": "trip-8841-quote-1-attempt-1",
  "approval_url": "https://app.agentcard.sh/a/jpay_7c2e9a41d05b3f68.Y3PU...",
  "expires_at": "2026-11-17T18:45:00Z",
  "jinko": {
    "payment_attempt_id": "<PAYMENT_ATTEMPT_ID>",
    "payment_status": "requires_authentication",
    "recovery": { "action": "authenticate", "replacement_credential_required": false },
    "retry_after_seconds": 2,
    "authentication": { "url": "<AUTHENTICATION_URL>", "expires_at": "<AUTHENTICATION_EXPIRES_AT>" }
  }
}
```

The `jinko` object is Jinko's answer to the card Agentcard sent, with `payment_error` when Jinko named one and `retry_after_seconds` when Jinko asked you to wait, and Agentcard does not read the attempt again. From `submitted` on, your app follows the attempt and the booking with Jinko under your own key.

A payment can read `submitted` with `jinko` set to `null` and `reason: jinko_unanswered`. The card went out, and Agentcard could not learn what Jinko did with it, so the card may have been charged. Before you create another payment for the same quote, read the trip with your Jinko key. Its `payment_attempt` is the trip's newest payment attempt.

```bash theme={null}
curl https://api.gojinko.com/v1/trip/<TRIP_ID> \
  -H "X-API-Key: $JINKO_API_KEY"
```

A payment stays `submitting` only while Agentcard sends the card. If that send stops part way, Agentcard picks the payment up again within about 20 minutes. A payment whose card never left reads `refused` with `reason: interrupted`. For a payment whose card left, Agentcard reads the trip on Jinko once and never sends the card again on its own:

| What the trip shows | What the payment reads |
| - | - |
| A newest attempt on the payment's quote that no earlier payment on the trip received | `submitted`, with that attempt in `jinko`. |
| No attempt, an attempt on another quote, or one an earlier payment already received | `refused` with `reason: needs_reapproval`. |
| Nothing, because the trip could not be read for a day after the card left | `submitted` with `reason: jinko_unanswered`. |

Your webhook endpoint hears each of these.

## Act on Jinko's answer

Branch on `jinko.recovery.action`, never on `payment_status` alone. An authorized attempt can still read `poll` while the booking completes.

| `recovery.action` | What Jinko means | What to do |
| - | - | - |
| `poll` | Jinko is still working on the attempt. | Read the attempt with your Jinko key every `retry_after_seconds`, and follow the booking with your Jinko webhooks. |
| `authenticate` | The traveller's bank asks for 3D Secure. | Send the traveller to `jinko.authentication.url` unchanged, before `jinko.authentication.expires_at`. Then read the attempt. |
| `retry_new_key` | Jinko declined the card and allows another attempt. | Create a new payment with a new `idempotency_key`, as [Retry without paying twice](#retry-without-paying-twice) shows. |
| `recheckout` | The quote can no longer be paid. | Call Jinko's checkout again, and create a new payment for the new quote. |
| `stop` | The attempt is final. `captured` means the traveller paid. | Read the booking with Jinko. |
| `contact_support` | Jinko cannot settle the outcome alone. | Give Jinko the `payment_attempt_id`. |

Read the attempt with your own Jinko key:

```bash theme={null}
curl https://api.gojinko.com/v1/trip/<TRIP_ID>/payment_attempts/<PAYMENT_ATTEMPT_ID> \
  -H "X-API-Key: $JINKO_API_KEY"
```

Never ask Agentcard for a second payment to settle an attempt Jinko still reads as `poll`. [Jinko's payment outcomes guide](https://docs.gojinko.com/guides/payment-outcomes.md) defines every status and action.

## Retry without paying twice

A request with the same `idempotency_key` and the same body returns the same payment, with no second approval and no second card sent to Jinko: `202` while it awaits approval, `200` after. After a timeout, send the same request again with the same key. The same key with a different traveller, trip, quote, `submit_url` or amount answers `409 idempotency_key_reused`.

A payment that reads `needs_reapproval` needs the traveller to approve again, because Jinko takes a card again only with its security code. Call Jinko's checkout again, create a new payment with a new `idempotency_key` for the quote it returns, and send the traveller the new link. The traveller pays at most once either way:

* When checkout still returns the interrupted payment's quote, Agentcard sends the new card with the same `Idempotency-Key` header the interrupted payment sent. If the interrupted request made its attempt late, Jinko answers with that attempt and charges nothing more.
* When that quote has expired, which is the usual case since Agentcard waits about 20 minutes before it reads the trip, checkout returns a new quote. Jinko refuses any card on the expired quote, so the new payment is the only one that can charge.

A declined card needs a new payment. Create one with a new `idempotency_key`, on a quote whose `expires_at` has not passed, and only once Jinko's `recovery.action` reads `retry_new_key`. The traveller approves the new payment on a new link. When `jinko.recovery.replacement_credential_required` is true, Jinko refuses the same card again, so the traveller needs another card in their Vault ([Adding a card](https://docs.agentcard.com/vault/adding-a-card.md)).

```bash theme={null}
curl -X POST https://api.agentcard.sh/buy/v1/jinko/payments \
  -H "Authorization: Bearer $AGENTCARD_ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "traveller_42",
    "trip_id": "<TRIP_ID>",
    "quote_id": "<QUOTE_ID>",
    "submit_url": "https://pay.gojinko.com/v1/agent_payment/submit",
    "amount": 48230,
    "currency": "USD",
    "idempotency_key": "trip-8841-quote-1-attempt-2"
  }'
```

## Listen for updates

Your webhook endpoint receives `jinko_payment.updated` each time a payment's `status` changes. Subscribe to it by name:

```bash theme={null}
curl -X POST https://api.agentcard.sh/api/v2/webhook_endpoints \
  -H "Authorization: Bearer $AGENTCARD_ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your.app/agentcard/webhooks", "enabled_events": ["jinko_payment.updated"]}'
```

The event carries the payment as `GET /buy/v1/jinko/payments/:id` returns it:

```json theme={null}
{
  "id": "evt_4d1b8e2f7a90",
  "type": "jinko_payment.updated",
  "created": 1763404800,
  "livemode": false,
  "data": {
    "id": "jpay_7c2e9a41d05b3f68",
    "status": "submitting",
    "trip_id": "<TRIP_ID>",
    "quote_id": "<QUOTE_ID>",
    "amount": 48230,
    "currency": "USD",
    "idempotency_key": "trip-8841-quote-1-attempt-1",
    "approval_url": "https://app.agentcard.sh/a/jpay_7c2e9a41d05b3f68.Y3PU...",
    "expires_at": "2026-11-17T18:45:00Z",
    "jinko": null
  }
}
```

Agentcard delivers each event at least once, so deduplicate on the event's `id`. [Webhooks](https://docs.agentcard.com/webhooks/overview.md) shows how to verify the signature.

## Read a refusal

Agentcard refuses some requests at once and charges nothing:

```text theme={null}
400 {"error":"submit_url_not_allowed","code":"submit_url_not_allowed","message":"submit_url must be on pay.gojinko.com or pay.sandbox.gojinko.com. Send the submit_url from Jinko's checkout unchanged."}
```

| Answer | What happened | What to do |
| - | - | - |
| `400 invalid_request` | A field is missing or malformed. `message` names it. | Fix the field and send again. |
| `400 submit_url_not_allowed` | `submit_url` is not Jinko's pay URL, or the URL is the other mode's: a sandbox token pays only at `pay.sandbox.gojinko.com`, a production token only at `pay.gojinko.com`. | Send the card entry's `submit_url` unchanged, with the token of the quote's mode. |
| `403 client_credentials_required` | The token is a user's, not your company's. | Use your company's client-credentials token. |
| `403 jinko_payments_not_enabled` | Jinko payments are not on for your company yet. | Ask Agentcard. |
| `404 trip_not_found` | Jinko does not know the trip under your company's Jinko authorization. | Send the `trip_id` you checked out. |
| `409 jinko_not_configured` | Agentcard holds no Jinko authorization for your company in this mode. | Ask Agentcard to set it up with you and Jinko. |
| `409 jinko_key_refused` | Jinko refused the authorization Agentcard holds for your company. | Ask Agentcard to set it again. |
| `409 vault_card_missing` | The traveller has no card in their Vault. | Ask them to add one ([Adding a card](https://docs.agentcard.com/vault/adding-a-card.md)), then send again. |
| `409 quote_changed` | Jinko's checkout answers another quote for this trip now. | Send the quote checkout returns, with its total. |
| `409 customer_card_not_accepted` | Jinko's checkout lists no customer card for this quote. | Ask Jinko to turn customer cards on for your tenant. |
| `409 idempotency_key_reused` | The key already names a payment with another body. | Use a new key for a new payment. |
| `410 quote_expired` | The quote expires before the traveller could approve it. | Call Jinko's checkout again and send the new quote. |
| `422 amount_mismatch` | `amount` differs from the quote's total. | Send the quote's total, with a new `idempotency_key`. |
| `422 submit_url_mismatch` | `submit_url` differs from the one Jinko's checkout returns for a customer card. | Send it unchanged. |
| `502 jinko_unavailable` | Jinko's checkout did not answer. | Send the same request again with the same `idempotency_key`. |
| `503 payments_unavailable` | Card payments are not set up for this mode on Agentcard yet. | Ask Agentcard. |
| `503 approval_unavailable` | Agentcard could not open the approval yet. | Send the same request again with the same `idempotency_key`, and Agentcard opens the approval for the same payment. |

A payment Agentcard created can still end with no payment attempt at Jinko. That payment reads `refused` or `expired`, and `reason` says why:

| `reason` | What happened | What to do |
| - | - | - |
| `user_declined` | The traveller declined the approval. | Ask the traveller. A new payment needs a new `idempotency_key`. |
| `approval_expired` | The traveller did not approve before `expires_at`. | Create a new payment, on a new quote if this one lapsed. |
| `quote_expired` | Jinko answered that the quote expired when the card reached it. | Call Jinko's checkout again, and create a new payment. |
| `card_unavailable` | The traveller's approved card could not be prepared for Jinko. | Create a new payment; the traveller approves again. |
| `jinko_refused` | Jinko refused the request before any payment attempt. `jinko.error` holds its code. | Act on Jinko's code. |
| `jinko_idempotency_key_reused` | Jinko already holds another attempt under this payment's key. | Read the trip with your Jinko key before you create a new payment. |
| `forwarding_refused` | Stripe refused to send the card to Jinko, so it never left. | Create a new payment with a new `idempotency_key`, or contact Agentcard. |
| `interrupted` | Agentcard stopped before the card left. | Create a new payment with a new `idempotency_key`; the traveller approves again. |
| `needs_reapproval` | Agentcard stopped after the card left, and the trip on Jinko holds no attempt from it. | Call Jinko's checkout again and create a new payment with a new `idempotency_key`; the traveller approves again, and the card is charged at most once. |
| `approval_already_used`, `payments_unavailable`, `jinko_not_configured` | The approval or Agentcard's setup could not carry the card, and no card left. | Contact Agentcard. |

A payment that reads `submitted` reached Jinko. Every outcome after that is Jinko's, in `jinko.payment_status` and `jinko.recovery`.

## Test in sandbox

Use your sandbox client credentials and your Jinko sandbox tenant with customer cards turned on. Jinko's sandbox checkout returns `https://pay.sandbox.gojinko.com/v1/agent_payment/submit` as the `submit_url`; send it unchanged.

Connect a test traveller, and save one of Jinko's test cards in their Vault. The Vault code that connects a test traveller is always `111111`. Each card takes any future expiry and any three-digit CVC.

| Card | What Jinko does |
| - | - |
| The authorizing card in [Jinko's sandbox guide](https://docs.gojinko.com/guides/testing-in-sandbox) | Authorizes, and captures once the trip books. |
| `4000002760003184` | Asks for 3D Secure: the payment reads `submitted` with `recovery.action` set to `authenticate` and an `authentication.url`. |

Run both before you go live. The authorizing card follows a payment to a booking, and the 3D Secure card sends a traveller through their bank's check.

## Go live

1. Ask Jinko to turn customer cards on for your production tenant.
2. Confirm with Agentcard that Jinko's authorization for your production quotes is in place.
3. Choose Go live in the dashboard, and use your production `client_id` and `client_secret`.
4. Create a webhook endpoint with a production token. An endpoint belongs to one mode.


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