Crear un Pago Tokenizado

Esta guía le orienta en la configuración de pagos tokenizados utilizando la Global API de Getnet. Los pagos tokenizados le permiten almacenar de forma segura la información de la tarjeta y procesar cargos recurrentes sin requerir que los clientes vuelvan a introducir los detalles de su tarjeta en cada transacción.

Los pagos tokenizados pueden ser iniciados por el titular de la tarjeta (Cardholder-Initiated Transaction, o CIT) o por el comercio (Merchant-Initiated Transaction, o MIT). La diferencia principal es quién inicia el pago y los valores de credentials_on_file_type utilizados en las peticiones a la API.

Requisitos

Antes de seguir los pasos, necesita:

Crear su cuenta poniéndose en contacto con el equipo de Soporte de Integración para obtener sus credenciales de la API client_id y client_secret.
Generar su token con sus credenciales utilizando el endpoint de Access Token.
Adquirir el paquete Recurrence (Subscriptions) y el paquete Vault, o el paquete Modular con recurrencia y vault.

Getnet proporciona una Postman Collection para ayudarle a replicar estos casos de uso localmente. También puede probar la API en el entorno sandbox utilizando la API Reference disponible en la documentación.

Especificidades de los Casos de Uso

Al integrar cualquier solución de Getnet, se aplican requisitos específicos del mercado. Asegúrese de revisar los recursos a continuación antes de pasar a producción:

También puede utilizar tarjetas de prueba para simular escenarios específicos. Puede encontrar más información sobre los requisitos específicos para cada país en la sección de Developer Resources de la documentación de Getnet.

Entendiendo Card on File (COF) y Tipos de Transacción

Los pagos tokenizados soportan dos tipos de transacción según quién inicie el pago:

Cardholder-Initiated Transaction (CIT) - One Click: El cliente autoriza el pago durante una transacción inicial. Utilice credentials_on_file_type: "ONE_CLICK" para el primer pago y "ONE_CLICK_PAYMENT" para los pagos posteriores.
Merchant-Initiated Transaction (MIT) - Recurrente: El comercio desencadena los pagos en un calendario regular sin requerir la interacción del cliente. Utilice credentials_on_file_type: "RECURRING" para el primer pago y "RECURRING_PAYMENT" para los pagos posteriores.

Para obtener información detallada sobre los valores de credentials_on_file_type, consulte Pagos Recurrentes.

Nota para Argentina: Argentina utiliza una estructura diferente para marcar las transacciones recurrentes. Para Argentina, debe incluir el objeto additional_data.recurring en lugar de credentials_on_file_type. El objeto debe contener:

payments_identification (String): Una descripción de la transacción recurrente

sequence (String): Establecido como "FIRST" para la primera transacción recurrente, o "SUBSEQUENT" para las transacciones posteriores

billing_period (String): Mes y año en que se lanzará la transacción (formato: MM/YYYY o MMYYYY)

transaction_identifier (String): Para las transacciones posteriores, incluya el identificador de transacción del primer pago

Para obtener información general sobre los pagos recurrentes, incluyendo los tipos de pagos recurrentes y la disponibilidad regional, consulte Pagos Recurrentes.

Enfoques de tokenización

Puede implementar pagos tokenizados utilizando dos enfoques diferentes de tokenización:

Flujo 1: Tokenizar antes del pago - Tokenice la tarjeta primero utilizando el endpoint de tokenización, luego guárdela en el vault antes de procesar el pago. Este método le permite gestionar la tokenización y el almacenamiento en el vault de forma separada del procesamiento del pago.
Flujo 2: Tokenizar durante el pago - Envíe el número de la tarjeta en formato original (raw) en la petición de pago con save_card_data: true. Getnet tokenizará automáticamente la tarjeta y la guardará en el vault durante el procesamiento del pago, simplificando la integración.

Elija el enfoque que mejor se adapte a sus necesidades de integración. Ambos enfoques funcionan tanto para los tipos de transacción CIT como MIT.

