Redirección
Aquí puedes consultar la referencia de nuestra API
API ReferenceEste servicio web y su arquitectura permite a cualquier aplicación conectarse a Place to Pay, independiente del lenguaje de desarrollo. Para usar el servicio web, deberás tener un lenguaje de programación que pueda comunicarse con un servicio SOAP o REST.
Autenticación
Todas las peticiones al servicio deben contener la siguiente estructura de autenticación
{
auth: {
"login": "6dd490faf9cb87a9862245da41170ff2",
"seed": "2017-07-24T15:21:10-05:00",
"nonce": "ZjgzYzNkNzI1MmEwNjRlNzlhZDViOGIyNmQxNjcxZTg=",
"tranKey": "gUwHkL4tiU+0oCWEiWw0q2uUfwQ="
},
...
}
Datos suministrados por Place to Pay
- Nombre único de usuario (
login) - Llave secreta (
secretKey), necesaria para la construcción de la llave transaccional (tranKey)
¿Cómo generar el seed?
Fecha actual en formato ISO 8601
Ejemplo: PHP
$seed = date('c');
¿Cómo generar el nonce?
Valor aleatorio para cada solicitud codificado en Base64.
Ejemplo: PHP
if (function_exists('random_bytes')) {
$nonce = bin2hex(random_bytes(16));
} elseif (function_exists('openssl_random_pseudo_bytes')) {
$nonce = bin2hex(openssl_random_pseudo_bytes(16));
} else {
$nonce = mt_rand();
}
$nonceBase64 = base64_encode($nonce);
¿Cómo generar el tranKey?
El valor del tranKey es el resultado de la siguiente operación: Base64(SHA-1(nonce + seed + secretKey)).
El nonce dentro del SHA-1 no es codificado en Base64, sólo está codificado como parámetro.
Ejemplo: PHP
$tranKey = base64_encode(sha1($nonce . $seed . $secretKey, true));
Pago básico
Datos con los que debes contar
- Referencia única para la solicitud de pago
- Descripción del pago
- Moneda en que se realizará el pago
- Monto a pagar
Crear petición de pago
POST /api/session
{
"auth": {
...
},
"payment": {
"reference": "5976030f5575d",
"description": "Pago básico de prueba",
"amount": {
"currency": "COP",
"total": "10000"
}
},
"expiration": "2017-08-01T00:00:00-05:00",
"returnUrl": "https://dev.placetopay.com/redirection/sandbox/session/5976030f5575d",
"ipAddress": "127.0.0.1",
"userAgent": "PlacetoPay Sandbox"
}
Consideraciones
- El tiempo de expiración (
expiration) debe ser una fecha válida en formato ISO 8601, indica el tiempo limite que tiene el usuario para realizar el pago y debe ser de al menos 5 minutos mayor que la fecha actual. - La url de retorno (
returnUrl) es utilizada para redirigir al usuario una vez terminada la operación. Se recomienda incluir el valor de la referencia de pago en la url para poder identificarlo posteriormente.
Respuestas del servicio
Si la respuesta obtenida es fallida al momento de crear la peticion de pago:
{
"status": {
"status": "FAILED",
"reason": 0,
"message": "No se ha solicitado ningún tipo de operación",
"date": "2017-07-31T10:42:21-05:00"
}
}
El atributo message detalla el problema generado al momento de crear la petion de pago.
La estructura enviada por Place to Pay cuando la petición es exitosa es la mostrada a continuación:
{
"status": {
"status": "OK",
"reason": "PC",
"message": "La petición se ha procesado correctamente",
"date": "2017-07-31T10:43:21-05:00"
},
"requestId": 784,
"processUrl": "https://dev.placetopay.com/redirection/session/784/8135922ccf67492be57121e29e60f12f"
}
El identificador (requestId) es una referencia única de la plataforma de pago. Se recomienda relacionar este atributo con la referencia de pago interna.
La url de procesamiento (processUrl) generada por Place to Pay permite redirigir al usuario para poder continuar con el proceso de pago correspondiente.
Redireccionar al usuario
Al ser redireccionado el usuario ingresa a la plataforma de pago de Place to Pay.
Una vez el usuario culmina el pago este puede retornar al comercio.
Consultar información de la transacción
Si el usuario retorna al comercio, este debe consultar la información de la transacción usando el identificador único (requestId) generado anteriormente.
POST /api/session/784
La estructura de la respuesta contiene toda la información de la petición de pago original y una lista con el detalle de los pagos realizados sobre esa sesión.
{
"requestId": 784,
"status": {
"status": "APPROVED",
"reason": "00",
"message": "La petición ha sido aprobada exitosamente",
"date": "2017-07-31T10:57:10-05:00"
},
"request": {
"locale": "es_CO",
"payer": {
"document": "1234567890",
"documentType": "CC",
"name": "Jhon",
"surname": "Doe",
"email": "jhondoe@placetopay.com",
"mobile": "3216549870"
},
"buyer": null,
"payment": {
"reference": "5976030f5575d",
"description": "Pago básico de prueba",
"amount": {
"currency": "COP",
"total": "10000"
},
"allowPartial": false
},
"subscription": null,
"fields": null,
"returnUrl": "https://dev.placetopay.com/redirection/sandbox/session/5976030f5575d",
"paymentMethod": null,
"cancelUrl": null,
"ipAddress": "127.0.0.1",
"userAgent": "PlacetoPay Sandbox",
"expiration": "2017-08-01T00:00:00-05:00",
"captureAddress": false,
"skipResult": false,
"noBuyerFill": false
},
"payment": [
{
"status": {
"status": "APPROVED",
"reason": "00",
"message": "Aprobada",
"date": "2017-07-31T10:52:40-05:00"
},
"internalReference": 1449483329,
"paymentMethod": "card",
"paymentMethodName": "Visa",
"issuerName": "BANCO DE PRUEBAS",
"amount": {
"from": {
"currency": "COP",
"total": 10000
},
"to": {
"currency": "COP",
"total": 10000
},
"factor": 1
},
"authorization": "000000",
"reference": "5976030f5575d",
"receipt": "1501516360",
"franchise": "CR_VS",
"refunded": false,
"processorFields": [
{
"keyword": "lastDigits",
"value": "****1111",
"displayOn": "none"
},
{
"keyword": "id",
"value": "bee8340b8908e3c9488df8fe41b70d07",
"displayOn": "none"
}
]
}
],
"subscription": null
}
Pago Mixto
Datos con los que debes contar
- Referencia única para la solicitud de pago
- Descripción del pago
- Moneda en que se realizará el pago
- Monto a pagar
Crear petición de pago
A diferencia del pago básico, en el pago mixto es necesario incluir el atributo allowPartial dentro de la estructura de pago con el valor true.
POST /api/session
{
"auth": {
...
},
"payment": {
"reference": "5980a78fd4420",
"description": "Pago mixto de prueba",
"amount": {
"currency": "COP",
"total": "10000"
},
"allowPartial": true
},
"expiration": "2017-08-01T11:15:00-05:00",
"returnUrl": "https://dev.placetopay.com/redirection/sandbox/session/5980a78fd4420",
"ipAddress": "127.0.0.1",
"userAgent": "PlacetoPay Sandbox"
}
En la plataforma se le permite al usuario dividir el valor a pagar entre los medios de pagos disponibles del comercio.
Estados adicionales de una sesión de pago mixto
Al obtener la información de una transacción pago mixto, el estado de la misma se puede encontrar con los siguientes casos:
Cuando se ha realizado un pago pero no se ha completado el monto total
{
...
"status": {
"status": "APPROVED_PARTIAL",
"reason": "P0",
"message": "La petición está parcialmente aprobada",
"date": "2017-08-01T11:13:27-05:00"
},
...
}
Cuando se ha realizado un pago y el tiempo de expiración finalizó
{
...
"status": {
"status": "PARTIAL_EXPIRED",
"reason": "PX",
"message": "La petición esta expirada o cancelada y se han realizado pagos",
"date": "2017-08-01T11:15:38-05:00"
},
...
}
Pago recurrente
Datos con los que debes contar
- Referencia única para la solicitud de pago
- Descripción del pago
- Moneda en que se realizará el pago
- Monto a pagar
- Periodicidad del pago
- Intervalo asociado a la periodicidad
- Fecha de próximo pago
- Número máximo de periodo
Crear petición de pago
A diferencia del pago básico, en el pago recurrente es necesario incluir la estructura recurring dentro de la estructura de pago, la misma contiene:
- La periodicidad (
periodicity) representada con una letra,Dpara días,Mpara meses yYpara años - Un intervalo asociado a la periodicidad (
interval), el valor-1representa un intervalo indefinido - La fecha del próximo pago (
nextPayment) con el formatoAAAA-MM-DD - Un número máximo de periodos a recaudar (
maxPeriods)
POST /api/session
{
"auth": {
...
},
"payment": {
"reference": "5976030f5575d",
"description": "Pago parcial de prueba",
"amount": {
"currency": "COP",
"total": "10000"
},
"recurring": {
"periodicity": "M",
"interval": "1",
"nextPayment": "2017-08-25",
"maxPeriods": "12"
}
},
"expiration": "2017-07-25T00:00:00-05:00",
"returnUrl": "https://placetopay.com/",
"ipAddress": "127.0.0.1",
"userAgent": "PlacetoPay eShop"
}
Suscripción
Datos con los que debes contar
- Referencia única para la solicitud de suscripción
- Descripción de la suscripción
Crear petición de suscripción
POST /api/session
{
"auth": {
...
},
"subscription": {
"reference": "5980a9c8dc043",
"description": "Una suscripción de prueba"
},
"expiration": "2017-08-02T00:00:00-05:00",
"returnUrl": "https://dev.placetopay.com/redirection/sandbox/session/5980a9c8dc043",
"ipAddress": "127.0.0.1",
"userAgent": "PlacetoPay Sandbox"
}
Respuesta exitosa del servicio
{
"status": {
"status": "OK",
"reason": "PC",
"message": "La petición se ha procesado correctamente",
"date": "2017-08-01T11:19:14-05:00"
},
"requestId": 793,
"processUrl": "https://dev.placetopay.com/redirection/session/793/6a0517f74abe08a4fac4b88ffb8fb67b"
}
Redireccionar al usuario
Al ser redireccionado el usuario ingresa a la plataforma de pago de Place to Pay.
Una vez el usuario culmina la suscripción este puede retornar al comercio.
Consultar información de la transacción
Si el usuario retorna al comercio, este debe consultar la información de la transacción usando el identificador único (requestId) generado anteriormente.
POST /api/session/793
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.
{
"requestId": 793,
"status": {
"status": "APPROVED",
"reason": "00",
"message": "La petición ha sido aprobada exitosamente",
"date": "2017-08-01T11:37:12-05:00"
},
"request": {
"locale": "es_CO",
"payer": {
"document": "123456789",
"documentType": "CC",
"name": "Jhon",
"surname": "Doe",
"email": "jhondoe@placetopay.com",
"mobile": "3216549870"
},
"buyer": null,
"payment": null,
"subscription": {
"reference": "5980a9c8dc043",
"description": "Una suscripción de prueba"
},
"fields": null,
"returnUrl": "https://dev.placetopay.com/redirection/sandbox/session/5980a9c8dc043",
"paymentMethod": null,
"cancelUrl": null,
"ipAddress": "127.0.0.1",
"userAgent": "PlacetoPay Sandbox",
"expiration": "2017-08-02T00:00:00-05:00",
"captureAddress": false,
"skipResult": false,
"noBuyerFill": false
},
"payment": null,
"subscription": {
"type": "token",
"status": {
"status": "OK",
"reason": "00",
"message": "Token generated successfully",
"date": "2017-08-01T11:36:10-05:00"
},
"instrument": [
{
"keyword": "token",
"value": "9e7d3e05beefc9ee37b09218802115ee37d60654fc0618fa5f49a6d2582f0648",
"displayOn": "none"
},
{
"keyword": "subtoken",
"value": "4000422479591111",
"displayOn": "none"
},
{
"keyword": "franchise",
"value": "CR_VS",
"displayOn": "none"
},
{
"keyword": "franchiseName",
"value": "VISA",
"displayOn": "none"
},
{
"keyword": "issuerName",
"value": null,
"displayOn": "none"
},
{
"keyword": "lastDigits",
"value": "1111",
"displayOn": "none"
},
{
"keyword": "validUntil",
"value": "2018-12-15",
"displayOn": "none"
},
{
"keyword": "installments",
"value": "12",
"displayOn": "none"
}
]
}
}
Recaudar pago
Con el token obtenido anteriormente se procede a realizar la petición de recaudo del pago, adicionalmente debe enviarse una estructura de pago (payment) y pagador (payer) como la siguiente:
POST /api/collect
{
"auth": {
},
"instrument": {
"token": {
"token": "9e7d3e05beefc9ee37b09218802115ee37d60654fc0618fa5f49a6d2582f0648"
}
},
"payer": {
"document": "1234567890",
"documentType": "CC",
"name": "Jhon",
"surname": "Doe",
"email": "jhondoe@placetopay.com"
},
"payment": {
"reference": "5980afd6b1611",
"description": "Pago con suscripción",
"amount": {
"currency": "COP",
"total": "10000"
}
}
}
Respuesta positiva del recaudo
{
"requestId": 794,
"status": {
"status": "APPROVED",
"reason": "00",
"message": "La petición ha sido aprobada exitosamente",
"date": "2017-08-01T11:45:01-05:00"
},
"request": {
"locale": "es_CO",
"payer": {
"document": "1234567890",
"documentType": "CC",
"name": "Jhon",
"surname": "Doe",
"email": "jhondoe@placetopay.com"
},
"buyer": null,
"payment": {
"reference": "5980afd6b1611",
"description": "Pago con suscripción",
"amount": {
"currency": "COP",
"total": "10000"
},
"allowPartial": false
},
"subscription": null,
"fields": null,
"returnUrl": "https://dev.placetopay.com/redirection",
"paymentMethod": null,
"cancelUrl": null,
"ipAddress": "181.137.138.120",
"userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.78 Safari/537.36",
"expiration": "2017-09-01T11:45:01-05:00",
"captureAddress": false,
"skipResult": false,
"noBuyerFill": false
},
"payment": [
{
"status": {
"status": "APPROVED",
"reason": "00",
"message": "Aprobada",
"date": "2017-08-01T11:45:01-05:00"
},
"internalReference": 1449534072,
"paymentMethod": "card",
"paymentMethodName": "Visa",
"issuerName": "BANCO DE PRUEBAS",
"amount": {
"from": {
"currency": "COP",
"total": 10000
},
"to": {
"currency": "COP",
"total": 10000
},
"factor": 1
},
"authorization": "000000",
"reference": "5980afd6b1611",
"receipt": "1501605901",
"franchise": "CR_VS",
"refunded": false,
"processorFields": [
{
"keyword": "lastDigits",
"value": "****1111",
"displayOn": "none"
},
{
"keyword": "id",
"value": "081a0f5f6e28943e8cae302b8df23ad8",
"displayOn": "none"
}
]
}
],
"subscription": null
}
Notificación
Cuando un pago es aprobado o rechazado la plataforma hace una petición a la url de notificación configurada por el comercio con la siguiente estructura:
{
"status": {
"status": "APPROVED",
"message": "",
"reason": "",
"date": "2016-09-15T13:49:01-05:00"
},
"requestId": 58,
"reference": "ORDER-1000",
"signature": "feb3e7cc76939c346f9640573a208662f30704ab"
}
Descripción de la petición
El estado de la sesión (status) puede contener los valores APPROVED o REJECTED.
El identificador de la sesión (requestId) y la referencia (reference) identifican la sesión de pago afectada.
La firma (signature) permite validar la petición recibida.
Consideraciones
Puedes validar que se trate de una respuesta de Place to Pay haciendo un SHA-1 con los datos requestId + status + date + secretKey, para el caso del ejemplo y si el secretKey del comercio fuera ABCD1234 sería: sha1("58APPROVED2016-09-15T13:49:01-05:00ABCD1234").
Bajo ninguna circunstancia reveles tu secretKey en ninguna parte accesible a los clientes o usuarios de su aplicación.
Si este valor coincide con el valor proporcionado por el signature, puedes autenticar la respuesta y proceder a asentar en la base de datos.