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
| Environment | CDN ({cdn_host}) | API ({api_host}) |
|---|---|---|
| Staging | pci-card-form.stg.geopagos.io | api.stg.geopagos.io |
| Production | Provided by Geopagos | Provided by Geopagos |
API base: https://{api_host}/api/v1.0.
Authentication
| Caller | Auth |
|---|---|
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 browser | Uses 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.
mode | Name | What payment/intent does | Session ready to charge? |
|---|---|---|---|
0 | Mixed | Saves the card and returns 200 with its public fields | No — save only |
1 | Hybrid | Returns 204 | Yes |
2 | Complete | Returns 204 | Yes — can list / reuse saved cards |
Five buyer flows
Complete has three shapes; Hybrid and Mixed each have one:
| Flow | Mode | What the buyer completes | |
|---|---|---|---|
| A | New card | Complete (2) | Full card form |
| B | Saved card + selector | Complete (2) | Picks a card from the list, enters CVV |
| C | Locked saved card | Complete (2) | CVV only (session created with payment_method_id) |
| D | New card | Hybrid (1) | Full card form (no saved-card UI) |
| E | Save card only | Mixed (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:
- Session has
external_reference. - 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:
| Mode | Saving | Consent |
|---|---|---|
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 checkbox | Yours 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
}'
| Field | Type | Description |
|---|---|---|
amount | decimal | Required for Hybrid/Complete (> 0, major units). Optional for Mixed (0) — omit or send 0 (save only) |
merchant_id | string | See merchant vs tenant credentials |
mode | number | 0 Mixed, 1 Hybrid (default), 2 Complete. 0 requires saving enabled for your tenant (else 400 SAVE_PAYMENT_METHOD_NOT_ALLOWED) |
external_reference | string | Your 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_id | uuid | Optional. 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: 2and usuallyexternal_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 thatexternal_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.allowed | reason | What you should do |
|---|---|---|
true | cvv_required | Remount the component with the same session_id (do not create a new session) |
false | cvv_refresh_limit | CVV 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 cardrequires_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
| Method | Path | Auth | Who |
|---|---|---|---|
POST | /sessions | JWT | Your backend |
POST | /payment | JWT + X-Session-Id | Your 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.
Related
- Backend Integration — Hybrid charge path and IdP token
- Lifecycle Hooks —
onSubmit/ Mixedresult - Error Handling —
SESSION_INVALID, issuer declines on the charge - Security — trust model