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

Name
auth
Type
Authentication
is Required
REQUIRED
Description
La autenticación del sitio. Ver más en Autenticación
Name
login
Type
string
is optional
Description
Identificador del sitio.
Name
tranKey
Type
string
is optional
Description
Credencial tranKey generado.
Ver más en Autenticación
Name
nonce
Type
string
is optional
Description
Valor aleatorio para cada solicitud codificado en Base64.
Name
seed
Type
string
is optional
Description
Fecha actual, la cual se genera en formato ISO 8601.
Name
payment
Type
PaymentRequest
is Required
REQUIRED
Description
Información del pago solicitado.
Name
reference
Type
string
is Required
REQUIRED
Description
Referencia única del pago. Máximo de 32 caracteres
Ej: PAYMENT_0001_ABC
Name
description
Type
string
is Required
REQUIRED
Description
Descripción del proceso a realizar
EJ: Consumo mes de Mayo
Name
amount
Type
Amount
is Required
REQUIRED
Description
Información del monto a cobrar
Name
currency
Type
string
is optional
Description
Código alfabético de la moneda a usar (ISO 4217 alpha code)
EJ: USD
Name
total
Type
number
is optional
Description
Valor total en la moneda base indicada
EJ: 1000 equivalen a Mil dolares
Name
taxes
Type
array[Taxes]
is optional
Description
Estructura para definir impuestos en el proceso de pago.
Name
kind
Type
string
is optional
Description
Identificador del tipo de impuesto

Uno de: valueAddedTax exciseDuty ice airportTax stateTax reducedStateTax municipalTax.
Name
amount
Type
number
is optional
Description
Monto total del impuesto
EJ: 200
Name
base
Type
number
is optional
Description
Monto base sobre el cual se calcula el impuesto
EJ: 1000
Name
details
Type
array[Details]
is optional
Description
Estructura para definir detalles adicionales del monto en el proceso de pago.
Name
kind
Type
string
is optional
Description
Identificador del tipo de detalle. Uno de: discount additional vatDevolutionBase shipping handlingFee insurance giftWrap subtotal fee tip airline interests
Name
amount
Type
number
is optional
Description
Monto total del detalle

EJ: 200
Name
allowPartial
Type
boolean
is optional
Description
Define si el monto a ser cobrado puede ser pagado en varias transacciones. Cuando es true el usuario podrá completar el pago en varias transacciones.
Name
shipping
Type
Person
is optional
Description
Estructura para relacionar información de envío.
Name
document
Type
string
is optional
Description
Documento de identidad

Ej: 1017111222
Name
documentType
Type
string
is optional
Description
Identificador del tipo de documento. Ver opciones en Tipos de documento

EJ: CC para "Cédula de Ciudadanía" en Colombia.
Name
name
Type
string
is optional
Description
Nombre de la persona o empresa

EJ: Juan José
Name
surname
Type
string
is optional
Description
Apellido de la persona. No aplica cuando el tipo de documento corresponde al de una empresa

EJ: Peréz Pinzon
Name
company
Type
string
is optional
Description
Nombre de la compañia a la que pertenece la persona

EJ: Placetopay
Name
email
Type
string
is optional
Description
Correo eléctronico del usuario o empresa

EJ: [email protected]
Name
mobile
Type
string
is optional
Description
Número de teléfono del usuario o empresa

EJ: +573214445566
Name
address
Type
object
is optional
Description
Estructura para anexar información del domicilio o dirección
Name
country
Type
string
is optional
Description
País del domicilio

EJ: Colombia
Name
state
Type
string
is optional
Description
Departamento del domicilio

EJ: Antioquia
Name
city
Type
string
is optional
Description
Ciudad del domicilio

EJ: Medellín
Name
postalCode
Type
string
is optional
Description
Código postal del domicilio

EJ: 050012
Name
street
Type
string
is optional
Description
Dirección del domicilio

EJ: Calle 12 #33a-12, Apto 101
Name
phone
Type
string
is optional
Description
Número telefónico del domicilio

