Redirección

Aquí puedes consultar la referencia de nuestra API

API Reference

Este 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, D para días, M para meses y Y para años
  • Un intervalo asociado a la periodicidad (interval), el valor -1 representa un intervalo indefinido
  • La fecha del próximo pago (nextPayment) con el formato AAAA-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.