Crear Sesión

Sesión es el término que usamos para referirnos al proceso de pago con el que interactuan tus usuarios en Checkout.

Para crear una sesión debes consumir nuestra API según tus necesidades, conoce los detalles del API en API - Crear Sesion.

Autenticación: Para crear una sesión debes autenticarte con nuestra API, conoce los detalles en Autenticación

Localización: Puedes elegir el idioma de la sesión haciendo uso de los parámetros del api, conoce los detalles en Localización

Pago Básico

Una sesión de pago básico es una sesión en la cual esperas recibir un pago único de un usuario.

{
    ...
    "payment": {
        "reference": "PAY_ABC_1287",
        "description": "Pago por Placetopay",
        "amount": {
            "currency": "USD",
            "total": 1000
        },
    }
    ...
}

Pagos Parciales

Una sesión de pago parcial es una sesión en la cual un usuario puede hacer varias transacciones de distintos montos o con diferentes medios de pago hasta completar el total solicitado en la misma sesión.

Para usar esta funcionalidad se debe enviar la propiedad payment.allowPartial como true.

{
    ...
    "payment": {
        "reference": "PAY_ABC_1287",
        "description": "Pago por Placetopay",
        "amount": {
            "currency": "USD",
            "total": 1000
        },
        "allowPartial": true
    }
    ...
}

Cuando se hace una sesión de pagos parciales, aparecen nuevo escenarios que se deben controlar:

• La sesión finaliza con el estado APPROVED_PARTIAL, ocurre cuando en la sesión se hizo al menos una transacción APPROVED, pero no se completó el total del monto solicitado.
• La sesión finaliza con el estado PARTIAL_EXPIRED, ocurre cuando en la sesión se hizo al menos una transacción APPROVED, pero no se completó el toal del monto solicitado y la sesión expiró.

Las sesiones parciales también tienen condiciones adicionales como:

• No se aceptan impuestos, pues no se pueden dividir los impuestos en diferentes transacciones.

Pago Recurrente

Una sesión de pago recurrente es una sesión en la cual el usuario completa el proceso con una tarjeta de crédito, y a partir de ese momento periodicamente se le realizan cobros automáticos al medio de pago. Por ejemplo, en el pago de una mensualidad o suscripción a un servicio.

Para usar esta funcionalidad se debe enviar la propiedad payment.recurring con la estructura Recurrence.

{
    ...
    "payment": {
        "reference": "PAY_ABC_1287",
        "description": "Pago por Placetopay",
        "amount": {
            "currency": "USD",
            "total": 1000
        },
        "recurring": {
            "periodicity": "D",
            "interval": "1",
            "nextPayment": "2024-08-24",
            "maxPeriods": 1,
            "dueDate ": "2024-09-24",
            "notificationUrl ": "https://merchanturl.com/notify"
        },
    }
    ...
}

• El atributo nextPayment no es obligatorio, en caso de que no se envié, se calcula dependiendo del atributo interval y periodicity, en caso de que se declare debe ser una fecha futura a la fecha actual.
• En el caso de fallar un cobro recurrente, éste seguirá reintentado una vez cada día durante 3 días, si luego de esto no se obtiene una transacción aprobada, la recurrencia se le cancela al tarjetahabiente.
• La recurrencia se deja de reintentar si la primera respuesta no tiene sentido reintentar (Tarjeta invalida, robada, etc), es decir se reintenta sólo si es por saldo.
• Las recurrencias sólo pueden ser canceladas en la consola administrativa de PlacetoPay.

Pago con Dispersión

Una sesión de dispersión es una sesión en la cual el monto total del pago será dividido en diferentes destinos.

Para usar este tipo de sesión, debes enviar la propiedad payment.dispersión que contiene un arreglo de DispersionRequests

{
    ...
    "payment": {
        "reference": "PAY_ABC_1287",
        "description": "Pago por Placetopay",
        "amount": {
            "currency": "USD",
            "total": 1000
        },
        "dispersion": [
            {
                "amount": {
                    "total": 700,
                    "currency": "USD"
                },
                "agreement": 30,
                "agreementType": "AIRLINE"
            },
            {
                "amount": {
                    "total": 300,
                    "currency": "USD"
                },
                "agreementType": "MERCHANT"
            }
        ],
    }
    ...
}

El pago puede ser dividido en diferentes convenios registrados, además permite que cada parte de la transacción sea procesada por diferentes proveedores.

