Skip to main content

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​

EnvironmentCDN ({cdn_host})API ({api_host})
Stagingpci-card-form.stg.geopagos.ioapi.stg.geopagos.io
ProductionProvided by GeopagosProvided 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'
EnvironmentIdentity provider ({idp_host})
Stagingidp.stg.geopagos.io
ProductionProvided 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:

CredentialsWho uses themmerchant_id on POST /sessions
MerchantA merchant that charges for itself. The token identifies that merchantOptional. If you send it, it must be that same merchant, or the request fails with MERCHANT_MISMATCH
TenantA 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​

FieldTypeDescription
amountdecimalRequired 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_idstringMerchant 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
modenumberOptional. 0 Mixed, 1 Hybrid (default if omitted), 2 Complete. This page documents Hybrid; see Saved cards and modes for the others
external_referencestringOptional here. Your customer id — required to save or list cards. See Saved cards and modes
payment_method_iduuidOptional. Locks Complete to a saved card (CVV-only). Requires external_reference

Responses​

StatusMeaning
201Session created. Returns session_id
400Invalid request, or merchant context error — discriminate by message_code (see below)
401Invalid or missing token
403Valid token without sufficient permissions
500Internal error
message_codeMeaning
MERCHANT_REQUIREDTenant credentials and no merchant_id in the body
MERCHANT_MISMATCHMerchant credentials and a merchant_id that is not the token's merchant
MERCHANT_NOT_FOUNDTenant 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_ALLOWEDmode: 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​

FieldTypeDescription
emailstringRequired 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.

StatusMeaning
200Processed. Check success and status
400Rejected by the issuer, missing/invalid email, or other invalid request — discriminate by message_code
401Invalid or missing token, or session not found / expired (SESSION_NOT_FOUND, SESSION_EXPIRED)
403Valid token without sufficient permissions
409Session already used (SESSION_USED)
502Upstream 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_codeMeaning
EMAIL_REQUIREDemail was missing or empty
EMAIL_INVALIDemail 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_codeMeaning
PAYMENT_REJECTEDGeneric rejection
PAYMENT_REJECTED_INSUFFICIENT_FUNDSInsufficient funds
PAYMENT_REJECTED_CALL_FOR_AUTHThe issuer requires authorization by phone
PAYMENT_REJECTED_DECLINEDDeclined by the issuer
PAYMENT_REJECTED_INVALID_CARDInvalid card
PAYMENT_REJECTED_INVALID_TRANSACTIONInvalid transaction
PAYMENT_REJECTED_INVALID_MERCHANTInvalid merchant
PAYMENT_REJECTED_INVALID_ORDERInvalid order
PAYMENT_REJECTED_MAX_ATTEMPTSMaximum attempts exceeded
PAYMENT_REJECTED_SYSTEM_ERRORIssuer-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.