Una vez que la tarjeta está almacenada en el vault, la forma recomendada de reutilizarla en pagos posteriores es enviar únicamente su card_id en el bloque card. Getnet localiza la tarjeta almacenada y completa el resto de los campos de la tarjeta de forma transparente.

Esto es importante porque el number_token almacenado se renueva con el tiempo. Para reutilizar una tarjeta mediante number_token, primero debe llamar a Get Card by ID para recuperar el token actual antes de cada pago. Enviar card_id evita esa llamada adicional: Getnet resuelve el token actual por usted. Consulte los pasos de pago posterior a continuación para ver ejemplos.

Flujo 1: Tokenizar antes del pago

Este enfoque implica tokenizar la tarjeta primero utilizando el endpoint de tokenización, luego guardarla en el vault y finalmente utilizarla en las peticiones de pago. Este método le permite gestionar la tokenización y el almacenamiento en el vault de forma separada del procesamiento del pago.

Visión general del proceso

Para este flujo, el proceso funciona de la siguiente manera:

Registrar un cliente: Cree un registro de cliente en el sistema.
Tokenizar la tarjeta: Utilice el endpoint de tokenización para convertir el número original (raw) de la tarjeta en un token seguro.
Guardar la tarjeta en el vault: Almacene la tarjeta tokenizada en el vault de Getnet.
Procesar el primer pago: Realice el primer pago utilizando el número de la tarjeta tokenizada y guarde el transaction_id de la respuesta. Utilice credentials_on_file_type: "ONE_CLICK" para CIT o "RECURRING" para MIT.
Procesar pagos posteriores: Para todos los pagos futuros, utilice credentials_on_file_type: "ONE_CLICK_PAYMENT" (CIT) o "RECURRING_PAYMENT" (MIT) e incluya el transaction_id del primer pago junto con el número de la tarjeta tokenizada.

El siguiente diagrama ofrece una visión general de este proceso:

Paso 1: Registrar un cliente

Para que los pagos tokenizados funcionen, es necesario registrar un cliente. El cliente es el consumidor del producto o servicio.

Utilice el endpoint de Create Customer para registrar los detalles del cliente:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/customers-gwproxy/v1/customers \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --data '{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "customer_id": "customer-123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "document_type": "CPF",
  "document_number": "12345678900",
  "phone_number": "+5511999999999"
}'

Ejemplo de respuesta:

{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "customer_id": "customer-123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "document_type": "CPF",
  "document_number": "12345678900",
  "phone_number": "+5511999999999",
  "created_at": "2025-11-06T10:30:00.000Z"
}

Paso 2 (Opcional): Tokenizar los datos de la tarjeta

Tokenice la tarjeta antes de procesar los pagos. La tokenización mejora la seguridad y reduce el alcance del cumplimiento del PCI DSS al sustituir el número original (raw) de la tarjeta por un token seguro que puede utilizarse para los cargos recurrentes.

Este paso es opcional. El vault acepta un number_token tokenizado o el number de la tarjeta en formato original (raw), por lo que puede omitir la tokenización y enviar el number de la tarjeta directamente en el Paso 3. Tokenice la tarjeta primero cuando quiera gestionar la tokenización de forma separada del almacenamiento en el vault.

El proceso de tokenización requiere el customer_id del Paso 1.

Utilice el endpoint de Card Tokenization para tokenizar la tarjeta:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/cofre-gw-proxy/v1/tokens/card \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --data '{
  "card_number": "5155901222280001",
  "customer_id": "customer-123"
}'

Ejemplo de respuesta:

{
  "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c"
}

Guarde el number_token de la respuesta. Necesitará este token en el Paso 3 para guardar la tarjeta en el vault. El token sustituye al número original (raw) de la tarjeta en todas las peticiones de API posteriores, mejorando la seguridad y reduciendo el alcance del cumplimiento del PCI DSS.

Para obtener todos los detalles sobre la tokenización, consulte la documentación de Tokenización y Vault.

Paso 3: Guardar la tarjeta en el vault

Para los pagos tokenizados, debe guardar la tarjeta en el vault de Getnet. Utilice el endpoint de Store Card in Vault.