EJ: +573214445566
Name
items
Type
array[Item]
is optional
Description
Estructura para relacionar productos o artículos en el proceso.
Name
sku
Type
string
is optional
Description
Identificador SKU del artículo.
EJ: SKU-12345
Name
name
Type
string
is optional
Description
Nombre del artículo.
EJ: Manta de lana
Name
category
Type
string
is optional
Description
Categoría del artículo. Uno de: digital physical
Name
qty
Type
number
is optional
Description
Cantidad de artículos de este tipo.
EJ: 23
Name
price
Type
number
is optional
Description
Costo total del artículo.
EJ: 1400
Name
tax
Type
number
is optional
Description
Monto en impuestos del artículo.
EJ: 100
Name
fields
Type
array[NameValuePair]
is optional
Description
Estructura para relacionar información adicional en el proceso. Ver más en Campos Adicionales
Name
keyword
Type
string
is optional
Description
Identificador o índice del dato a anexar.
EJ: cmsInvoiceId
Name
value
Type
string|object|array|number|boolean
is optional
Description
Valor del dato a anexar.
EJ: ID_2233
Name
displayOn
Type
string
is optional
Description
Indica en qué condiciones se muestra el dato anexo. Ver más en Campos Adicionales

Uno de: none, payment, receipt, both, approved.
Name
recurring
Type
object
is optional
Description
Estructura para indicar la frecuencia de un cobro recurrente.
Name
periodicity
Type
string
is optional
Description
Periodicidad del cobro
D Día, M Mes, Y Año
Name
interval
Type
number
is optional
Description
Intervalo asociado a la periodicidad
EJ: 15 para días.
Name
nextPayment
Type
string
is optional
Description
Fecha del próximo pago
EJ: 2019-08-24
Name
maxPeriods
Type
number
is optional
Description
Número máximo de periodos. Usar -1 en caso de que no haya límite
EJ: 12 para máximo 12 cobros
Name
dueDate
Type
string
is optional
Description
Fecha de vencimiento de la recurrencia
EJ: 2019-09-24
Name
notificationUrl
Type
string
is optional
Description
URL en el que el servicio notificará cada vez que se haga un cobro
EJ: https://merchant.com/notification
Name
subscribe
Type
boolean
is optional
Description
Cuando se envía true, se genera una sesión de pago con suscripción.

En el proceso de pago, el usuario puede elegir si quiere o no guardar su medio de pago para que sea usado en futuros cobros.
Name
dispersion
Type
array[DispersionDetail]
is optional
Description
Cuando se define, se genera una sesión de pago con dispersión. El pago generado puede ser dividido en diferentes destinos según las condiciones dadas.
Name
amount
Type
Amount
is optional
Description
Monto a "dispersar" en este destino.
Name
currency
Type
string
is optional
Description
Código alfabético de la moneda a usar (ISO 4217 alpha code)
EJ: USD
Name
total
Type
number
is optional
Description
Valor total en la moneda base indicada
EJ: 1000 equivalen a Mil dolares
Name
taxes
Type
array[Taxes]
is optional
Description
Estructura para definir impuestos en el proceso de pago.
Name
kind
Type
string
is optional
Description
Identificador del tipo de impuesto

Uno de: valueAddedTax exciseDuty ice airportTax stateTax reducedStateTax municipalTax.
Name
amount
Type
number
is optional
Description
Monto total del impuesto
EJ: 200
Name
base
Type
number
is optional
Description
Monto base sobre el cual se calcula el impuesto
EJ: 1000
Name
details
Type
array[Details]
is optional
Description
Estructura para definir detalles adicionales del monto en el proceso de pago.
Name
kind
Type
string
is optional
Description
Identificador del tipo de detalle. Uno de: discount additional vatDevolutionBase shipping handlingFee insurance giftWrap subtotal fee tip airline interests
Name
amount
Type
number
is optional
Description
Monto total del detalle

EJ: 200
Name
agreement
Type
string|number
is optional
Description
Id del destino de este monto. Puede ser el id de un sitio.

EJ: 122
Name
agreementType
Type
string
is optional
Description
Tipo de destino de este monto.
MERCHANT para sitios, AIRLINE para aerolineas.
Name
modifiers
Type
array[Modifiers]
is optional
Description
Estructura para definir modificadores en el cobro.

Aplica para leyes de impuestos en paises especificos.
Name
type
Type
string
is optional
Description
Identificador del tipo de modificador.
Sólo FEDERAL_GOVERMENT es soportado actualmente.
Name
code
Type
number
is optional
Description
Código del modificador.

Para FEDERAL_GOVERMENT representa el número de ley para descuento.
17934 Servicios Gastronómicos
18083 IMESI Brasil - Argentina
19210 Inclusión Financiera
18910 Asignaciones Familiares
18999 Reintegro Inmobiliarias
Name
additional
Type
object
is optional
Description
Estructura para anexar información al modificador
Name
invoice
Type
string
is optional
Description
Requerido cuando modifiers.[].type es FEDERAL_GOVERMENT. Indica el número de factura.

