Backend Integration
One-shot tokenized payment through the component in Hybrid mode (mode: 1, the
session default). Your backend creates the session before the form is rendered, and
charges it after the buyer confirms. Everything in between happens inside the component.
For Complete / Mixed, saved cards, external_reference, saved-cards APIs, and CVV
retry after a declined charge, see Saved cards and modes.
For the visual sequence, see Geopagos PCI Component.
YOUR BACKEND POST /api/v1.0/sessions ─────────────► session_id
YOUR PAGE new Checkout(session_id).render(…)
BUYER fills in the card and confirms
COMPONENT POST /payment/intent + X-Session-Id ─► 204, session ready to charge
YOUR BACKEND POST /api/v1.0/payment ──────────────► charge executed
(Bearer JWT + X-Session-Id + { "email" })
The session_id travels in the X-Session-Id header on checkout and charge calls. It does
not go in the URL. Paths like /{sessionId}/payment no longer exist.
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 |
The API base URL is https://{api_host}/api/v1.0.
Authentication
Authenticated merchant-backend endpoints (including POST /sessions,
POST /payment with X-Session-Id, and the saved-cards list/delete APIs) take the same
Authorization: Bearer <access_token> header: an OAuth 2.0 access token issued by the
Geopagos identity provider with the client_credentials grant. Geopagos provides the
credentials (client_id, client_secret) and the realm. Paths the component calls with
X-Session-Id alone (no JWT) are not part of the integrator contract — see
Saved cards and modes.
curl -X POST 'https://{idp_host}/auth/realms/{realm}/protocol/openid-connect/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
-d 'client_id=<client id provided by Geopagos>' \
-d 'client_secret=<client secret provided by Geopagos>' \
-d 'scope=openid'
| Environment | Identity provider ({idp_host}) |
|---|---|
| Staging | idp.stg.geopagos.io |
| Production | Provided by Geopagos |
Send the access_token from the response as the Bearer token. Request a new one when it
expires (expires_in). Call both endpoints from your server only: a token in the browser is a
published token.
Merchant or tenant credentials
The token always identifies your tenant. Whether it also identifies a merchant depends on the credentials Geopagos issued to you:
| Credentials | Who uses them | merchant_id on POST /sessions |
|---|---|---|
| Merchant | A merchant that charges for itself. The token identifies that merchant | Optional. If you send it, it must be that same merchant, or the request fails with MERCHANT_MISMATCH |
| Tenant | A platform that charges on behalf of several merchants of its tenant (e.g. a marketplace or delivery app) | Required. It is the merchant this session charges for, and it must belong to your tenant. Without it the request fails with MERCHANT_REQUIRED; with an unknown merchant, with MERCHANT_NOT_FOUND |
merchant_id is the merchant's account id in Geopagos. The merchant is fixed when the
session is created: the charge does not take a merchant_id and is always made for the
session's merchant. Use the same credentials for the session and its charge.
1. Create the payment session
POST /api/v1.0/sessions must be called from your server with the Bearer token described in
Authentication.
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": 1
}'
With merchant credentials you can leave out merchant_id.
{ "session_id": "3f8a2b1c9d4e5f60718293a4b5c6d7e8" }
Request body
| Field | Type | Description |
|---|---|---|
amount | decimal | Required for Hybrid (1) and Complete (2). Major units (e.g. 55555.00), must be greater than zero. Fixed for the session (installments and payment). Optional for Mixed (0) — omit it or send 0 (save card only; no charge) |
merchant_id | string | Merchant account id in Geopagos. Required with tenant credentials. Optional with merchant credentials, and then it must be the token's merchant. See Merchant or tenant credentials |
mode | number | Optional. 0 Mixed, 1 Hybrid (default if omitted), 2 Complete. This page documents Hybrid; see Saved cards and modes for the others |
external_reference | string | Optional here. Your customer id — required to save or list cards. See Saved cards and modes |
payment_method_id | uuid | Optional. Locks Complete to a saved card (CVV-only). Requires external_reference |
Responses
| Status | Meaning |
|---|---|
201 | Session created. Returns session_id |
400 | Invalid request, or merchant context error — discriminate by message_code (see below) |
401 | Invalid or missing token |
403 | Valid token without sufficient permissions |
500 | Internal error |
message_code | Meaning |
|---|---|
MERCHANT_REQUIRED | Tenant credentials and no merchant_id in the body |
MERCHANT_MISMATCH | Merchant credentials and a merchant_id that is not the token's merchant |
MERCHANT_NOT_FOUND | Tenant credentials and a merchant_id that does not exist or does not belong to your tenant. Do not retry: fix the merchant_id |
SAVE_PAYMENT_METHOD_NOT_ALLOWED | mode: 0 (Mixed) on a tenant without card saving enabled. Do not retry: ask Geopagos to enable it — see Saved cards and modes |
Session lifetime
The session expires in 15 minutes by default (configurable per tenant) and is single-use
for the charge. Once expired, unknown or already used, the form shuts down with
SESSION_INVALID and the only recovery is creating a new session from your backend.
Create the session as close as possible to rendering the form — not when the cart page loads.
2. Render the component
Hand the session_id to your page and render the component — see
Quick start and Embedding the component. Nothing else travels
from your backend to the browser: the amount and the merchant already live in the session.
3. Charge the session
When onSubmit fires, the component has already called payment/intent with the encrypted
card fields (and cardholder document). The session holds the tokenized card, amount and
installment. The charge itself is yours to run, from your backend, with the same kind of
Bearer token you used to create the session (same credentials). It is made for the
merchant fixed on the session, so it takes no merchant_id.
In Hybrid the component does not collect the cardholder email. Your backend must send it on the charge:
curl -X POST 'https://{api_host}/api/v1.0/payment' \
-H 'Authorization: Bearer <access_token>' \
-H 'X-Session-Id: 3f8a2b1c9d4e5f60718293a4b5c6d7e8' \
-H 'Content-Type: application/json' \
-d '{
"email": "buyer@example.com"
}'
Send the session_id from POST /sessions in X-Session-Id. Do not put it in the path.
Request body
| Field | Type | Description |
|---|---|---|
email | string | Required for this flow. Cardholder email used on the charge. Must be a valid email address |
{
"success": true,
"referenceNumber": "1197088126",
"status": "APPROVED"
}
referenceNumber is the payment reference from the processor. Keep it for reconciliation; it is
not related to any field on the create-session request.
| Status | Meaning |
|---|---|
200 | Processed. Check success and status |
400 | Rejected by the issuer, missing/invalid email, or other invalid request — discriminate by message_code |
401 | Invalid or missing token, or session not found / expired (SESSION_NOT_FOUND, SESSION_EXPIRED) |
403 | Valid token without sufficient permissions |
409 | Session already used (SESSION_USED) |
502 | Upstream failure |
Errors follow the standard shape:
{
"app_name": "pci-card-form-backend",
"app_version": "1.0.0",
"status_code": 400,
"message": "Insufficient funds",
"message_code": "PAYMENT_REJECTED_INSUFFICIENT_FUNDS"
}
Email validation codes
message_code | Meaning |
|---|---|
EMAIL_REQUIRED | email was missing or empty |
EMAIL_INVALID | email is not a valid email address |
Issuer rejections are yours to handle
Insufficient funds, invalid card, "call for authorization": none of that reaches the component.
It is returned by POST /payment (with X-Session-Id), which your backend calls. The
component stops at payment/intent, which only leaves the session ready to charge.
Which means the "insufficient funds" message is yours to show. These come back with HTTP
400 — indistinguishable by status from a validation error — so discriminate them by
message_code:
message_code | Meaning |
|---|---|
PAYMENT_REJECTED | Generic rejection |
PAYMENT_REJECTED_INSUFFICIENT_FUNDS | Insufficient funds |
PAYMENT_REJECTED_CALL_FOR_AUTH | The issuer requires authorization by phone |
PAYMENT_REJECTED_DECLINED | Declined by the issuer |
PAYMENT_REJECTED_INVALID_CARD | Invalid card |
PAYMENT_REJECTED_INVALID_TRANSACTION | Invalid transaction |
PAYMENT_REJECTED_INVALID_MERCHANT | Invalid merchant |
PAYMENT_REJECTED_INVALID_ORDER | Invalid order |
PAYMENT_REJECTED_MAX_ATTEMPTS | Maximum attempts exceeded |
PAYMENT_REJECTED_SYSTEM_ERROR | Issuer-side system error |
Retry after a declined charge (saved card)
When the session charged a saved card, a failed payment may include a retry object:
{
"message_code": "PAYMENT_REJECTED",
"retry": {
"allowed": true,
"reason": "cvv_required",
"session_id": "3f8a2b1c9d4e5f60718293a4b5c6d7e8"
}
}
If retry.allowed is true and reason is cvv_required, remount the component with the
same session_id so the buyer can enter CVV again — do not create a new session. If
reason is cvv_refresh_limit, attempts are exhausted; start a new session.
Full contract: Saved cards and modes → CVV retry.
Security note
POST /sessions and POST /payment require a Bearer access token issued with the same
credentials (see Authentication). The session_id in X-Session-Id
identifies which ready session to charge; it is not sufficient authorization by itself.
Keep your client_secret and access tokens on your server.
Call the charge from your backend only — never from the browser. Treat the session_id as a
capability: do not log it where it can leak, and do not expose it beyond the page that renders
the form. CVV is never accepted on the payment body.