Para hacer uso de esta funcionalidad es importante conocer el identificador del convenio (agreement) a donde va dirigido el pago. Si no se agrega ningún valor de aggreement, se tomará por defecto el medio de pago configurado en el sitio de la sesión, también es necesario indicar el tipo de convenio (aggrementType), en este caso MERCHANT o AIRLINE.

• No se permiten pagos parciales cuando se crea una sesión de dispersión.
• No se permiten pagos de preautorización cuando se crea una sesión de dispersión.
• La suma total de las dispersiones deben ser igual al total del pago.
• Todas las monedas de las dispersiones deben ser igual a la moneda del pago

Para el envió de impuestos, es importante que se agreguen en la estructura amount de cada una de las dispersiones

{
    ...
    "payment": {
        ...
        "dispersion": [
            {
                "amount": {
                    "total": 700,
                    "currency": "USD",
                    "taxes": [
                        {
                            "kind": "airportTax",
                            "amount": 16.13
                        }
                    ],
                    "details": [
                        {
                            "kind": "tip",
                            "amount": 11
                        }
                    ]
                },
                "agreement": 30,
                "agreementType": "AIRLINE",
            },
        ],
    }
    ...
}

Pago con Preautorización

La preautorización te permite reservar un monto en la tarjeta del cliente a través de una sesión de Web Checkout. Esto es útil cuando el monto final a cobrar no se conoce con certeza desde el inicio, como sucede en sectores como hospitalidad, movilidad o alquiler de equipos.

El flujo de preautorización incluye tres pasos clave:

• Check-in: Reserva un monto específico en la tarjeta del cliente sin capturarlo de inmediato.
• Reautorización: Ajusta el monto reservado si el valor estimado cambia.
• Checkout: Captura el monto final o libera la reserva.

Para una explicación conceptual, consulta Pagos/Preautorización.

Paso 1: Crear una sesión para el flujo de preautorización (Check-in)

Inicia la preautorización creando una sesión con type establecido como checkin. Esto reserva los fondos en la tarjeta del cliente sin cobrarlos.

Envía una RedirectRequest al API Web Checkout -> Crear sesión:

• type debe ser checkin
• No se permiten pagos mixtos ni dispersos
• La moneda se mantiene fija durante todo el flujo

{
  ...,
  "type": "checkin",
  "payment": {
    "reference": "PAY_ABC_1287",
    "description": "Payment Preauthorization",
    "amount": {
      "currency": "USD",
      "total": 1000
    }
  }
  ...
}

Redirige al usuario al processUrl para completar este paso. Una vez finalizado, usa API Web Checkout -> Consultar sessión (getRequestInformation) para confirmar el estado:

{
  "auth": ...
}

RedirectInformation.payment es un arreglo de intentos de pago. Si RedirectInformation.status es APPROVED, identifica el intento exitoso.

Guarda RedirectInformation.payment[n].internalReference para usar en las operaciones de Reautorización y Checkout.

Paso 2: Ajustar el monto reservado (Reautorización)

Este paso opcional permite actualizar el monto retenido antes de capturarlo.

Esto se hace enviando el TransactionActionRequest a API Web Checkout -> Acciones sobre transacciones:

• action debe ser reauthorization
• Puedes realizar múltiples reautorizaciones
• Debes incluir internalReference del último paso.
• La moneda deben coincidir con el Check-in

{
  "auth": ...,
  "action": "reauthorization",
  "internalReference": 35,
  "amount": {
    "currency": "USD",
    "total": 1500
  },
  ...
}

Paso 3: Finalizar la transacción (Checkout)

Este paso captura o libera el monto retenido.

Esto se hace enviando el TransactionActionRequest a API Web Checkout -> Acciones sobre transacciones:

• action debe ser checkout
• Si payment.amount.total es 0, el monto retenido se libera.
• Debes incluir internalReference del último paso.
• La moneda deben coincidir con el Check-in

{
  "auth": ...,
  "action": "checkout",
  "internalReference": 35,
  "amount": {
    "currency": "USD",
    "total": 2000
  },
  ...
}

Este flujo aplica exclusivamente para Web Checkout, donde el paso inicial se realiza mediante una sesión en el navegador y las acciones posteriores se ejecutan vía API.

Asegúrate de almacenar de forma segura el valor de internalReference para completar correctamente el flujo.

Suscripción

Una sesión de suscripción es una sesión en la cual el usuario ingresa un medio de pago para tokenizarlo y que luego podrá ser usado para cobrar sobre ese medio de pago.

