Skip to main content

Saved cards and modes

How to use session modes, saved cards, and the saved-cards APIs with the PCI Component. Staging hosts apply (api.stg.geopagos.io / pci-card-form.stg.geopagos.io).

For the Hybrid one-shot path (new card only), see Quick start and Backend Integration.

Environments​

EnvironmentCDN ({cdn_host})API ({api_host})
Stagingpci-card-form.stg.geopagos.ioapi.stg.geopagos.io
ProductionProvided by GeopagosProvided by Geopagos

API base: https://{api_host}/api/v1.0.

Authentication​

CallerAuth
Your backend (POST /sessions, POST /payment + X-Session-Id, list/delete saved cards)Bearer access token from the Geopagos identity provider (client_credentials) — same as Backend Integration → Authentication
The PCI Component in the browserUses X-Session-Id only (no JWT). Do not call those paths from your backend or page — they are not part of the integrator contract

Never put the access token in the browser.


Session modes​

mode is fixed on POST /sessions. The component cannot change it. Omit it to get Hybrid (1), the default.

modeNameWhat payment/intent doesSession ready to charge?
0MixedSaves the card and returns 200 with its public fieldsNo — save only
1HybridReturns 204Yes
2CompleteReturns 204Yes — can list / reuse saved cards

Five buyer flows​

Complete has three shapes; Hybrid and Mixed each have one:

FlowModeWhat the buyer completes
ANew cardComplete (2)Full card form
BSaved card + selectorComplete (2)Picks a card from the list, enters CVV
CLocked saved cardComplete (2)CVV only (session created with payment_method_id)
DNew cardHybrid (1)Full card form (no saved-card UI)
ESave card onlyMixed (0)Card form only (no other payment methods); the card is saved, no charge via this session

The component picks the UI from session config (including whether saved cards exist). You choose the mode and optional payment_method_id / external_reference when creating the session.


Persistence: external_reference and saving a card​

Owner key​

external_reference is your customer / user id (opaque string). It is the owner key of saved cards for that merchant/tenant. Set it on POST /sessions whenever you want the vault involved (save, list, or lock a card).

Saving a card​

Cards are created only when the component submits the card form. Requirements:

  1. Session has external_reference.
  2. Geopagos has enabled saving for your tenant (save_payment_method_enabled). You cannot turn this on yourself — it is not a merchant-facing setting.

How the buyer opts in depends on the mode:

ModeSavingConsent
Hybrid (1) / Complete (2)Optional. The form shows a “save card” checkbox (new card only)The buyer ticks the checkbox
Mixed (0)Always. Saving the card is the whole flow; there is no checkboxYours to obtain before creating the session: submitting the form saves the card

If saving is not enabled for your tenant, Hybrid and Complete simply never show the checkbox, and POST /sessions with mode: 0 fails with 400 SAVE_PAYMENT_METHOD_NOT_ALLOWED.

What the form sees​

GET /config (header X-Session-Id) exposes modules[].save_payment_method_enabled as true only when Geopagos enabled the feature and the session has external_reference. Otherwise the form never offers save.


Create session (fields for modes & vault)​

POST /api/v1.0/sessions — Bearer token required.

curl -X POST 'https://{api_host}/api/v1.0/sessions' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-d '{
"amount": 55555.00,
"merchant_id": "<merchant account id>",
"mode": 2,
"external_reference": "customer-42",
"payment_method_id": null
}'
FieldTypeDescription
amountdecimalRequired for Hybrid/Complete (> 0, major units). Optional for Mixed (0) — omit or send 0 (save only)
merchant_idstringSee merchant vs tenant credentials
modenumber0 Mixed, 1 Hybrid (default), 2 Complete. 0 requires saving enabled for your tenant (else 400 SAVE_PAYMENT_METHOD_NOT_ALLOWED)
external_referencestringYour customer id. Required for Mixed, and to save cards, list them in Complete, or lock payment_method_id. A Mixed session without it fails on submit with EXTERNAL_REFERENCE_REQUIRED
payment_method_iduuidOptional. Locks the session to that owned card (Complete only). Requires external_reference. Flow C: CVV-only UI; buyer cannot switch cards — create a new session instead