Al almacenar la tarjeta en el vault, incluya los siguientes campos:

Campo	Descripción	Requerido
`number_token`	Número de tarjeta tokenizado del Paso 2. Envíe `number_token` o `number`.	Condicional
`number`	Número de tarjeta en formato original (PAN). Envíe `number` o `number_token`.	Condicional
`brand`	Marca de la tarjeta (ej., `"VISA"`, `"MASTERCARD"`)	Sí
`cardholder_name`	Nombre del titular de la tarjeta	Sí
`expiration_month`	Mes de caducidad de la tarjeta	Sí
`expiration_year`	Año de caducidad de la tarjeta	Sí
`customer_id`	ID del cliente del Paso 1	Sí
`verify_card`	Establezca en `true` para verificar la tarjeta	Recomendado
`security_code`	Código de seguridad de la tarjeta (CVV) - obligatorio si `verify_card` es `true`	Condicional

Envíe number_token o number, no ambos. Utilice number_token si tokenizó la tarjeta en el Paso 2, o envíe el number de la tarjeta en formato original (raw) para almacenar la tarjeta sin tokenizarla primero.

Este es un ejemplo de una petición para almacenar la tarjeta en el vault:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/cofre-gw-proxy/v1/cards \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --data '{
  "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
  "brand": "MASTERCARD",
  "cardholder_name": "John Doe",
  "expiration_month": "12",
  "expiration_year": "30",
  "customer_id": "customer-123",
  "verify_card": true,
  "security_code": "123"
}'

La respuesta incluirá un card_id que puede utilizar para futuras referencias.

Ejemplo de respuesta:

{
  "card_id": "e8ad2ae4-9e3e-4532-998f-1a5a11e56e58",
  "last_four_digits": "0001",
  "bin": "515590",
  "expiration_month": 12,
  "expiration_year": 30,
  "brand": "MASTERCARD",
  "cardholder_name": "JOHN DOE",
  "customer_id": "customer-123",
  "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
  "used_at": "2025-11-06T10:38:00.000Z",
  "created_at": "2025-11-06T10:38:00.000Z",
  "updated_at": "2025-11-06T10:38:00.000Z",
  "status": "active",
  "transaction_id": "123456"
}

Guarde el card_id de la respuesta para sus registros.

El transaction_id de esta respuesta del vault es la transacción de verificación de la tarjeta. No es el valor que reutiliza para los pagos posteriores: ese transaction_id proviene de la respuesta del primer pago en el Paso 4.

Paso 4: Procesar el primer pago

Para la primera transacción de pago, debe utilizar el valor de credentials_on_file_type adecuado según su tipo de transacción:

CIT (One Click): Utilice credentials_on_file_type: "ONE_CLICK"
MIT (Recurrente): Utilice credentials_on_file_type: "RECURRING"

Utilice el endpoint de Create Payment:

Ejemplo para CIT (One Click):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187383",
  "data": {
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "ONE_CLICK",
      "card": {
        "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
        "brand": "MASTERCARD",
        "expiration_month": "12",
        "expiration_year": "30",
        "cardholder_name": "John Doe",
        "security_code": "123"
      }
    }
  }
}'

Ejemplo para MIT (Recurrente):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187383",
  "data": {
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "RECURRING",
      "card": {
        "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
        "brand": "MASTERCARD",
        "expiration_month": "12",
        "expiration_year": "30",
        "cardholder_name": "John Doe",
        "security_code": "123"
      }
    }
  }
}'

La respuesta incluirá un transaction_id. Guarde este valor—lo necesitará para todas las transacciones de pago posteriores:

{
  "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75",
  "order_id": "ORDER-10187383",
  "status": "APPROVED",
  "transaction_id": "MCC50205G1020",
  ...
}

Esta respuesta del primer pago no devuelve un card_id. Si utiliza la opción simplificada de card_id en el Paso 5, ese card_id proviene de la respuesta del vault del Paso 3, no de esta respuesta.