La suscripción permite almacenar de forma segura (tokenizando) el medio de pago de un usuario, para que luego pueda efectuar cobros relacionados a éste.

Para hacer uso de esta funcionalidad es necesario enviar en el CreateSessionRequest la estructura subscription.

{
    ...
    "subscription": {
        "reference": "3110",
        "description": "Una suscripción de prueba"
    },
    ...
}

Cobrar sobre un medio de pago tokenizado

Cuando se realiza una suscripción se obtiene un token, con este token puedes hacer cobros al cliente.

La estructura de la respuesta contiene toda la información de la petición original y una estructura de suscripción (subscription) con un instrumento (instrument) representado en forma de token.

{
    ...
    "payment": {
        "reference": "1122334455",
        "description": "Prueba",
        "amount": {
            "currency": "USD",
            "total": 100
        }
    },
    "instrument": {
        "token": {
            "token": "e07ca9986cf0ecac8a557fa11c07bf37ea35e9e3e3a4180c49"
        }
    },
    ...
}

La información del token debe ser almacenada en su sitio y relacionada al usuario y/o producto. Luego de tener el token, puede generar cobros al medio de pago tokenizado usando el servicio collect.

Pago con suscripción

Puedes permitir que tus usuarios guarden su medio de pago durante un pago normal, activando el flujo de suscripción. Este flujo permite almacenar de forma segura el medio de pago para futuras compras, siempre con el consentimiento explícito del usuario.

Este flujo es útil para:

• Preparar cobros futuros (por ejemplo, para suscripciones o pagos recurrentes).
• Reducir fricción en el checkout repitiendo automáticamente los datos de pago guardados.
• Realizar cobros cuando el usuario no está presente, como en casos de renovaciones automáticas.

1. Crear sesión de pago con opción de suscripción

Para activar la opción de guardar el medio de pago durante el proceso de checkout, debes enviar la propiedad
subscribe: true dentro de la estructura payment en la petición CreateSessionRequest.

{
  ...
  "payment": {
    "reference": "PAY_ABC_1287",
    "description": "Pago por Placetopay",
    "amount": {
      "currency": "USD",
      "total": 1000
    },
    "subscribe": true
  }
  ...
}

Esto habilita la opción para que el usuario autorice el almacenamiento del medio de pago (tokenización) al momento de completar el pago.

2. Guardado del medio de pago por parte del usuario

Durante el flujo de checkout, se mostrará al usuario una opción para autorizar el almacenamiento de su medio de pago.
Esta autorización es necesaria para que el medio sea tokenizado y quede disponible para futuros pagos.

3. Obtener el token del medio de pago guardado

Si el usuario autorizó el guardado del medio de pago durante el proceso de checkout, al finalizar la sesión podrás consultar el token generado (identificador del medio de pago tokenizado).

Para obtenerlo, realiza una solicitud al endpoint Consultar una sesión usando el requestId correspondiente. El token estará disponible en el campo subscription.instrument de la respuesta, si el proceso fue exitoso.

{
  "requestId": 1,
  "status": {...},
  "request": {
    ...
    "payment": {
      "reference": "12345",
      "description": "Prueba de pago",
      "amount": {
        "currency": "COP",
        "total": 2000,
      },
      "subscribe": true,
    },
  },
  "payment": [
    {
      "status": {
        "status": "APPROVED",
        "reason": "00",
        "message": "La petición ha sido aprobada exitosamente",
        "date": "2022-07-27T14:51:27-05:00"
      },
      ...
    }
  ],
  "subscription": {
    "status": {
      "status": "OK",
      "reason": "00",
      "message": "La petición ha sido aprobada exitosamente",
      "date": "2022-07-27T14:51:27-05:00"
    },
    "type": "token",
    "instrument": [
        {
            "keyword": "token",
            "value": "a3bfc8e2afb9ac5583922eccd6d2061c1b0592b099f04e352a894f37ae51cf1a",
            "displayOn": "none"
        },
        {
            "keyword": "subtoken",
            "value": "8740257204881111",
            "displayOn": "none"
        },
        ...
    ]
  }
}

4. Usar el token para realizar cobros futuros

Una vez se obtiene el token del medio de pago, puedes reutilizarlo para realizar cobros futuros sin requerir una nueva interacción del usuario.

Para más detalles sobre este proceso, consulta la sección:
➡️ Cobrar sobre un medio de pago tokenizado