EJ: 123456789
Name
expiration
Type
string
is Required
REQUIRED
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.
EJ: 2023-07-17T13:12:44-05:00
Name
ipAddress
Type
string
is Required
REQUIRED
Description
Dirección IP del usuario que realizará el proceso.
Ej: 134.10.163.36
Name
userAgent
Type
string
is Required
REQUIRED
Description
User Agent del navegador del usuario que realizará el proceso.

EJ: 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.

EJ: https://merchant.com/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, es_CO
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
document
Type
string
is optional
Description
Documento de identidad

Ej: 1017111222
Name
documentType
Type
string
is optional
Description
Identificador del tipo de documento. Ver opciones en Tipos de documento

EJ: CC para "Cédula de Ciudadanía" en Colombia.
Name
name
Type
string
is optional
Description
Nombre de la persona o empresa

EJ: Juan José
Name
surname
Type
string
is optional
Description
Apellido de la persona. No aplica cuando el tipo de documento corresponde al de una empresa

EJ: Peréz Pinzon
Name
company
Type
string
is optional
Description
Nombre de la compañia a la que pertenece la persona

EJ: Placetopay
Name
email
Type
string
is optional
Description
Correo eléctronico del usuario o empresa

EJ: [email protected]
Name
mobile
Type
string
is optional
Description
Número de teléfono del usuario o empresa

EJ: +573214445566
Name
address
Type
object
is optional
Description
Estructura para anexar información del domicilio o dirección
Name
country
Type
string
is optional
Description
País del domicilio

EJ: Colombia
Name
state
Type
string
is optional
Description
Departamento del domicilio

EJ: Antioquia
Name
city
Type
string
is optional
Description
Ciudad del domicilio

EJ: Medellín
Name
postalCode
Type
string
is optional
Description
Código postal del domicilio

EJ: 050012
Name
street
Type
string
is optional
Description
Dirección del domicilio

EJ: Calle 12 #33a-12, Apto 101
Name
phone
Type
string
is optional
Description
Número telefónico del domicilio

EJ: +573214445566
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
document
Type
string
is optional
Description
Documento de identidad

Ej: 1017111222
Name
documentType
Type
string
is optional
Description
Identificador del tipo de documento. Ver opciones en Tipos de documento

EJ: CC para "Cédula de Ciudadanía" en Colombia.
Name
name
Type
string
is optional
Description
Nombre de la persona o empresa

EJ: Juan José
Name
surname
Type
string
is optional
Description
Apellido de la persona. No aplica cuando el tipo de documento corresponde al de una empresa

EJ: Peréz Pinzon
Name
company
Type
string
is optional
Description
Nombre de la compañia a la que pertenece la persona

EJ: Placetopay
Name
email
Type
string
is optional
Description
Correo eléctronico del usuario o empresa

EJ: [email protected]
Name
mobile
Type
string
is optional
Description
Número de teléfono del usuario o empresa

EJ: +573214445566
Name
address
Type
object
is optional
Description
Estructura para anexar información del domicilio o dirección
Name
country
Type
string
is optional
Description
País del domicilio

EJ: Colombia
Name
state
Type
string
is optional
Description
Departamento del domicilio

EJ: Antioquia
Name
city
Type
string
is optional
Description
Ciudad del domicilio

EJ: Medellín
Name
postalCode
Type
string
is optional
Description
Código postal del domicilio

EJ: 050012
Name
street
Type
string
is optional
Description
Dirección del domicilio

EJ: Calle 12 #33a-12, Apto 101
Name
phone
Type
string
is optional
Description
Número telefónico del domicilio

EJ: +573214445566
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
reference
Type
Reference
is optional
Description
Referencia única del proceso. Máximo de 32 caracteres

Ej: PAYMENT_0001_ABC
Name
description
Type
Description
is optional
Description
Descripción del proceso a realizar

EJ: Consumo mes de Mayo
Name
fields
Type
array[NameValuePair]
is optional
Description
Estructura para relacionar información adicional en el proceso. Ver más en Campos Adicionales
Name
keyword
Type
string
is optional
Description
Identificador o índice del dato a anexar.
EJ: cmsInvoiceId
Name
value
Type
string|object|array|number|boolean
is optional
Description
Valor del dato a anexar.
EJ: ID_2233
Name
displayOn
Type
string
is optional
Description
Indica en qué condiciones se muestra el dato anexo. Ver más en Campos Adicionales

