- Your app calls Jinko’s checkout and gets a quote.
- Your app sends the quote to Agentcard, and Agentcard answers with an approval link.
- The traveller opens the link and approves the total with their passkey.
- Agentcard sends the traveller’s card to Jinko and hands you Jinko’s answer.
- 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.- Your company’s
client_idandclient_secret, exchanged for an access token (Create an access token). The Commerce SDK uses the same token. - The traveller connected to your company with a card in their Vault (Adding a card, Check for stored cards).
- Customer cards turned on for your Jinko tenant. Ask Jinko at dev@gojinko.com to enable the
customer_cardkind, in sandbox and in production separately. Jinko’s checkout lists a card entry only for the kinds your tenant has. - 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.
- 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:card_kinds holds customer_card:
Ask Agentcard to pay
Get an access token with your client credentials:$482.30:
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:
idempotency_key.
Send the approval link
Sendapproval_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:
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.
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 onjinko.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:
poll. Jinko’s payment outcomes guide defines every status and action.
Retry without paying twice
A request with the sameidempotency_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-Keyheader 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.
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 receivesjinko_payment.updated each time a payment’s status changes. Subscribe to it by name:
GET /buy/v1/jinko/payments/:id returns it:
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 returnshttps://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
- Ask Jinko to turn customer cards on for your production tenant.
- Confirm with Agentcard that Jinko’s authorization for your production quotes is in place.
- Choose Go live in the dashboard, and use your production
client_idandclient_secret. - Create a webhook endpoint with a production token. An endpoint belongs to one mode.