En la integración estándar, tu botón de Google Pay declara tokenizationSpecification.type: "PAYMENT_GATEWAY" con gateway: "conektagpay". Google cifra el token con la llave de Conekta, tu backend nos lo envía como lo devuelve Google y Conekta lo desencripta.

Esta guía cubre el flujo alterno: configuras tu botón con tokenizationSpecification.type: "DIRECT" y tu propia llave pública, así que Google cifra el token para ti, tú lo desencriptas y envías el contenido ya desencriptado.

🚧

Requiere habilitación y certificación PCI DSS

Este flujo está disponible solo para comercios con PCI DSS vigente y se habilita por cuenta.

📘

DIRECT no es lo mismo que "Direct API"

DIRECT es uno de los dos valores de tokenizationSpecification.type en la librería de Google Pay, y define a qué llave se cifra el token.

1. Cuándo usar este flujo

Se recomienda si necesitas que el token de Google Pay no quede atado a un solo procesador.

2. Métodos de autenticación soportados

Se aceptan los dos métodos de Google Pay, y cada uno se procesa distinto:

⚠️

Sin three_ds_mode, un PAN_ONLY no traslada la responsabilidad

Si no envías three_ds_mode, el cargo PAN_ONLY viaja al banco sin autenticar, como una tarjeta digitada: sin criptograma y sin indicador de wallet. No se rechaza, pero tampoco hay traslado de responsabilidad al emisor. CRYPTOGRAM_3DS no tiene este problema: la autenticación ya viaja dentro del criptograma.

📘

Con 3DS, el return_url va a nivel orden

Si usas three_ds_mode con PAN_ONLY, envía return_url como atributo de la orden. No uses checkout.success_url: Conekta lo interpreta como un checkout hosteado.

3. Construye el payload desencriptado

Toma el mensaje que obtuviste al desencriptar el token de Google, serialízalo y codifícalo en Base64 estándar, con un máximo de 8,192 bytes.

// message = JSON obtenido al desencriptar el token de Google Pay
const data = Buffer.from(JSON.stringify(message)).toString('base64');

El JSON conserva el formato de Google. Conekta valida lo siguiente, y rechaza la petición si falta o viene mal formado:

🚧

El mensaje vencido se rechaza

Google pide a los integradores descartar cualquier mensaje cuyo messageExpiration ya pasó, y Conekta aplica la misma regla. Calcula la vigencia al momento de cobrar, no al construir el payload.

4. Crea el cargo

Envía el payload dentro de google_payment.decrypted_payment_data e incluye "source": "merchant_decrypted". Todos los parámetros de la tabla son obligatorios.

curl --location 'https://api.conekta.io/orders' \
--header 'Accept: application/vnd.conekta-v2.3.0+json' \
--header 'Content-type: application/json' \
--header 'Authorization: Bearer key_YOUR_PRIVATE_API_KEY' \
--data '{
    "currency": "MXN",
    "customer_info": { "customer_id": "cus_xxxxxxxxxxxx" },
    "line_items": [{ "name": "Vasija de Cerámica", "unit_price": 20000, "quantity": 1 }],
    "charges": [{
        "payment_method": {
            "type": "google",
            "source": "merchant_decrypted",
            "google_payment": {
                "decrypted_payment_data": { "data": "eyJtZXNzYWdlRXhwaXJhdGlvbiI6IjE3OTAwMDAwMDAwMDAi..." },
                "info": { "card_network": "VISA", "card_details": "2346", "card_funding_source": "CREDIT" },
                "description": "Visa •••• 2346"
            }
        }
    }]
}'

La orden pagada regresa payment_status: "paid" y el cargo indica "product_type": "google_pay":

{
    "livemode": false,
    "amount": 20000,
    "currency": "MXN",
    "payment_status": "paid",
    "object": "order",
    "id": "ord_31wKoGLYa9BpeDc4e",
    "charges": {
        "object": "list",
        "has_more": false,
        "total": 1,
        "data": [
            {
                "id": "68a5e90679fcdd001abab412",
                "livemode": false,
                "created_at": 1761004800,
                "currency": "MXN",
                "payment_method": {
                    "auth_code": "249606",
                    "object": "card_payment",
                    "type": "credit",
                    "last4": "2346",
                    "brand": "visa",
                    "country": "MX",
                    "fraud_indicators": [],
                    "three_ds_flow_required": false,
                    "product_type": "google_pay"
                },
                "object": "charge",
                "description": "Payment from order",
                "status": "paid",
                "amount": 20000,
                "paid_at": 1761004800,
                "fee": 2785,
                "customer_id": "cus_xxxxxxxxxxxx",
                "order_id": "ord_31wKoGLYa9BpeDc4e"
            }
        ]
    }
}

El cargo guarda payment_method.source como merchant_decrypted y el auth_method utilizado, para que puedas distinguirlos en tus reportes. El number solo conserva los últimos 4 dígitos.

5. Errores

Si el payload es inválido, la respuesta nombra el campo que falla pero nunca su valor.