Uno de: none, payment, receipt, both, approved.
Name
fields
Type
array[NameValuePair]
is optional
Description
Estructura para relacionar información adicional en el proceso. Ver más en Campos Adicionales
Name
keyword
Type
string
is optional
Description
Identificador o índice del dato a anexar.
EJ: cmsInvoiceId
Name
value
Type
string|object|array|number|boolean
is optional
Description
Valor del dato a anexar.
EJ: ID_2233
Name
displayOn
Type
string
is optional
Description
Indica en qué condiciones se muestra el dato anexo. Ver más en Campos Adicionales

Uno de: none, payment, receipt, both, approved.
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
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

EJ: https://merchant.com/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
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.
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

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":"c51ce410c124a10e0db5e4b97fc2af39",
        "tranKey":"VQOcRcVH2DfL6Y4B4SaK6yhoH/VOUveZ3xT16OQnvxE=",
        "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
status
Type
string
is optional
Description
Estado de una petición o pago
Name
reason
Type
string|number|null
is optional
Description
Código del motivo proporcionado.
Name
message
Type
string|null
is optional
Description
Descripción del código de razón.
Name
date
Type
string
is optional
Description
Fecha y hora en que se genera el estado de pago.
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
Name
login
Type
string
is optional
Description
Identificador del sitio.
Name
tranKey
Type
string
is optional
Description
Credencial tranKey generado.
Ver más en Autenticación
Name
nonce
Type
string
is optional
Description
Valor aleatorio para cada solicitud codificado en Base64.
Name
seed
Type
string
is optional
Description
Fecha actual, la cual se genera en formato ISO 8601.

Solicitud

POST

/api/session/:requestId

