Sesión

Se identifica como sesión, a la experiencia visual con el que interactuan los usuarios para completar un pago.

POST/api/session

Crear una sesión

Este endpoint te permite crear una nueva sesión. En la sesión el usuario podrá completar un pago o suscripción.

Solicitud

Estructura que contiene toda la información acerca de la transacción para ser procesada.

Name
auth
Type
Authentication
is Required
REQUIRED
Description
La autenticación del sitio. Ver más en Autenticación
Name
payment
Type
PaymentRequest
is Required
REQUIRED
Description
Información del pago solicitado.
Name
expiration
Type
string
is optional
Description
Fecha de expiración de una sesión. El usuario debe terminar el proceso antes de esta fecha. El tiempo de expiración debe ser de al menos 5 minutos desde el momento de la creación. Ver más en Fecha de expiración
Ejemplo:2024-09-03T12:23:39-05:00
Formato:date-time
Name
ipAddress
Type
string
is Required
REQUIRED
Description
Dirección IP del usuario que realizará el proceso.
Ej: 134.10.163.36
Ejemplo:134.10.163.36
Name
userAgent
Type
string
is Required
REQUIRED
Description
User Agent del navegador del usuario que realizará el proceso.
Ejemplo:Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
Name
returnUrl
Type
string
is Required
REQUIRED
Description
URL de retorno, a esta url se redirige al usuario una vez termina la sesión. Ocurre cuando el usuario da click en Volver al comercio.
Ejemplo:https://commerce.test/return
Name
locale
Type
string
is optional
Description
Idioma en el que se tratará la petición y la sesión. Ver más en Localización
Ejemplo:en_US
Formato:regex
Patrón:^\w{2}\_[A-Z]{2}
Name
buyer
Type
Person
is optional
Description
Datos del usuario comprador, hace referencia al usuario que está comprando un producto o un servicio.

Cuando se crea una sesión: Se puede enviar si conoces al usuario que está haciendo la compra, pues ayuda a completar la información de la sesión.
Si se envía este dato, el usuario tendrá sus datos personales pre-diligenciados y podrá cambiarlos en Checkout.
Name
payer
Type
Person
is optional
Description
Datos del usuario pagador, hace referencia al dueño del medio de pago o usuario que pagó el monto solicitado.

Cuando se crea una sesión: Sólo se debe usar cuando quieres "forzar" los datos del usuario que completará el proceso.
Si se envía este dato, el usuario tendrá sus datos personales pre-diligenciados pero no podrá cambiarlos.
Name
subscription
Type
SubscriptionRequest
is optional
Description
Cuando se envía, se genera una sesión de suscripción.

El usuario registra un medio de pago para que luego se realicen cobros sobre ese medio de pago.
Name
fields
Type
array[NameValuePair]
is optional
Description
Estructura para relacionar información adicional en el proceso. Ver más en Campos Adicionales
Name
paymentMethod
Type
string
is optional
Description
Se usa para restringir los métodos de pago disponibles en checkout. Se pueden enviar varios códigos separados por coma. Ver más en Métodos de pago

EJ: visa,master,pse
Ejemplo:visa
Name
cancelUrl
Type
string
is optional
Description
URL de cancelación, a esta url se redirige al usuario cuando decide no continuar con el proceso. Ocurre cuando el usario da click en No deseo continuar
Ejemplo:https://commerce.test/cancel
Name
skipResult
Type
boolean
is optional
Description
Si se envía true, cuando el usuario finalice el proceso no se mostrará la página de resultado de sesión, en su lugar será redireccionado al returnUrl. Ver más en Omitir resultado
Valor por defecto:false
Name
noBuyerFill
Type
boolean
is optional
Description
Por defecto los datos enviados como buyer se pre-diligencian en la interfaz de Checkout para agilizar el proceso de pago, si se envía este parámetro como true entonces no se hará este pre diligenciamiento.
Valor por defecto:false
Name
type
Type
string
is optional
Description
Parámetro usado para sesiones de tipo preauthorización

Sólo se soporta checkin para generar una sesión de preautorización
Valores permitidos:checkin
Ejemplo:checkin
Name
metadata
Type
metadata
is optional
Description
Estructura de tipo clave-valor que se utiliza para enviar información adicional y determinar comportamientos específicos durante el procesamiento de una sesión.

Solicitud

POST

/api/session

curl -X "POST" https://checkout-test.placetopay.com/api/session \
  -H "Content-Type: application/json" \
  -d '{
      "locale": "es_CO",
      "auth": {
        "login":"aabbccdd1234567890aabbccdd123456",
        "tranKey":"ABC123example456trankey+789abc012def3456ABC=",
        "nonce":"NjE0OWVkODgwYjNhNw==",
        "seed":"2021-09-21T09:34:48-05:00"
      },
      "payment": {
          "reference": "1122334455",
          "description": "Prueba",
          "amount": {
            "currency": "USD",
            "total": 100
          }
      },
      "expiration": "2021-12-30T00:00:00-05:00",
      "returnUrl": "https://dnetix.co/p2p/client",
      "ipAddress": "127.0.0.1",
      "userAgent": "PlacetoPay Sandbox"
  }'