El number_token utilizado en el pago debe ser el token obtenido en el Paso 2. Al utilizar number_token, también debe proporcionar la brand, cardholder_name, security_code, expiration_month y expiration_year de la tarjeta en la petición de pago. Estos detalles son obligatorios a pesar de que el propio número de la tarjeta esté tokenizado. La tarjeta debe estar guardada en el vault (Paso 3) antes de procesar el primer pago.

El transaction_id de este primer pago debe guardarse y utilizarse en todas las transacciones de pago posteriores para identificar al cliente y su método de pago.

Nota para Argentina: Para Argentina, utilice el objeto additional_data.recurring en lugar de credentials_on_file_type. Para la primera transacción, establezca sequence: "FIRST" e incluya billing_period con el mes y el año (formato: MM/YYYY o MMYYYY).

Paso 5: Procesar pagos posteriores

Para todas las transacciones de pago posteriores, debe utilizar el valor de credentials_on_file_type adecuado e incluir el transaction_id del primer pago en su petición:

CIT (One Click): Utilice credentials_on_file_type: "ONE_CLICK_PAYMENT"
MIT (Recurrente): Utilice credentials_on_file_type: "RECURRING_PAYMENT"

Utilice el endpoint de Create Payment:

Ejemplo para CIT (One Click):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187384",
  "data": {
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "ONE_CLICK_PAYMENT",
      "transaction_id": "MCC50205G1020",
      "card": {
        "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
        "brand": "MASTERCARD",
        "expiration_month": "12",
        "expiration_year": "30",
        "cardholder_name": "John Doe",
        "security_code": "123"
      }
    }
  }
}'

Ejemplo para MIT (Recurrente):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187384",
  "data": {
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "RECURRING_PAYMENT",
      "transaction_id": "MCC50205G1020",
      "card": {
        "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
        "brand": "MASTERCARD",
        "expiration_month": "12",
        "expiration_year": "30",
        "cardholder_name": "John Doe",
        "security_code": "123"
      }
    }
  }
}'

Opción simplificada — referencie la tarjeta almacenada con card_id:

Esta es la forma recomendada de reutilizar una tarjeta almacenada. Envíe únicamente el card_id de la tarjeta almacenada (devuelto en el Paso 3) en el bloque card, y Getnet completa el resto de los campos de forma transparente: no necesita enviar number_token, brand, cardholder_name, expiration_month, expiration_year ni security_code. Como Getnet resuelve el token actual por usted, también evita la llamada adicional a Get Card by ID necesaria para actualizar el number_token renovado. Mantenga el transaction_id del primer pago en la petición.

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187384",
  "data": {
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "ONE_CLICK_PAYMENT",
      "transaction_id": "MCC50205G1020",
      "card": {
        "card_id": "e8ad2ae4-9e3e-4532-998f-1a5a11e56e58"
      }
    }
  }
}'

Este ejemplo utiliza ONE_CLICK_PAYMENT (CIT). Para MIT, utilice credentials_on_file_type: "RECURRING_PAYMENT".

El transaction_id en la petición de pago debe coincidir con el transaction_id de la primera transacción de pago (Paso 4). Esto permite a Getnet identificar al cliente y su método de pago.

Nota para Argentina: Para Argentina, utilice el objeto additional_data.recurring en lugar de credentials_on_file_type. Para las transacciones posteriores, establezca sequence: "SUBSEQUENT" e incluya transaction_identifier con el identificador de transacción del primer pago, junto con billing_period para el período de facturación actual.

Flujo 2: Tokenizar durante el pago

Este enfoque implica enviar el número de la tarjeta en formato original (raw) en la petición de pago con save_card_data: true. Getnet tokenizará automáticamente la tarjeta y la guardará en el vault durante el procesamiento del pago. Este método simplifica la integración al combinar la tokenización, el almacenamiento en el vault y el pago en un solo paso.

Visión general del proceso

Para este flujo, el proceso funciona de la siguiente manera:

