When to use
Use this guide to integrate raw customer cards or virtual credit cards (VCCs) through the REST API, using the typed payment submission. Start with a trip containing the selected items and travelers; see Flight booking. Checkout discovery → submit to the returned pay URL → read the outcome → follow its recovery action.Card payments require PCI DSS compliance (see Activation) and are available to partners Jinko has enabled, in production and in sandbox: email dev@gojinko.com to enable yours. Test in sandbox gives the sandbox pay URL and the test card numbers.
Discover what the tenant may use
Call checkout with your tenant-bound booking key. The examples use placeholders only.accepted_payment_types lists only presently usable combinations. A card entry has type: "card", card_kinds (customer_card or vcc), required headers and fields, and authentication (customer_handoff or unavailable). A customer-card entry can advertise customer_handoff, and a VCC has no handoff. A card entry always carries submit_url and collector, which reads jinko: Jinko charges the card. Use that submit_url for the submission instead of hard-coding a hostname.
Checkout lists one card entry per card kind. A tenant enabled for both kinds gets two entries, one with card_kinds: ["vcc"] and one with card_kinds: ["customer_card"], each with its own authentication: read the entry whose card_kinds contains the kind you will send. A tenant that is not enabled for cards gets no card entry at all.
Use the quote ID and deadline that checkout returns. Never send card data speculatively: submit a card only when checkout lists card with the card kind you intend to use.
Submit a card payment
Raw customer cards and VCCs go to the pay URL that checkout discovery returns (submit_url on the card entry): https://pay.gojinko.com/v1/agent_payment/submit in production and https://pay.sandbox.gojinko.com/v1/agent_payment/submit in sandbox. The URL differs by environment: always use the one checkout returns and never hard-code a hostname.
Never send raw cards to api.gojinko.com. Its own POST /v1/agent_payment/submit accepts shared payment tokens only and refuses type: "card" with 400 CREDENTIAL_FORMAT_INVALID.
The pay URL uses the same headers, typed JSON body shape, response envelope and payment status codes as api.gojinko.com. Authenticate with a tenant-bound booking key (jnk_…), sent as X-API-Key or as Authorization: Bearer; OAuth/JWT bearer tokens are refused for typed bodies. Idempotency-Key is required.
This curl template sends the body through standard input. Keep real card data out of shell history and command arguments; production requests belong in your secure backend.
submit_url and quote_id. Replace <EXP_MONTH> and <EXP_YEAR> with JSON integers for the credential’s expiration before sending; this placeholder template is not valid JSON until then. Use card_kind: "customer_card" for a customer card. brand and billing_details are optional.
Request fields
The body carriestrip_id, quote_id and payment. An unknown field, a null value and each value the Rule column marks as refused are answered with 400 CREDENTIAL_FORMAT_INVALID, before any payment attempt exists.
The checkout card entry names the fields this trip requires in
requires.fields: send every field it lists.
Card brand
payment.brand is optional: visa, mastercard, amex, discover, diners, jcb or unionpay. Send the brand when you know it; an attempt without it proceeds.
Card data and resubmission
Send the card number and CVC with every new submission, over HTTPS from your backend. Submitted card details can be used for a short time only. When an accepted attempt can no longer use them, it returnspayment_error.code: "CARD_ALIAS_EXPIRED". Follow recovery.action: retry_new_key (submit the card again to the pay URL with a new Idempotency-Key), poll while the attempt reads cancelling (resubmit only once the action changes), or recheckout once the quote has expired.
Every new card submission needs a new Idempotency-Key: the same key replays the same attempt, and a different card sent under it is not tried. See Retries never charge twice for the full rules.
When the submission answers 503
A 503TEMPORARILY_UNAVAILABLE answer carries no payment_attempt_id, so it does not tell you whether an attempt was created. Send the same request again, with the same card and the same Idempotency-Key. Wait for Retry-After when the answer carries it. The answer can also come with no Retry-After, no payment_error and no recovery; wait a few seconds, then send it again. Do not switch to a new key: if the first request did create an attempt, the same key returns that attempt’s outcome instead of charging again.
Read the outcome
The card submission answers with the samePaymentAttemptOutcome as every typed payment. Read it, poll the attempt while its recovery.action is poll, and follow its action as described in Payment outcomes and retries. The sections below cover how card outcomes are handled.
Customer authentication handoff
authentication is returned only for customer_card attempts in requires_authentication, with recovery.action: "authenticate". Send the customer to the returned authentication.url unchanged before authentication.expires_at. Never parse or reconstruct it. Keep polling GET /v1/trip/{trip_id}/payment_attempts/{payment_attempt_id} while the customer authenticates. The handoff completes 3-D Secure (3DS) on the existing attempt. A VCC never receives an authentication handoff.
After the customer returns, read the attempt. A browser return is not proof of authorization. Closing the browser before the deadline does not itself prove failure; poll. A verified authentication failure requires cleanup. Authentication still incomplete at the deadline becomes abandoned; poll cleanup, then recheckout when instructed.
VCC policy
A VCC has no customer authentication handoff. If a VCC needs authentication, do not open a hosted payment flow or ask a traveler to authenticate it. Obtain a replacement credential that can complete without a handoff. Wait until the attempt permits replacement and cleanup is complete; then use a new key on a valid quote, or recheckout as directed. Fulfillment never falls back to hosted payment for a VCC.Card outcome codes
These codes need card-specific handling. Every code, and the action it asks for, is listed under Payment outcome codes. Always obey the returnedrecovery.action.
Quiescent means the earlier attempt has finished cleanup and the returned recovery action permits another attempt.
Failure table
Statuses can change during cleanup. Read the latest outcome and its recovery action before acting.Money outcomes after booking
Readmoney as described in Money outcomes after booking.
Test in sandbox
Once your sandbox tenant is enabled (see Activation), the flow is the same as in production: call checkout onhttps://api.sandbox.gojinko.com with a sandbox key, then submit the card to the submit_url it returns, https://pay.sandbox.gojinko.com/v1/agent_payment/submit. Testing in sandbox describes the test flights to put in the trip.
Use the card numbers below, with any expiration date in the future and any three-digit CVC. Never send a real card number in sandbox.
The spaces are for reading only: send each number as digits.
Security and data handling
Send credentials only from your secure backend over HTTPS. Raw card data must never pass through prompts, MCP, CLI arguments, logs, traces, analytics, support tickets, or stored request bodies. The examples contain placeholders, not usable card credentials. Jinko never returns the card number or CVC in a response. Keep attempt, trip, quote, and request identifiers for recovery and support: the pay URL returnsX-Jinko-Request-ID on every answer; quote it when you contact support. The X-Request-ID on the answer can differ from the one you sent, so identify a submission by X-Jinko-Request-ID. Never include the card data when reporting an issue.
Activation
Card payments require your organization to be PCI DSS compliant. Your backend receives and sends card numbers and CVCs, so the systems that handle them are in scope for PCI DSS. Card kinds are disabled per tenant by default. Email dev@gojinko.com to arrange enablement, then confirm that checkout listscard with the card kind you need. Production and sandbox are enabled separately: say which one you need.
MCP and CLI remain SPT-only. Use the typed REST contract for raw customer cards and VCCs.