Respuesta

Name
status
Type
Status
is optional
Description
Estructura que contiene la información de la respuesta sobre una solicitud o pago, e informa el estado actual de la misma.
Name
requestId
Type
integer
is optional
Description
Name
processUrl
Type
string
is optional
Description

Respuesta

{
  "status": {
    "status": "OK",
    "reason": "PC",
    "message": "La petición se ha procesado correctamente",
    "date": "2021-11-30T15:08:27-05:00"
  },
  "requestId": 1,
  "processUrl": "https://checkout-co.placetopay.com/session/1/cc9b8690b1f7228c78b759ce27d7e80a",
}

POST/api/session/:requestId

Consultar una sesión

Este endpoint te permite obtener la información de la sesión, si en la sesión hay transacciones se muestra el detalle de las mismas.

Parámetros

Name
requestId
Type
requestId
is Required
REQUIRED
Description

Solicitud

Name
auth
Type
Authentication
is Required
REQUIRED
Description
La autenticación del sitio. Ver más en Autenticación

Solicitud

POST

/api/session/:requestId

curl -X "POST" https://checkout-test.placetopay.com/api/session/000000 \
  -H "Content-Type: application/json" \
  -d '{
      "auth": {
        "login": "aabbccdd1234567890aabbccdd123456",
        "tranKey": "ABC123example456trankey+789abc012def3456ABC=",
        "nonce": "NjE0OWVkODgwYjNhNw==",
        "seed": "2021-09-21T09:34:48-05:00"
      }
    }'

Respuesta

Name
requestId
Type
string|number|integer
is optional
Description
Id de la petición
Ejemplo:1
Name
status
Type
Status
is optional
Description
Estructura que contiene la información de la respuesta sobre una solicitud o pago, e informa el estado actual de la misma.
Name
request
Type
RedirectRequest
is optional
Description
Estructura que contiene toda la información acerca de la transacción para ser procesada.
Name
payment
Type
Transaction
is optional
Description
Name
subscription
Type
SubscriptionResponse
is optional
Description
Estructura que contiene información para el método de pago suscripción.

Respuesta

{
  "requestId": 1,
  "status": {
    "status": "APPROVED",
    "reason": "00",
    "message": "La petición ha sido aprobada exitosamente",
    "date": "2022-07-27T14:51:27-05:00"
  },
  "request": {
    "locale": "es_CO",
    "payer": {
      "document": "1122334455",
      "documentType": "CC",
      "name": "John",
      "surname": "Doe",
      "company": "Evertec",
      "email": "[email protected]",
      "mobile": "+5731111111111",
      "address": {
        "street": "Calle falsa 123",
        "city": "Medellín",
        "state": "Poblado",
        "postalCode": "55555",
        "country": "CO",
        "phone": "+573111111111"
      }
    },
    "buyer": {
      "document": "1122334455",
      "documentType": "CC",
      "name": "John",
      "surname": "Doe",
      "company": "Evertec",
      "email": "[email protected]",
      "mobile": "+5731111111111",
      "address": {
        "street": "Calle falsa 123",
        "city": "Medellín",
        "state": "Poblado",
        "postalCode": "55555",
        "country": "CO",
        "phone": "+573111111111"
      }
    },
    "payment": {
      "reference": "12345",
      "description": "Prueba de pago",
      "amount": {
        "currency": "COP",
        "total": 2000,
        "taxes": [
          {
            "kind": "valueAddedTax",
            "amount": 1000,
            "base": 0
          }
        ],
        "details": [
          {
            "kind": "discount",
            "amount": 1000
          }
        ]
      },
      "allowPartial": false,
      "shipping": {
        "document": "1122334455",
        "documentType": "CC",
        "name": "John",
        "surname": "Doe",
        "company": "Evertec",
        "email": "[email protected]",
        "mobile": "+5731111111111",
        "address": {
          "street": "Calle falsa 123",
          "city": "Medellín",
          "state": "Poblado",
          "postalCode": "55555",
          "country": "CO",
          "phone": "+573111111111"
        }
      },
      "items": [
        {
          "sku": "12345",
          "name": "product_1",
          "category": "physical",
          "qty": "1",
          "price": 1000,
          "tax": 0
        }
      ],
      "fields": [
        {
          "keyword": "_test_field_value_",
          "value": "_test_field_",
          "displayOn": "approved"
        }
      ],
      "recurring": {
        "periodicity": "D",
        "interval": "1",
        "nextPayment": "2019-08-24",
        "maxPeriods": 1,
        "dueDate ": "2019-09-24",
        "notificationUrl ": "https://checkout.placetopay.com"
      },
      "subscribe": false,
      "dispersion": [
        {
          "agreement": "1299",
          "agreementType": "MERCHANT",
          "amount": {
            "currency": "USD",
            "total": 200
          }
        }
      ],
      "modifiers": [
        {
          "type": "FEDERAL_GOVERNMENT",
          "code": 17934,
          "additional": {
            "invoice": "123345"
          }
        }
      ]
    },
    "subscription": {
      "reference": "12345",
      "description": "Ejemplo de descripción",
      "fields": {
        "keyword": "1111",
        "value": "lastDigits",
        "displayOn": "none"
      }
    },
    "fields": [
      {
        "keyword": "_processUrl_",
        "value": "https://checkout.redirection.test/session/1/a592098e22acc709ec7eb30fc0973060",
        "displayOn": "none"
      }
    ],
    "paymentMethod": "visa",
    "expiration": "2019-08-24T14:15:22Z",
    "returnUrl": "https://commerce.test/return",
    "cancelUrl": "https://commerce.test/cancel",
    "ipAddress": "127.0.0.1",
    "userAgent": "PlacetoPay Sandbox",
    "skipResult": false,
    "noBuyerFill": false,
    "type": "checkin"
  },
  "payment": [
    {
      "status": {
        "status": "APPROVED",
        "reason": "00",
        "message": "La petición ha sido aprobada exitosamente",
        "date": "2022-07-27T14:51:27-05:00"
      },
      "internalReference": 12345,
      "reference": "12345",
      "paymentMethod": "visa",
      "paymentMethodName": "Visa",
      "issuerName": "JPMORGAN CHASE BANK, N.A.",
      "amount": {
        "from": {
          "currency ": "COP",
          "total ": 10000
        },
        "to": {
          "currency ": "COP",
          "total ": 10000
        },
        "factor": 1
      },
      "receipt": "052617800175",
      "franchise": "PS_VS",
      "refunded": false,
      "authorization": "965960",
      "processorFields": [
        {
          "keyword": "1111",
          "value": "lastDigits",
          "displayOn": "none"
        }
      ],
      "dispersion": null,
      "agreement": null,
      "agreementType": null,
      "discount": {
        "base": 3000,
        "code": "17934",
        "type": "FRANCHISE",
        "amount": 1000
      },
      "subscription": null
    }
  ],
  "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"
      },
      {
        "keyword": "franchise",
        "value": "visa",
        "displayOn": "none"
      },
      {
        "keyword": "franchiseName",
        "value": "Visa",
        "displayOn": "none"
      },
      {
        "keyword": "issuerName",
        "value": "JPMORGAN CHASE BANK, N.A.",
        "displayOn": "none"
      },
      {
        "keyword": "lastDigits",
        "value": "1111",
        "displayOn": "none"
      },
      {
        "keyword": "validUntil",
        "value": "2029-12-31",
        "displayOn": "none"
      },
      {
        "keyword": "installments",
        "value": null,
        "displayOn": "none"
      }
    ]
  }
}

