Skip to main content
Jinko 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.
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). The Commerce SDK uses the same token.
  2. The traveller connected to your company with a card in their Vault (Adding a card, Check for stored cards).
  3. Customer cards turned on for your Jinko tenant. Ask Jinko at 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.
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:
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:
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 shows the whole answer. Four parts of the quote become the payment:

Ask Agentcard to pay

Get an access token with your client credentials:
Send the quote, the traveller and a key of your own for this payment. Here the quote’s total is $482.30:
Agentcard answers 202 with the payment and the link the traveller approves on:
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:
Send the quote’s total and currency, with a new idempotency_key. Send approval_url to the traveller wherever you already talk to them: a chat thread, an iMessage, an email, your app (Choose a platform). 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:
A submitted payment carries Jinko’s payment attempt. Here the traveller’s bank asks for 3D Secure:
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.
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: 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. Read the attempt with your own Jinko key:
Never ask Agentcard for a second payment to settle an attempt Jinko still reads as poll. Jinko’s payment outcomes guide 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).

Listen for updates

Your webhook endpoint receives jinko_payment.updated each time a payment’s status changes. Subscribe to it by name:
The event carries the payment as GET /buy/v1/jinko/payments/:id returns it:
Agentcard delivers each event at least once, so deduplicate on the event’s id. Webhooks shows how to verify the signature.

Read a refusal

Agentcard refuses some requests at once and charges nothing:
A payment Agentcard created can still end with no payment attempt at Jinko. That payment reads refused or expired, and reason says why: 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. 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.