Saved-cards APIs​

Cards are never created with a dedicated “vault create” endpoint — only by the component, as described in Saving a card.

In Complete, the component loads saved cards on its own when the session has external_reference. That path is not part of the integrator API — use the JWT list below from your backend.

List (your backend — JWT)​

curl -X GET 'https://{api_host}/api/v1.0/saved-cards?external_reference=customer-42' \
-H 'Authorization: Bearer <access_token>'

Public fields only (no card token):

[
{
"payment_method_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"type": "card",
"brand": "visa",
"last4": "4242",
"exp": "12/28"
}
]

Use this for your own account UI or to pick a payment_method_id before creating a locked session (flow C).

Soft-delete (your backend — JWT)​

The component does not delete cards. Soft-delete requires your Bearer token and the owner key:

curl -X DELETE 'https://{api_host}/api/v1.0/saved-cards/{paymentMethodId}?external_reference=customer-42' \
-H 'Authorization: Bearer <access_token>'

Returns 204 on success.


Mode-specific behaviour​

Hybrid (1) — flow D​

Same as Backend Integration: intent → 204 → your backend charges with { "email" } (unless you use collectEmail on Complete/Hybrid as documented in Configuration). No saved-card list.

Optional: set external_reference and let the buyer save the card (if Geopagos enabled saving).

Complete (2) — flows A, B, C​

  • Create session with mode: 2 and usually external_reference.
  • A: no cards yet → full form; optional save with consent.
  • B: cards exist → component shows them + “new card” (you do not call a list endpoint).
  • C: pass payment_method_id (owned by that external_reference) → CVV only.
  • Intent → 204 → charge from your backend like Hybrid.

Mixed (0) — flow E​

Save card only. The component shows just the card form and always saves the card: there is no checkbox, so get the buyer's consent before creating the session. Intent returns 200 with the saved card's public fields:

{
"payment_method_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"brand": "visa",
"last4": "1111",
"exp": "12/26"
}

The session is not ready to pay. Do not call POST /payment for Mixed. onSubmit may carry this payload as result (see Lifecycle Hooks).

You do not need a charge amount: omit amount on POST /sessions (or send 0). You do need external_reference, and saving must be enabled for your tenant (see Saving a card).


Charge rejected: CVV retry (saved card)​

After a failed POST /payment (with X-Session-Id) when the session used a saved card (CVV was required), the BFF clears the ephemeral CVV and may allow the same session to continue.

Hint on the charge error​

{
"message_code": "PAYMENT_REJECTED",
"retry": {
"allowed": true,
"reason": "cvv_required",
"session_id": "3f8a2b1c9d4e5f60718293a4b5c6d7e8"
}
}
retry.allowedreasonWhat you should do
truecvv_requiredRemount the component with the same session_id (do not create a new session)
falsecvv_refresh_limitCVV re-capture attempts exhausted (max 3). Create a new session or another flow

There is no CVV field on POST /payment. CVV always stays in the component → intent (JWE).

What the component sees on remount​

GET /config (header X-Session-Id) returns 200 with:

  • payment_method_id — locked / selected saved card
  • requires_cvv: true — show CVV-only UI

Then the component posts a new CVV JWE via payment/intent (204). Your backend calls POST /payment again with the same X-Session-Id.

If attempts are exhausted, further refresh fails with CVV_REFRESH_LIMIT and config treats the session as no longer open for CVV remount.


Endpoint summary​

MethodPathAuthWho
POST/sessionsJWTYour backend
POST/paymentJWT + X-Session-IdYour backend
GET/saved-cards?external_reference=JWT (no X-Session-Id)Your backend
DELETE/saved-cards/{id}?external_reference=JWT (no X-Session-Id)Your backend

The session_id goes in X-Session-Id, never in the URL. Paths /{sessionId}/… no longer exist.

config, payment/intent, installments, and any session-scoped payment-methods paths the component may use are not integrator endpoints — do not call them from your backend.