Registrar un cliente: Cree un registro de cliente en el sistema.
Procesar el primer pago: Envíe el número de la tarjeta en formato original (raw) en la petición de pago con save_card_data: true y el valor de credentials_on_file_type adecuado (ONE_CLICK para CIT o RECURRING para MIT). Getnet tokenizará automáticamente la tarjeta y la guardará en el vault durante el procesamiento del pago. Guarde el transaction_id de la respuesta.
Procesar pagos posteriores: Para todos los pagos futuros, utilice credentials_on_file_type: "ONE_CLICK_PAYMENT" (CIT) o "RECURRING_PAYMENT" (MIT) e incluya el transaction_id del primer pago junto con el número de la tarjeta tokenizada.

<Diagram: resources/diagrams/tokenized-payment-flow-2.mermaid>

Paso 1: Registrar un cliente

Para que los pagos tokenizados funcionen, es necesario registrar un cliente. El cliente es el consumidor del producto o servicio.

Utilice el endpoint de Create Customer para registrar los detalles del cliente:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/customers-gwproxy/v1/customers \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --data '{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "customer_id": "customer-123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "document_type": "CPF",
  "document_number": "12345678900",
  "phone_number": "+5511999999999"
}'

Ejemplo de respuesta:

{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "customer_id": "customer-123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "document_type": "CPF",
  "document_number": "12345678900",
  "phone_number": "+5511999999999",
  "created_at": "2025-11-06T10:30:00.000Z"
}

Paso 2: Procesar el primer pago con la tokenización de la tarjeta

Para la primera transacción de pago, envíe el número de la tarjeta en formato original (raw) en la petición de pago junto con save_card_data: true y el valor de credentials_on_file_type adecuado. Getnet tokenizará automáticamente la tarjeta y la guardará en el vault durante el procesamiento del pago.

Utilice el endpoint de Create Payment:

Ejemplo para CIT (One Click):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187383",
  "data": {
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "ONE_CLICK",
      "save_card_data": true,
      "card": {
        "number": "5155901222280001",
        "brand": "MASTERCARD",
        "expiration_month": "12",
        "expiration_year": "30",
        "cardholder_name": "John Doe",
        "security_code": "123"
      }
    }
  }
}'

Ejemplo para MIT (Recurrente):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187383",
  "data": {
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "RECURRING",
      "save_card_data": true,
      "card": {
        "number": "5155901222280001",
        "brand": "MASTERCARD",
        "expiration_month": "12",
        "expiration_year": "30",
        "cardholder_name": "John Doe",
        "security_code": "123"
      }
    }
  }
}'

La respuesta incluirá un transaction_id y un card_id para la tarjeta almacenada. Guarde ambos valores—necesitará el transaction_id para todas las transacciones de pago posteriores, y puede utilizar el card_id para referenciar la tarjeta almacenada en pagos futuros:

{
  "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75",
  "order_id": "ORDER-10187383",
  "status": "APPROVED",
  "transaction_id": "MCC50205G1020",
  "card_id": "e8ad2ae4-9e3e-4532-998f-1a5a11e56e58",
  ...
}

Al enviar el number de la tarjeta en formato original (raw) en la petición de pago con save_card_data: true, también debe proporcionar la brand, cardholder_name, security_code, expiration_month y expiration_year de la tarjeta. La tarjeta se tokenizará automáticamente y se guardará en el vault durante el procesamiento del pago.

El transaction_id de este primer pago debe guardarse y utilizarse en todas las transacciones de pago posteriores para identificar al cliente y su método de pago.

Nota para Argentina: Para Argentina, utilice el objeto additional_data.recurring en lugar de credentials_on_file_type. Para la primera transacción, establezca sequence: "FIRST" e incluya billing_period con el mes y el año (formato: MM/YYYY o MMYYYY).

Paso 3: Procesar pagos posteriores

Para todas las transacciones de pago posteriores, debe utilizar el valor de credentials_on_file_type adecuado e incluir el transaction_id del primer pago en su petición. Utilice el token del número de la tarjeta tokenizada obtenido de la respuesta del primer pago:

CIT (One Click): Utilice credentials_on_file_type: "ONE_CLICK_PAYMENT"
MIT (Recurrente): Utilice credentials_on_file_type: "RECURRING_PAYMENT"