POST/api/session/:requestId/cancel

Cancelar una sesión

Este endpoint te permite cancelar una sesión sin algún pago aprobado, o con una transacción de efectivo aún no pagada.

Parámetros

Name
requestId
Type
requestId
is Required
REQUIRED
Description
Identificador de la sesión a cancelar

Solicitud

Estructura de solicitud para cancelar una sesión.

Name
auth
Type
Authentication
is Required
REQUIRED
Description
La autenticación del sitio. Ver más en Autenticación

Solicitud

POST

/api/session/:requestId/cancel

curl -X "POST" https://checkout-test.placetopay.com/api/session/000000/cancel \
  -H "Content-Type: application/json" \
  -d '{
      "auth": {
        "login": "aabbccdd1234567890aabbccdd123456",
        "tranKey": "ABC123example456trankey+789abc012def3456ABC=",
        "nonce": "NjE0OWVkODgwYjNhNw==",
        "seed": "2021-09-21T09:34:48-05:00"
      }
    }'

Respuesta

Name
status
Type
Status
is optional
Description
Estructura que contiene la información de la respuesta sobre una solicitud o pago, e informa el estado actual de la misma.
Name
session
Type
RedirectInformation
is optional
Description
Estructura de respuesta a una solicitud para una información de transacción.

Respuesta

{
  "status": {
    "status": "OK",
    "reason": "00",
    "message": "La petición se ha procesado correctamente",
    "date": "2025-07-11T14:05:44-05:00"
  },
  "session": {
    "requestId": 28,
    "status": {
      "status": "REJECTED",
      "reason": "MC",
      "message": "La petición ha sido cancelada por el comercio",
      "date": "2025-07-11T14:05:44-05:00"
    },
    "request": {
      "locale": "es_CO",
      "payer": {
        "document": "118877455",
        "documentType": "CC",
        "name": "John",
        "surname": "Doe",
        "email": "[email protected]",
        "mobile": "+573123123123"
      },
    "payment": {
      "reference": "Ord: 1001/2023",
      "description": "_pueba pagoEfectivo",
      "amount": {
        "currency": "USD",
        "total": 20000
      },
      "allowPartial": false,
      "subscribe": false,
      "fields": [
        {
        "keyword": "_test_field_",
        "value": "_test_field_value_",
        "displayOn": "payment"
        }
      ]
    },
    "returnUrl": "https://mysite.com/response/32120",
    "ipAddress": "127.0.0.1",
    "userAgent": "PlacetoPay Sandbox",
    "expiration": "2025-07-11T19:25:39.497Z"
    },
  "payment": null,
  "subscription": null
  }
}