curl -X "POST" https://checkout-test.placetopay.com/api/session/000000 \
  -H "Content-Type: application/json" \
  -d '{
      "auth": {
        "login": "c51ce410c124a10e0db5e4b97fc2af39",
        "tranKey": "VQOcRcVH2DfL6Y4B4SaK6yhoH/VOUveZ3xT16OQnvxE=",
        "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
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
status
Type
string
is optional
Description
Estado de una petición o pago
Name
reason
Type
string|number|null
is optional
Description
Código del motivo proporcionado.
Name
message
Type
string|null
is optional
Description
Descripción del código de razón.
Name
date
Type
string
is optional
Description
Fecha y hora en que se genera el estado de pago.
Name
request
Type
RedirectRequest
is optional
Description
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
login
Type
string
is optional
Description
Identificador del sitio.
Name
tranKey
Type
string
is optional
Description
Credencial tranKey generado.
Ver más en Autenticación
Name
nonce
Type
string
is optional
Description
Valor aleatorio para cada solicitud codificado en Base64.
Name
seed
Type
string
is optional
Description
Fecha actual, la cual se genera en formato ISO 8601.
Name
payment
Type
PaymentRequest
is Required
REQUIRED
Description
Información del pago solicitado.
Name
reference
Type
string
is Required
REQUIRED
Description
Referencia única del pago. Máximo de 32 caracteres
Ej: PAYMENT_0001_ABC
Name
description
Type
string
is Required
REQUIRED
Description
Descripción del proceso a realizar
EJ: Consumo mes de Mayo
Name
amount
Type
Amount
is Required
REQUIRED
Description
Información del monto a cobrar
Name
currency
Type
string
is optional
Description
Código alfabético de la moneda a usar (ISO 4217 alpha code)
EJ: USD
Name
total
Type
number
is optional
Description
Valor total en la moneda base indicada
EJ: 1000 equivalen a Mil dolares
Name
taxes
Type
array[Taxes]
is optional
Description
Estructura para definir impuestos en el proceso de pago.
Name
kind
Type
string
is optional
Description
Identificador del tipo de impuesto

Uno de: valueAddedTax exciseDuty ice airportTax stateTax reducedStateTax municipalTax.
Name
amount
Type
number
is optional
Description
Monto total del impuesto
EJ: 200
Name
base
Type
number
is optional
Description
Monto base sobre el cual se calcula el impuesto
EJ: 1000
Name
details
Type
array[Details]
is optional
Description
Estructura para definir detalles adicionales del monto en el proceso de pago.
Name
kind
Type
string
is optional
Description
Identificador del tipo de detalle. Uno de: discount additional vatDevolutionBase shipping handlingFee insurance giftWrap subtotal fee tip airline interests
Name
amount
Type
number
is optional
Description
Monto total del detalle

EJ: 200
Name
allowPartial
Type
boolean
is optional
Description
Define si el monto a ser cobrado puede ser pagado en varias transacciones. Cuando es true el usuario podrá completar el pago en varias transacciones.
Name
shipping
Type
Person
is optional
Description
Estructura para relacionar información de envío.
Name
document
Type
string
is optional
Description
Documento de identidad

Ej: 1017111222
Name
documentType
Type
string
is optional
Description
Identificador del tipo de documento. Ver opciones en Tipos de documento

EJ: CC para "Cédula de Ciudadanía" en Colombia.
Name
name
Type
string
is optional
Description
Nombre de la persona o empresa

EJ: Juan José
Name
surname
Type
string
is optional
Description
Apellido de la persona. No aplica cuando el tipo de documento corresponde al de una empresa

EJ: Peréz Pinzon
Name
company
Type
string
is optional
Description
Nombre de la compañia a la que pertenece la persona

EJ: Placetopay
Name
email
Type
string
is optional
Description
Correo eléctronico del usuario o empresa

EJ: [email protected]
Name
mobile
Type
string
is optional
Description
Número de teléfono del usuario o empresa

EJ: +573214445566
Name
address
Type
object
is optional
Description
Estructura para anexar información del domicilio o dirección
Name
country
Type
string
is optional
Description
País del domicilio

EJ: Colombia
Name
state
Type
string
is optional
Description
Departamento del domicilio

EJ: Antioquia
Name
city
Type
string
is optional
Description
Ciudad del domicilio

EJ: Medellín
Name
postalCode
Type
string
is optional
Description
Código postal del domicilio

EJ: 050012
Name
street
Type
string
is optional
Description
Dirección del domicilio

EJ: Calle 12 #33a-12, Apto 101
Name
phone
Type
string
is optional
Description
Número telefónico del domicilio

EJ: +573214445566
Name
items
Type
array[Item]
is optional
Description
Estructura para relacionar productos o artículos en el proceso.
Name
sku
Type
string
is optional
Description
Identificador SKU del artículo.
EJ: SKU-12345
Name
name
Type
string
is optional
Description
Nombre del artículo.
EJ: Manta de lana
Name
category
Type
string
is optional
Description
Categoría del artículo. Uno de: digital physical
Name
qty
Type
number
is optional
Description
Cantidad de artículos de este tipo.
EJ: 23
Name
price
Type
number
is optional
Description
Costo total del artículo.
EJ: 1400
Name
tax
Type
number
is optional
Description
Monto en impuestos del artículo.
EJ: 100
Name
fields
Type
array[NameValuePair]
is optional
Description
Estructura para relacionar información adicional en el proceso. Ver más en Campos Adicionales
Name
keyword
Type
string
is optional
Description
Identificador o índice del dato a anexar.
EJ: cmsInvoiceId
Name
value
Type
string|object|array|number|boolean
is optional
Description
Valor del dato a anexar.
EJ: ID_2233
Name
displayOn
Type
string
is optional
Description
Indica en qué condiciones se muestra el dato anexo. Ver más en Campos Adicionales

Uno de: none, payment, receipt, both, approved.
Name
recurring
Type
object
is optional
Description
Estructura para indicar la frecuencia de un cobro recurrente.
Name
periodicity
Type
string
is optional
Description
Periodicidad del cobro
D Día, M Mes, Y Año
Name
interval
Type
number
is optional
Description
Intervalo asociado a la periodicidad
EJ: 15 para días.
Name
nextPayment
Type
string
is optional
Description
Fecha del próximo pago
EJ: 2019-08-24
Name
maxPeriods
Type
number
is optional
Description
Número máximo de periodos. Usar -1 en caso de que no haya límite
EJ: 12 para máximo 12 cobros
Name
dueDate
Type
string
is optional
Description
Fecha de vencimiento de la recurrencia
EJ: 2019-09-24
Name
notificationUrl
Type
string
is optional
Description
URL en el que el servicio notificará cada vez que se haga un cobro
EJ: https://merchant.com/notification
Name
subscribe
Type
boolean
is optional
Description
Cuando se envía true, se genera una sesión de pago con suscripción.

En el proceso de pago, el usuario puede elegir si quiere o no guardar su medio de pago para que sea usado en futuros cobros.
Name
dispersion
Type
array[DispersionDetail]
is optional
Description
Cuando se define, se genera una sesión de pago con dispersión. El pago generado puede ser dividido en diferentes destinos según las condiciones dadas.
Name
amount
Type
Amount
is optional
Description
Monto a "dispersar" en este destino.
Name
currency
Type
string
is optional
Description
Código alfabético de la moneda a usar (ISO 4217 alpha code)
EJ: USD
Name
total
Type
number
is optional
Description
Valor total en la moneda base indicada
EJ: 1000 equivalen a Mil dolares
Name
taxes
Type
array[Taxes]
is optional
Description
Estructura para definir impuestos en el proceso de pago.
Name
kind
Type
string
is optional
Description
Identificador del tipo de impuesto

Uno de: valueAddedTax exciseDuty ice airportTax stateTax reducedStateTax municipalTax.
Name
amount
Type
number
is optional
Description
Monto total del impuesto
EJ: 200
Name
base
Type
number
is optional
Description
Monto base sobre el cual se calcula el impuesto
EJ: 1000
Name
details
Type
array[Details]
is optional
Description
Estructura para definir detalles adicionales del monto en el proceso de pago.
Name
kind
Type
string
is optional
Description
Identificador del tipo de detalle. Uno de: discount additional vatDevolutionBase shipping handlingFee insurance giftWrap subtotal fee tip airline interests
Name
amount
Type
number
is optional
Description
Monto total del detalle

EJ: 200
Name
agreement
Type
string|number
is optional
Description
Id del destino de este monto. Puede ser el id de un sitio.

EJ: 122
Name
agreementType
Type
string
is optional
Description
Tipo de destino de este monto.
MERCHANT para sitios, AIRLINE para aerolineas.
Name
modifiers
Type
array[Modifiers]
is optional
Description
Estructura para definir modificadores en el cobro.

Aplica para leyes de impuestos en paises especificos.
Name
type
Type
string
is optional
Description
Identificador del tipo de modificador.
Sólo FEDERAL_GOVERMENT es soportado actualmente.
Name
code
Type
number
is optional
Description
Código del modificador.

Para FEDERAL_GOVERMENT representa el número de ley para descuento.
17934 Servicios Gastronómicos
18083 IMESI Brasil - Argentina
19210 Inclusión Financiera
18910 Asignaciones Familiares
18999 Reintegro Inmobiliarias
Name
additional
Type
object
is optional
Description
Estructura para anexar información al modificador
Name
invoice
Type
string
is optional
Description
Requerido cuando modifiers.[].type es FEDERAL_GOVERMENT. Indica el número de factura.

EJ: 123456789
Name
expiration
Type
string
is Required
REQUIRED
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.
EJ: 2023-07-17T13:12:44-05:00
Name
ipAddress
Type
string
is Required
REQUIRED
Description
Dirección IP del usuario que realizará el proceso.
Ej: 134.10.163.36
Name
userAgent
Type
string
is Required
REQUIRED
Description
User Agent del navegador del usuario que realizará el proceso.

EJ: 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.

EJ: https://merchant.com/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, es_CO
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
document
Type
string
is optional
Description
Documento de identidad

Ej: 1017111222
Name
documentType
Type
string
is optional
Description
Identificador del tipo de documento. Ver opciones en Tipos de documento

EJ: CC para "Cédula de Ciudadanía" en Colombia.
Name
name
Type
string
is optional
Description
Nombre de la persona o empresa

EJ: Juan José
Name
surname
Type
string
is optional
Description
Apellido de la persona. No aplica cuando el tipo de documento corresponde al de una empresa

EJ: Peréz Pinzon
Name
company
Type
string
is optional
Description
Nombre de la compañia a la que pertenece la persona

EJ: Placetopay
Name
email
Type
string
is optional
Description
Correo eléctronico del usuario o empresa

EJ: [email protected]
Name
mobile
Type
string
is optional
Description
Número de teléfono del usuario o empresa

EJ: +573214445566
Name
address
Type
object
is optional
Description
Estructura para anexar información del domicilio o dirección
Name
country
Type
string
is optional
Description
País del domicilio

EJ: Colombia
Name
state
Type
string
is optional
Description
Departamento del domicilio

EJ: Antioquia
Name
city
Type
string
is optional
Description
Ciudad del domicilio

EJ: Medellín
Name
postalCode
Type
string
is optional
Description
Código postal del domicilio

EJ: 050012
Name
street
Type
string
is optional
Description
Dirección del domicilio

EJ: Calle 12 #33a-12, Apto 101
Name
phone
Type
string
is optional
Description
Número telefónico del domicilio

EJ: +573214445566
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
document
Type
string
is optional
Description
Documento de identidad

Ej: 1017111222
Name
documentType
Type
string
is optional
Description
Identificador del tipo de documento. Ver opciones en Tipos de documento

EJ: CC para "Cédula de Ciudadanía" en Colombia.
Name
name
Type
string
is optional
Description
Nombre de la persona o empresa

EJ: Juan José
Name
surname
Type
string
is optional
Description
Apellido de la persona. No aplica cuando el tipo de documento corresponde al de una empresa

EJ: Peréz Pinzon
Name
company
Type
string
is optional
Description
Nombre de la compañia a la que pertenece la persona

EJ: Placetopay
Name
email
Type
string
is optional
Description
Correo eléctronico del usuario o empresa

EJ: [email protected]
Name
mobile
Type
string
is optional
Description
Número de teléfono del usuario o empresa

EJ: +573214445566
Name
address
Type
object
is optional
Description
Estructura para anexar información del domicilio o dirección
Name
country
Type
string
is optional
Description
País del domicilio

EJ: Colombia
Name
state
Type
string
is optional
Description
Departamento del domicilio

EJ: Antioquia
Name
city
Type
string
is optional
Description
Ciudad del domicilio

EJ: Medellín
Name
postalCode
Type
string
is optional
Description
Código postal del domicilio

EJ: 050012
Name
street
Type
string
is optional
Description
Dirección del domicilio

EJ: Calle 12 #33a-12, Apto 101
Name
phone
Type
string
is optional
Description
Número telefónico del domicilio

EJ: +573214445566
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
reference
Type
Reference
is optional
Description
Referencia única del proceso. Máximo de 32 caracteres

Ej: PAYMENT_0001_ABC
Name
description
Type
Description
is optional
Description
Descripción del proceso a realizar

EJ: Consumo mes de Mayo
Name
fields
Type
array[NameValuePair]
is optional
Description
Estructura para relacionar información adicional en el proceso. Ver más en Campos Adicionales
Name
keyword
Type
string
is optional
Description
Identificador o índice del dato a anexar.
EJ: cmsInvoiceId
Name
value
Type
string|object|array|number|boolean
is optional
Description
Valor del dato a anexar.
EJ: ID_2233
Name
displayOn
Type
string
is optional
Description
Indica en qué condiciones se muestra el dato anexo. Ver más en Campos Adicionales

Uno de: none, payment, receipt, both, approved.
Name
fields
Type
array[NameValuePair]
is optional
Description
Estructura para relacionar información adicional en el proceso. Ver más en Campos Adicionales
Name
keyword
Type
string
is optional
Description
Identificador o índice del dato a anexar.
EJ: cmsInvoiceId
Name
value
Type
string|object|array|number|boolean
is optional
Description
Valor del dato a anexar.
EJ: ID_2233
Name
displayOn
Type
string
is optional
Description
Indica en qué condiciones se muestra el dato anexo. Ver más en Campos Adicionales

Uno de: none, payment, receipt, both, approved.
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
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

EJ: https://merchant.com/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
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.
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
Name
payment
Type
Transaction
is optional
Description
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
status
Type
string
is optional
Description
Estado de una petición o pago
Name
reason
Type
string|number|null
is optional
Description
Código del motivo proporcionado.
Name
message
Type
string|null
is optional
Description
Descripción del código de razón.
Name
date
Type
string
is optional
Description
Fecha y hora en que se genera el estado de pago.
Name
internalReference
Type
integer
is optional
Description
Referencia interna en PlacetoPay.
Name
reference
Type
string
is optional
Description
Referencia enviada por el comercio para la transacción.
Name
paymentMethod
Type
string
is optional
Description
Código del método de pago utilizado.
Name
paymentMethodName
Type
string
is optional
Description
Nombre del método de pago utilizado.
Name
issuerName
Type
string
is optional
Description
Nombre del emisor o del procesador.
Name
amount
Type
AmountConversion
is optional
Description
Estructura para definir el factor de conversión y los valores.
Name
from
Type
AmountBase
is optional
Description
Estructura que representa una cantidad que define la moneda y el total.
Name
currency
Type
string
is optional
Description
Moneda acorde al ISO 4217 (alphabetic code).
Name
total
Type
number|string
is optional
Description
Valor total.
Name
to
Type
AmountBase
is optional
Description
Estructura que representa una cantidad que define la moneda y el total.
Name
currency
Type
string
is optional
Description
Moneda acorde al ISO 4217 (alphabetic code).
Name
total
Type
number|string
is optional
Description
Valor total.
Name
factor
Type
number|string
is optional
Description
Factor de conversión
Name
receipt
Type
string
is optional
Description
Numero de recibo de la transacción.
Name
franchise
Type
string
is optional
Description
Franquicia de la tarjeta utilizada.
Name
refunded
Type
boolean
is optional
Description
Se utiliza para definir si la transacción ha sido reversada
Name
authorization
Type
string
is optional
Description
Código de autorización.
Name
processorFields
Type
array[NameValuePair]
is optional
Description
Estructura que puede variar en el tiempo según la información disponible para el medio de pago.
Name
keyword
Type
string
is optional
Description
Identificador o índice del dato a anexar.
EJ: cmsInvoiceId
Name
value
Type
string|object|array|number|boolean
is optional
Description
Valor del dato a anexar.
EJ: ID_2233
Name
displayOn
Type
string
is optional
Description
Indica en qué condiciones se muestra el dato anexo. Ver más en Campos Adicionales

Uno de: none, payment, receipt, both, approved.
Name
dispersion
Type
Transaction Dispersion
is optional
Description
Estructura que contiene información de dispersión
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
status
Type
string
is optional
Description
Estado de una petición o pago
Name
reason
Type
string|number|null
is optional
Description
Código del motivo proporcionado.
Name
message
Type
string|null
is optional
Description
Descripción del código de razón.
Name
date
Type
string
is optional
Description
Fecha y hora en que se genera el estado de pago.
Name
agreement
Type
integer|null|string|number
is optional
Description
Identificador de destinatario de la transacción. Para el sitio principal de la transacción.
Name
agreementType
Type
string|null
is optional
Description
Tipo de dispersión
Name
authorization
Type
string|null
is optional
Description
Código de autorización.
Name
receipt
Type
string|null
is optional
Description
Numero de recibo de la transacción.
Name
amount
Type
AmountConversion
is optional
Description
Estructura para definir el factor de conversión y los valores.
Name
from
Type
AmountBase
is optional
Description
Estructura que representa una cantidad que define la moneda y el total.
Name
currency
Type
string
is optional
Description
Moneda acorde al ISO 4217 (alphabetic code).
Name
total
Type
number|string
is optional
Description
Valor total.
Name
to
Type
AmountBase
is optional
Description
Estructura que representa una cantidad que define la moneda y el total.
Name
currency
Type
string
is optional
Description
Moneda acorde al ISO 4217 (alphabetic code).
Name
total
Type
number|string
is optional
Description
Valor total.
Name
factor
Type
number|string
is optional
Description
Factor de conversión
Name
refunded
Type
boolean
is optional
Description
Se utiliza para definir si la transacción ha sido reversada
Name
paymentMethod
Type
string
is optional
Description
Código del método de pago utilizado.
Name
agreement
Type
integer|null|string|number
is optional
Description
Identificador de destinatario de la transacción. Para el sitio principal de la transacción.
Name
agreementType
Type
string|null
is optional
Description
Tipo de dispersión
Name
discount
Type
object|null
is optional
Description
Name
base
Type
string|number
is optional
Description
Name
code
Type
string
is optional
Description
Name
type
Type
string
is optional
Description
Name
amount
Type
number|string
is optional
Description
Name
subscription
Type
string|null
is optional
Description
Name
subscription
Type
SubscriptionResponse
is optional
Description
Estructura que contiene información para el método de pago suscripción.
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
status
Type
string
is optional
Description
Estado de una petición o pago
Name
reason
Type
string|number|null
is optional
Description
Código del motivo proporcionado.
Name
message
Type
string|null
is optional
Description
Descripción del código de razón.
Name
date
Type
string
is optional
Description
Fecha y hora en que se genera el estado de pago.
Name
type
Type
string
is optional
Description
Define tipo de suscripción que se devuelve
Name
instrument
Type
array[NameValuePair]
is optional
Description
Name
keyword
Type
string
is optional
Description
Identificador o índice del dato a anexar.
EJ: cmsInvoiceId
Name
value
Type
string|object|array|number|boolean
is optional
Description
Valor del dato a anexar.
EJ: ID_2233
Name
displayOn
Type
string
is optional
Description
Indica en qué condiciones se muestra el dato anexo. Ver más en Campos Adicionales

Uno de: none, payment, receipt, both, approved.

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": "Colombia",
        "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": "Colombia",
        "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": "Colombia",
          "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"
      }
    ]
  }
}