Utilice el endpoint de Create Payment:

Ejemplo para CIT (One Click):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187384",
  "data": {
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "ONE_CLICK_PAYMENT",
      "transaction_id": "MCC50205G1020",
      "card": {
        "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
        "brand": "MASTERCARD",
        "expiration_month": "12",
        "expiration_year": "30",
        "cardholder_name": "John Doe",
        "security_code": "123"
      }
    }
  }
}'

Ejemplo para MIT (Recurrente):

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187384",
  "data": {
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "RECURRING_PAYMENT",
      "transaction_id": "MCC50205G1020",
      "card": {
        "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c",
        "brand": "MASTERCARD",
        "expiration_month": "12",
        "expiration_year": "30",
        "cardholder_name": "John Doe",
        "security_code": "123"
      }
    }
  }
}'

Opción simplificada — referencie la tarjeta almacenada con card_id:

Esta es la forma recomendada de reutilizar una tarjeta almacenada. Envíe únicamente el card_id devuelto por el primer pago (Paso 2) en el bloque card, y Getnet completa el resto de los campos de forma transparente: no necesita enviar number_token, brand, cardholder_name, expiration_month, expiration_year ni security_code. Como Getnet resuelve el token actual por usted, también evita la llamada adicional a Get Card by ID necesaria para actualizar el number_token renovado. Mantenga el transaction_id del primer pago en la petición.

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187384",
  "data": {
    "amount": 9900,
    "currency": "BRL",
    "customer_id": "customer-123",
    "payment": {
      "payment_method": "CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "credentials_on_file_type": "ONE_CLICK_PAYMENT",
      "transaction_id": "MCC50205G1020",
      "card": {
        "card_id": "e8ad2ae4-9e3e-4532-998f-1a5a11e56e58"
      }
    }
  }
}'

Este ejemplo utiliza ONE_CLICK_PAYMENT (CIT). Para MIT, utilice credentials_on_file_type: "RECURRING_PAYMENT".

El transaction_id en la petición de pago debe coincidir con el transaction_id de la primera transacción de pago (Paso 2). Esto permite a Getnet identificar al cliente y su método de pago.

Nota para Argentina: Para Argentina, utilice el objeto additional_data.recurring en lugar de credentials_on_file_type. Para las transacciones posteriores, establezca sequence: "SUBSEQUENT" e incluya transaction_identifier con el identificador de transacción del primer pago, junto con billing_period para el período de facturación actual.

Consideraciones importantes

Al gestionar calendarios de pagos tokenizados, tenga en cuenta estos puntos importantes:

Para los pagos tokenizados, la tarjeta debe estar tokenizada y guardada en el vault antes o durante el primer pago.
La tokenización es obligatoria para los pagos tokenizados. Puede tokenizar la tarjeta antes de procesar el pago (Flujo 1) o enviar los datos de la tarjeta en formato original (raw) en la petición de pago con save_card_data: true (Flujo 2), donde se tokenizará y guardará automáticamente.
Utilice siempre el transaction_id del primer pago (ONE_CLICK o RECURRING) en todas las peticiones de pago posteriores (ONE_CLICK_PAYMENT o RECURRING_PAYMENT).
Para reutilizar una tarjeta almacenada en pagos posteriores, envíe únicamente su card_id en el bloque card. Getnet completa el resto de los campos de la tarjeta desde el vault automáticamente, por lo que no necesita reenviar el number_token ni los demás detalles de la tarjeta.
Usted es responsable de desencadenar cada transacción de pago de acuerdo con el calendario de su negocio.
Al utilizar el Flujo 2 (Tokenizar durante el pago), asegúrese de incluir save_card_data: true en su petición de pago para guardar automáticamente la tarjeta en el vault.

Próximos pasos

Ahora que ha creado con éxito un pago tokenizado, puede explorar más funciones de la Global API de Getnet:

Aprenda sobre el Getnet Recurring Payments Engine
Lea más sobre Pagos Recurrentes
Explore la documentación de Tokenización y Vault