NAV Navbar
shell csharp php

WebCheckOut

Con WebCheckOut tu sitio obtiene una URL a la cual será redireccionado tu usuario para realizar el proceso transaccional. De esta manera, evitas capturar información sensible y la definición para una interfaz de un proceso de pago.

El API de WebCheckOut está basado en REST, retorna respuestas con codificación JSON. Para hacer uso de este servicio es necesario que tu sitio se conecte usando la versión 1.2 de TLS.

Puede usar la API WebCheckOut en modo de prueba, que no interactúa con las redes bancarias. Dependiendo del endpoint usado en la solicitud determina si la misma es en modo productivo o en modo de prueba.

Modo pruebas: https://test.placetopay.com/redirection/api/session/

Modo producción: https://secure.placetopay.com/redirection/api/session/

Consideraciones:

Importante: El expiration es el tiempo máximo que se da para la sesión, si un usuario no realiza la operación la sesión queda pendiente hasta expirar.

Importante: Esta URL de notificación debe ser suministrada a PlacetoPay para su configuración.

Flujo de integración

Warehouse@2x

  1. Al momento del usuario proceder con la operación en tu sitio, debes consumir el método createRequest.
  2. Si la solicitud es procesada correctamente, el servicio crea una sesión y retorna en la respuesta:
    • Identificador requestID
    • URL de procesamiento processUrl.
  3. Crea un registro en tu sistema, relaciona ese registro al requestID y déjalo en estado pendiente.
  4. Redirecciona al usuario al processURL obtenido en el punto 2.
  5. En la interfaz de Web Checkout el usuario realizará el proceso de pago o suscripción.
  6. Una vez el usuario realiza el proceso y hace clic en “Regresar al comercio”, éste es enviado a la URL de retorno returnUrl (Atributo especificado al crear la operación).
  7. Al llegar a tu sitio, con el requestID del registro debes consultar a PlacetoPay el estado de la sesión usando el método getRequestInformation.
  8. Ejecuta tu regla de negocio según el estado obtenido.
  9. De manera asincrónica, PlacetoPay realiza una notificación, del estado final de una sesión, a tu sitio.
  10. Recomendamos implementar un proceso sonda para resolver aquellas transacciones que no se resolvieron en los punto 7 y 9.

Librerías

Instalación para C Sharp

¿Dónde obtener la librería?

Repositorio: SDK .NET Framework 4.5.0 de Web Checkout.

DLL y dependencias:

https://drive.google.com/open?id=1UMy7SibuN3aVlRd4B8oLifCVQwxURzzv

¿Qué versiones soporta?

La versión es estable para la versión 4.5.0

¿Qué datos debo tener antes de iniciar la instalación?

PlacetoPay suministra login y trankey, datos que serán usados para la autenticación y relacionar las transacciones al sitio correspondiente.

Agregar dependencia en Visual Studio

Ir al explorador de soluciones, desplegar las opciones del proyecto y luego:
Dependencias -> agregar referencia -> examinar -> examinar -> seleccionar dll -> Aceptar

¿Cómo usar la clase?

Configurar instancia PlacetoPay necesaria para autenticarse ante los servicios web de PlacetoPay.

    using P2P = PlacetoPay.Integrations.Library.CSharp.PlacetoPay;
    Gateway gateway = new P2P(YOUR_LOGIN,
                              YOUR_TRANKEY,
                              new Uri("URL_INTEGRATION"),
                              Gateway.TP_SOAP or Gateway.TP_REST);

El parámetro "URL_INTEGRATION" hace referencia al endpoint a usar, los cuales son:
Pruebas: https://test.placetopay.com/redirection/
Producción: https://secure.placetopay.com/redirection/

Crear una nueva sesión de pago CreateRequest

Solicita la creación de la sesión (petición de cobro o suscripción) y retorna el identificador y la URL de procesamiento.

Ejemplo de llamada:

    Amount amount = new Amount('PAYMENT_AMOUNT');
    Payment payment = new Payment("REFERENCE", "DESCRIPTION", amount);
    RedirectRequest request = new RedirectRequest(payment,
        RETURN_URL,
        IP_ADDRESS,
        USER_AGENT,
        EXPIRATION);

    RedirectResponse response = gateway.Request(request);

Retorno:
Servicio responde una instancia de la clase RedirectResponse. Verificando el status de la respuesta se puede determinar si se creó la session de pago.

Success Response: si el status es igual a “OK”

Verificar: response.IsSuccessful() // return boolean

Error Response: si el status es igual a “ERROR”

Verificar motivo del error: response.Status.Message // return string

Obtenga información sobre una sesión (getRequestInformation)

Obtiene la información de la sesión y transacciones realizadas.

Ejemplo de llamada:

    RedirectInformation response = gateway.Query(requestId);

Retorno:

Servicio responde una instancia de la clase RedirectInformation. Se puede verificar el status de la sesión a través:

response.IsSuccessful() // return boolean
response.IsRejected() // return boolean
response.IsApproved() // return boolean
response.Status.status // return boolean

Cobro sin intervención del usuario (Collect)

Permite realizar cobros sin la intervención del usuario usando medios de pago previamente suscritos.

Ejemplo de llamada:

    Token token = new Token(YOUR_TOKEN);
    Instrument instrument = new Instrument(token);
    Person person = new Person(dni, type, Name, Surname, email);
    Amount amount = new Amount(1000);
    Payment payment = new Payment("123456789", "TEST", amount);
    CollectRequest collectRequest = new CollectRequest(person,
                                            payment,instrument);
    RedirectInformation collect = this.gateway.Collect(collectRequest);

Retorno:
Servicio responde una instancia de la clase RedirectInformation. Se puede verificar el status de la sesión a través:

response.IsSuccessful() // return boolean
response.IsRejected() // return boolean
response.IsApproved() // return boolean
response.Status.status // return boolean

Revertir un pago (reversePayment)

Permite revertir un pago aprobado con el código de referencia interna.

Ejemplo de llamada:

    ReverseResponse response = this.gateway.Reverse(requestId);

Retorno:
Servicio responde una instancia de la clase ReverseResponse. Se puede verificar el status de la sesión a través:

response.IsSuccessful() // return boolean
response.Status.status // return boolean

Leer respuesta enviada a la url de notificación (ReadNotification)

Permite leer la respuesta enviada por parte de PlacetoPay a la Url de notificación del comercio.

Ejemplo de llamada:

// La notificación enviado por parte de PlacetoPay tiene la siguiente forma.

{
   "status":{
      "status":"APPROVED",
      "reason":"00",
      "message":"Se ha aprobado su pago",
      "date":"2016-10-10T16:39:57-05:00"
   },
   "requestId":83,
   "reference":"TEST_20161010_213937",
   "signature":"8fb4beea130ab3e75a1de956bd0213892e0f6839"
}

// La variable “data” debe ser un json con la estructura mencionada arriba en formato string.

Notification notification = _gateway.ReadNotification(data);

   // Verificar si la notificación es válida
   if (notification.isValidNotification()) {
       if (notification.isApproved()) {
           // Liberar el producto
       } else {
           // Rechazar la orden
       }
   } else {
       // There was some error or invalid structure
   }

Posibles errores

Para cado uno de los objetos de respuesta, al momento de presentarse alguna excepción o problema de conexión se informa en la propiedad status.

Instalación librerÍas para JAVA

Para conectarse con PlacetoPay por medio del servicio de web checkout utilizando java, ingrese al siguiente enlace:

https://github.com/placetopay/java-placetopay

Autenticación


Ejemplo:
    Información proporcionada:
    login = usuarioprueba
    secretKey = ABCD1234

    Datos generados por el usuario:
    nonce = c9085e82debb82b0955579098be3d7ca //Nonce original
    seed = 2019-04-25T18:17:23-04:00

    Datos a enviar:
    tranKey = i/RFwSHAh8d7YgtO3HME5kCnYy8=
    nonce = YzkwODVlODJkZWJiODJiMDk1NTU3OTA5OGJlM2Q3Y2E= //Nonce en base64

Ejemplo:
POST /api/session

{
  "auth": {
    "login": "usuarioprueba",
    "tranKey": "T0O+x3gNlQUf0iBxEuenPvBPlWs=",
    "nonce": "YzkwODVlODJkZWJiODJiMDk1NTU3OTA5OGJlM2Q3Y2E=",
    "seed": "2019-04-25T18:17:23-04:00",
  }
}

La autenticación al servicio debe ser enviada sobre el objeto auth, el cual debe contener los siguientes atributos:

Parámetro Descripción
login Identificador del sitio.
tranKey Llave transaccional, que está formada por la siguiente operación: Base64(SHA-1(nonce + seed + secretkey)). El nonce dentro de la operación es el original, es decir, el que no está en Base64.
nonce Valor aleatorio para cada solicitud codificado en Base64.
seed Fecha actual, la cual se genera en formato ISO 8601.

Ejemplos de autenticación

PHP JAVA C# NodeJS

Todas las solicitudes al web deben ser autenticadas con WS Security UsernameToken Profile 1.1

Usando PasswordDigest (PasswordDigest = Base64 ( SHA-1 ( nonce + created + tranKey ) ))

Errores

Ejemplo autenticación fallida:

{
    "status": {
        "status": "FAILED",
        "reason": 401,
        "message": "Authentication Failed 103",
        "date": "2019-03-06T17:08:36-05:00"
    }
}

El servicio de Web CheckOut retorna los códigos de respuesta para la autenticación fallida en el atributo message del objeto status.

Código Causa
100 UsernameToken no proporcionado (Encabezado de la autorización malformado).
101 Identificador de sitio no existe ( Login incorrecto o no se encuentra en el ambiente).
102 El hash de TranKey no coincide (Trankey incorrecto o mal formado).
103 Fecha de la semilla mayor de 5 minutos.
104 Sitio inactivo.
105 Sitio expirado.
106 Credenciales expiradas.
107 Mala definición del UsernameToken (No cumple con el encabezado WSSE).
200 Saltar el encabezado de autenticación SOAP.
10001 Contacte a Soporte.

.

Errores frecuentes

Métodos de Interfaz de Web CheckOut

El web service contiene diferentes métodos donde se ejecutan operaciones de tipo solicitud - respuesta, estas requieren para cada una, parámetros de ingreso que son usados por las estructuras de datos con las que se procesan información para posteriormente retornar una respuesta.

Si deseas ejecutar un método rápidamente puedes usar: https://dnetix.co/p2p/client

CreateRequest

Ejemplo para la petición de un pago:

POST /api/session

{
  "auth": {
    "login": "usuarioprueba",
    "tranKey": "jsHJzM3+XG754wXh+aBvi70D9/4=",
    "nonce": "TTJSa05UVmtNR000TlRrM1pqQTRNV1EREprWkRVMU9EZz0=",
    "seed": "2019-04-25T18:17:23-04:00"
  },
    "locale": "en_CO",
    "buyer": {
      "name": "Deion",
      "surname": "Ondricka",
      "email": "dnetix@yopmail.com",
      "document": "1040035000",
      "documentType": "CC",
      "mobile": 3006108300
  },

    "payment": {
        "reference": "3210",
        "description": "Pago básico de prueba 04032019",
        "amount": {
            "currency": "COP",
            "total": "10000"
        },
      "allowPartial":false
      },

    "expiration": "2019-03-05T00:00:00-05:00",
    "returnUrl": "https://mysite.com/response/3210",
    "ipAddress": "127.0.0.1",
    "userAgent": "PlacetoPay Sandbox"
}

Solicita la creación de la sesión (petición de cobro o suscripción) y retorna el identificador y la URL de procesamiento.

PARÁMETROS

Name Type Description
payload Opcional RedirectRequest Información sobre el pago requerido

Retorna
RedirectResponse: Es un objeto con la información de redirección.

GetRequestInformation

Ejemplo para obtener información de una petición:

POST /api/session/REQUEST_ID
Remplace el REQUEST_ID con el valor devuelto en la respuesta de la petición de pago.

{
  "auth": {
    "login": "usuarioprueba",
    "tranKey": "T0O+x3gNlQUf0iBxEuenPvBPlWs=",
    "nonce": "YzkwODVlODJkZWJiODJiMDk1NTU3OTA5OGJlM2Q3Y2E=",
    "seed": "2019-04-25T18:17:23-04:00",
  }
}

Obtiene la información de la sesión y transacciones realizadas.

PARÁMETROS

Name Type Description
requestId Requerido int Identificador de la sesión a consultar.

Retorna
RedirectInformation: Información del estado de la transacción

ReversePayment

Ejemplo para revertir un pago aprobado:

POST /api/reverse
{
    "auth": {
    "login": "usuarioprueba",
    "tranKey": "jsHJzM3+XG754wXh+aBvi70D9/4=",
    "nonce": "TTJSa05UVmtNR000TlRrM1pqQTRNV1EREprWkRVMU9EZz0=",
    "seed": "2019-04-25T18:17:23-04:00"
    },
    "internalReference": "1468647381"
}

Permite revertir un pago aprobado con el código de referencia interna.

PARÁMETROS

Name Type Description
internalReference Requerido int Referencia interna de la transacción a reversar que se encuentra en el listado de transacciones del getRequestInformation (payment).

Retorna
ReverseResponse: Información de estado de la operación.

Collect

Permite realizar cobros sin la intervención del usuario usando medios de pago previamente suscritos.

PARÁMETROS

Name Type Description
payload Requerido CollectRequest Datos del pago, pagador y medio de pago a implementar como se describe en la estructura CollectRequest.

Retorna
RedirectInformation: Información de estado de la operación.

Estructuras de información

Esta sección describe cada una de las estructuras de datos usada por los métodos de web service.

RedirectRequest

Ejemplo de una estructura RedirectRequest para la solicitud de un pago:

    ...
       {
        "locale": "es_CO",
        "buyer": {
            "name": "Prof. General Hoppe",
            "surname": "Kuhic",
            "email": "ejohns@yahoo.com",
            "documentType": "CC",
            "document": "4216523744",
            "mobile": "3006108300",
            "address": {
                "street": "27791 Kyle Vista",
                "city": "Metzton",
                "state": "Antioquia",
                "postalCode": "46366-1132",
                "country": "US",
                "phone": "438-475-0498 x513"
            }
        },
        "payment": {
            "reference": "TEST_20190517_161956",
            "description": "Et alias quia nisi sequi.",
            "amount": {
            "taxes": [
                {
                "kind": "ice",
                "amount": 2.76,
                "base": 23
                },
                {
                "kind": "valueAddedTax",
                "amount": 4.37,
                "base": 23
                }
            ],
            "details": [
                {
                "kind": "shipping",
                "amount": 1.15
                },
                {
                "kind": "tip",
                "amount": 1.15
                },
                {
                "kind": "subtotal",
                "amount": 23
                }
            ],
            "currency": "USD",
            "total": 32.43
            },
            "items": [
            {
                "sku": 62762,
                "name": "Placeat consequuntur.",
                "category": "physical",
                "qty": 1,
                "price": 23,
                "tax": 4.37
            }
            ],
            "recurring_remove": {
            "periodicity": "D",
            "interval": 7,
            "nextPayment": "2019-05-19",
            "maxPeriods": 4,
            "notificationUrl": "https://dnetix.co/ping/recurring_notification"
            },
            "shipping": {
            "name": "Prof. General Hoppe",
            "surname": "Kuhic",
            "email": "ejohns@yahoo.com",
            "documentType": "CC",
            "document": "4216523744",
            "mobile": "3006108300",
            "address": {
                "street": "27791 Kyle Vista",
                "city": "Metzton",
                "state": "Antioquia",
                "postalCode": "46366-1132",
                "country": "US",
                "phone": "438-475-0498 x513"
            }
            },
            "allowPartial": false
        },
        "expiration": "2019-05-18T16:19:56-05:00",
        "ipAddress": "190.85.82.130",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/74.0.3729.131 Safari/537.36",
        "returnUrl": "https://dnetix.co/p2p/client",
        "cancelUrl": "https://dnetix.co",
        "skipResult": false,
        "noBuyerFill": false,
        "captureAddress": false,
        "paymentMethod": null,
        "fields": [
            {
            "keyword": "Redeem Code",
            "value": 226931,
            "displayOn": "payment"
            }
        ],
    ...    

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

ATRIBUTOS

Nombre Tipo Descripción
locale Opcional string Definido con los códigos ISO 631-1 (language) y ISO 3166-1 alpha-2 (2-letras del país). ej. en_US, es_CO
payer Opcional Person Información del ordenante, si establece este objeto, los datos del pagador utilizarán esta información.
buyer Opcional Person Información del comprador en la transacción.
payment Opcional PaymentRequest Objeto de pago cuando necesite solicitar un cobro.
subscription Opcional SubscriptionRequest Objeto de suscripción utilizado cuando se necesita un token.
fields Opcional NameValuePair[] Información adicional relacionada con la solicitud que el comercio requiere para guardar con la transacción.
paymentMethod Opcional string Forzar el medio de pago en la interfaz de redirección, los códigos aceptados son los de la lista. Si necesita más de uno separarlos con coma. ej. ATH,PSE,CR_VS
expiration Requerido dateTime Fecha de expiración de una solicitud, el usuario debe terminar el proceso antes de esta fecha. i.e. 2019-03-05T00:00:00-05:00.
returnUrl Requerido string URL de retorno es utilizada para redirigir al usuario una vez termina la operación de pago.
cancelUrl string URL para retornar cuando el cliente aborte la operación.
ipAddress Requerido string Dirección IP del usuario.
userAgent Requerido string Agente de usuario informado por el usuario.
skipResult Opcional bool Si se envía el parámetro como true se omite la pantalla del resultado en redirección y una vez aprobado el pago regresa al comercio automaticamente.
noBuyerFill Opcional bool Por defecto se llenan los datos que se piden en redirección con los del comprador (buyer) enviados, si se envía como true se omite este autocompletado automático.

Retorna: RedirectResponse

RedirectResponse

Ejemplo de una estructura RedirectResponse con respuesta aprobada en una solicitud de pago con autenticación:

{
    "status": {
        "status": "OK",
        "reason": "PC",
        "message": "La petición se ha procesado correctamente",
        "date": "2019-03-04T16:50:02-05:00"
    },
    "requestId": 181348,
    "processUrl": "https://test.placetopay.com/redirection/session/181348/43d83d36aa46de5f993aafb9b3e0be48"
}

Estructura que contiene la respuesta inicial desde el método createRequest.

ATRIBUTOS

Parámetro Tipo Descripción
status Requerido Status Estructura que contiene el estado de la solicitud de pago.
requestId Opcional Int Referencia única de la sesión de pago.
processUrl Opcional String URL donde se redirecciona al usuario para completar el proceso de pago.

RedirectInformation

Estructura de respuesta a una solicitud para una información de transacción.

ATRIBUTOS

Nombre Tipo Descripción
status Requerido Status Estado de esta solicitud, debe observar el estado interno de cada objeto.
request Opcional RedirectRequest Información con la solicitud original.
payment Opcional Transaction[] Información relacionada con el pago si este fue solicitado.
subscription Opcional SubscriptionResponse Información relacionado con la suscripción si esta fue solicitada.

ReverseResponse

Estructura de respuesta a una solicitud de pago reversado.

ATRIBUTOS

Nombre Tipo Descripción
status Requerido Status Estado de la solicitud será APROBADO si se ha realizado el reverso de lo contrario puede ser RECHAZADA.
payment Opcional Transaction Si el reverso fue exitoso, se almacena como una nueva transacción.

Person

Estructura que refleja la información de una persona involucrada en una transacción.

ATRIBUTOS

Parámetro Tipo Descripción
documentType Opcional DocumentType Tipo de identificación del usuario pagador.
document String Identificación.
name Requerido String Nombres de la persona.
surname Opcional String Apellidos de la persona.
company Opcional String Nombre de la empresa en la que trabaja o representa.
email Requerido String Correo electrónico de la persona.
address Opcional Address Información completa de la dirección.
mobile Opcional PhoneNumberType Número celular, el PhoneNumberType restringe la longitud del número de teléfono de la cadena a 30 caracteres.

PaymentRequest

Ejemplo de una estructura payment para la solicitud de un pago:

   ...
    "payment": {
            "reference": "TEST_20190517_135449",
            "description": "Et est suscipit fugit possimus.",
            "amount": {
            "taxes": [
                {
                "kind": "ice",
                "amount": 1.56,
                "base": 13
                },
                {
                "kind": "valueAddedTax",
                "amount": 2.47,
                "base": 13
                }
            ],
            "details": [
                {
                "kind": "shipping",
                "amount": 0.65
                },
                {
                "kind": "tip",
                "amount": 0.65
                },
                {
                "kind": "subtotal",
                "amount": 13
                }
            ],
            "currency": "USD",
            "total": 18.33
            },
            "items": [
            {
                "sku": 73131,
                "name": "Veniam quia.",
                "category": "physical",
                "qty": 1,
                "price": 13,
                "tax": 2.47
            }
            ],
            "recurring_remove": {
            "periodicity": "D",
            "interval": 7,
            "nextPayment": "2019-05-19",
            "maxPeriods": 4,
            "notificationUrl": "https://dnetix.co/ping/recurring_notification"
            },
            "shipping": {
            "name": "Miss Fanny Jacobson",
            "surname": "Turcotte",
            "email": "lisandro69@yahoo.com",
            "documentType": "CC",
            "document": "8792527177",
            "mobile": "3006108300",
            "address": {
                "street": "44669 Lowe Lakes Apt. 468",
                "city": "Port Emileview",
                "state": "Antioquia",
                "postalCode": "00555",
                "country": "US",
                "phone": "1-868-319-9048"
            }
            },
            "allowPartial": false
        },
        "expiration": "2019-05-18T13:54:49-05:00",
        "ipAddress": "190.85.82.130",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 
                      (KHTML, like Gecko) Chrome/74.0.3729.131 Safari/537.36",
        "returnUrl": "https://dnetix.co/p2p/client",
        "cancelUrl": "https://dnetix.co",
        "skipResult": false,
        "noBuyerFill": false,
        "captureAddress": false,
        "paymentMethod": null,
        "fields": [
            {
            "keyword": "Redeem Code",
            "value": 754100,
            "displayOn": "payment"
            }
        ],
    ...

Estructura que contiene la información acerca del pago de la transacción requerida al servicio web.

ATRIBUTOS

Nombre Tipo Descripción
reference Requerido string(32) Única referencia para la solicitud de pago.
description Opcional string Descripción de la cuenta.
amount Requerido Amount Objeto que contiene el monto a ser cobrado.
allowPartial Requerido bool Define si el monto a ser cobrado puede ser parcial.
shipping Opcional Person Información de la persona quien recibe el producto o servicio en la transacción.
items Opcional Items Productos relacionados con esta solicitud de pago.
fields Opcional NameValuePair[] Información adicional relacionada con la solicitud de pago que el comercio requiere guardar con la transacción.
recurring Opcional Recurring Información recurrente cuando PlacetoPay procesa un pago recurrente.
subscribe Opcional bool Permite solicitar un proceso de cobro y suscripción en la misma sesión.

SubscriptionRequest

Estructura que contiene la información relacionada con una solicitud de suscripción para obtener un Token.

ATRIBUTOS

Nombre Tipo Descripción
reference Requerido string Referencia única para la solicitud de suscripción
description Opcional string Descripción de la suscripción.
fields Opcional NameValuePair[] Información adicional relacionada con la suscripción.

Retorna: SubscriptionResponse

SubscriptionResponse

Ejemplo que contiene la estructura SubscriptionResponse:

  {
     ...
        "subscription": {
                "type": "token",
                "status": {
                    "status": "OK",
                    "reason": "00",
                    "message": "Token generado exitosamente",
                    "date": "2019-03-08T10:31:54-05:00"
                },
                "instrument": [
                    {
                        "keyword": "token",
                        "value": "1b394089c97bc5f155b684c068806d858d9e4180c8643b5b29cf216c4b656d3e",
                        "displayOn": "none"
                    },
     ...               
 }

Estructura que contiene información para el método de pago suscripción.

ATRIBUTOS

Parámetro Tipo Descripción
status Requerido Status Estado de la suscripción.
type Opcional String Esta cadena dicta el tipo de suscripción que se devuelve, puede ser [token, cuenta]
instrument Opcional NameValuePair[] Acorde con el tipo de suscripción los valore retornados puede cambiar y serán devueltos en la estructura de NameValuePair.
token:[token, subtoken, franchise,
franchiseName, lastDigits,
validUntil]

account: [bankCode, bankName, accountType,
accountNumber]

NameValuePair

Ejemplo que contiene la estructura namevaluepair:

     ...
            "processorFields": [
                {
                    "keyword": "merchantCode",
                    "value": "011271442",
                    "displayOn": "none"
                },
                {
                    "keyword": "terminalNumber",
                    "value": "00057742",
                    "displayOn": "none"
                },
                {
                    "keyword": "lastDigits",
                    "value": "1111",
                    "displayOn": "none"
                },
                {
                    "keyword": "id",
                    "value": "42337fd0ed2b037667ccabce3427f042",
                    "displayOn": "none"
                },
                {
                    "keyword": "bin",
                    "value": "411111",
                    "displayOn": "none"
                },
                {
                    "keyword": "installments",
                    "value": "1",
                    "displayOn": "none"
                },
                {
                    "keyword": "expiration",
                    "value": "0320",
                    "displayOn": "none"
                },
                {
                    "keyword": "cardType",
                    "value": "C",
                    "displayOn": "none"
                }
            ]
    ...       

Se utiliza para definir un tipo de par clave-valor

ATRIBUTOS

Nombre Tipo Descripción
keyword Opcional string Clave para el par de valores del dato.
value Opcional string Valor para el par de datos.
displayOn Opcional string Bajo qué circunstancias el campo debe ser mostrado en la interfaz de redirección. [none, payment, receipt, both, approved]

Status

Ejemplo de una estructura status con respuesta fallida en una petición de autenticación:

{
    "status": {
        "status": "FAILED",
        "reason": 401,
        "message": "Authentication Failed 103",
        "date": "2019-03-05T10:22:11-05:00"
    }
}

Estructura que contiene la información de la respuesta sobre una solicitud o pago, e informa el estado actual de la misma.

ATRIBUTOS

Parámetro Tipo Descripción
status Requerido String(32) Estado de una petición o pago
reason Requerido String Código del motivo proporcionado.
message Requerido String Descripción del código de razón.
date Requerido DateTime Fecha y hora en que se genera el estado de pago.

Estado de una petición o pago

Ejemplo de un estado de una petición o pago:

{
    "status": {
        "status": "REJECTED",
        "message": "",
        "reason": "",
        "date": "2016-09-15T13:49:01-05:00"
    },
    "requestId": 58,
    "reference": "ORDER-1000",
    "signature": "feb3e7cc76939c346f9640573a208662f30704ab"
}
Estado Descripción
OK Petición de autenticación procesada correctamente.
FAILED Fallo en una petición de autenticación.
APPROVED Petición de pago o suscripción terminada
APPROVED_PARTIAL Si se permite parcialmente, se ha aprobado una transacción, pero aún queda un monto.
PARTIAL_EXPIRED Cuando hay un pago parcial aprobado, pero la sesión ha caducado.
REJECTED Se ha declinado la transacción.
PENDING Transacción pendiente para la sesión, debe estar bloqueada hasta la resolución.
PENDING_VALIDATION La sesión está pendiente de validación de identidad del usuario.
REFUNDED Reintegro de una transacción por solicitud de un tarjetahabiente al comercio.

Transaction

Estructura que contiene información sobre el proceso de pago de la transacción en PlacetoPay.

ATRIBUTOS

Nombre Tipo Descripción
status Requerido Status Estado de la transacción.
internalReference Opcional int Referencia interna en PlacetoPay.
reference Opcional string Referencia enviada por el comercio para la transacción.
paymentMethod Opcional string Código del método de pago utilizado.
paymentMethodName Opcional string Nombre del método de pago utilizado.
issuerName Opcional string Nombre del emisor o del procesador.
amount Opcional AmountConversion Valor procesado.
receipt Opcional string Numero de recibo de la transacción.
franchise Opcional string Franquicia de la tarjeta utilizada.
refunded Opcional boolean
authorization Opcional string Código de autorización.
processorFields Opcional NameValuePair[] Campos adicionales del procesador.

Token

Estructura que contiene información acerca de un token usado para cobros de un cliente suscrito.

ATRIBUTOS

Nombre Tipo Descripción
status Requerido Status Estado del proceso de tokenización.
token Opcional string Token completo para tarjeta de crédito, debe ser usada para solicitar cualquier transacción a PlacetoPay.
subtoken Opcional string Representación numérica del token para casos donde es requerido un número adicional que parece como una tarjeta de crédito, los últimos 4 dígitos son iguales a los últimos 4 dígitos de la tarjeta de crédito.
franchiseName Opcional string Franquicia de la tarjeta tokenizada.
issuerName Opcional string Nombre del banco emisor.
lastDigits Opcional string Últimos 4 dígitos de la tarjeta de crédito.
validUntil Opcional date Fecha hasta la cual el token es válido, puede ser determinada por la fecha de expiración.

DocumentType

Contiene los diferentes tipos de documento, cadena (string) (ver listado)

Address

Estructura que contiene la información sobre una dirección física.

ATRIBUTOS

Nombre Tipo Descripción
street Requerido string Dirección física completa.
city Requerido string Nombre de la ciudad.
state Opcional string Nombre del estado coincidente con la dirección.
postalCode Opcional string Código postal o equivalente se requiere generalmente para los países que tienen.
country Opcional string Código internacional del país que se aplica a la dirección física según ISO 3166-1 ALPHA-2.
phone Opcional PhoneNumberType Número telefónico.

PhoneNumberType

Restringe la longitud del número de teléfono de la cadena a 30 caracteres.

Amount

Ejemplo de una estructura amount para un pago:

{
  ...
         "amount": {
           "taxes": [
                {
                "kind": "ice",
                "amount": 1.56,
                "base": 13
                },
                {
                "kind": "valueAddedTax",
                "amount": 2.47,
                "base": 13
                }
            ],
            "details": [
                {
                "kind": "shipping",
                "amount": 0.65
                },
                {
                "kind": "tip",
                "amount": 0.65
                },
                {
                "kind": "subtotal",
                "amount": 13
                }
            ],
            "currency": "COP",
            "total": "10000"
        }
  ...     
}

Extiende de AmountBase y describe el contenido del valor total, incluyendo impuestos y detalles.

ATRIBUTOS

Parámetro Tipo Descripción
currency Requerido String De amountBase. Permite identificar la moneda en que se va realizar un pago, acorde al ISO 4217 (Alphabetic).
total Requerido Decimal De amountBase. Permite identificar el monto total que se va a pagar.
taxes Opcional TaxDetail[] Descripción de los impuestos.
details Opcional AmountDetail[] Descripción del importe total.

TaxDetail

Estructura para almacenar información sobre un impuesto.

Nombre Tipo Descripción
kind Requerido string Valor de clasificación, puede ser [valueAddedTax, exciseDuty].
amount Requerido AmountType Valor discriminado.

AmountDetail

Estructura para almacenar información sobre el valor.

ATRIBUTOS

Nombre Tipo Descripción
kind Requerido string Valor de clasificación, puede ser [discount, additional,
vatDevolutionBase, shipping,
handlingFee, insurance,
giftWrap, subtotal, fee, tip]
.
amount Requerido AmountType Valor discriminado.

AmountType

Representación decimal del valor.

Recurring

Estructura que contiene la información requerida para una solicitud de pago recurrente.

ATRIBUTOS

Nombre Tipo Descripción
periodicity Requerido string Periodicidad de la factura [D, M, Y]
interval Requerido int Intervalo asociado a la periodicidad.
nextPayment Requerido date Fecha del próximo pago.
maxPeriods Requerido int Número máximo de periodo (-1 en caso de que no haya restricción.)
dueDate Opcional date Fecha para finalizar el pago.
notificationUrl Opcional string URL en el que el servicio notificará cada vez que se haga un pago recurrente.

AmountConversion

Estructura para definir el factor de conversión y los valores.

ATRIBUTOS

Nombre Tipo Descripción
from Requerido AmountBase Monto solicitado.
to Requerido AmountBase Monto procesado por la entidad.
factor Requerido double Factor de conversión.

AmountBase

Estructura que representa una cantidad que define la moneda y el total.

ATRIBUTOS

Nombre Tipo Descripción
currency Requerido string Moneda acorde al ISO 4217 (alphabetic code).
total Requerido decimal Valor total.

CollectRequest

Ejemplo para recaudar un pago utilizando la estructura CollecRequest

POST /api/collect
{
    "auth": {
        "login": "usuarioprueba",
        "tranKey": "YhmdBEZKTMAFsxkI1SrgS4SdBfE=",
        "nonce": "TlRoaE0yWTROMk0wWVRFellXUTVNVFUwWVRZNVpHRXpZbU16TWpJM01UWT0=",
        "seed": "2019-04-25T18:17:23-04:00"
  },
    "instrument": {
        "token": {
            "token": "1b394089c97bc5f155b684c068806d858d9e4180c8643b5b29cf216c4b656d3e"
        }
    },
    "payer": {
            "document": "911111111",
            "documentType": "CC",
            "name": "Prueba aliado",
            "surname": "JA",
            "email": "juan.jimenez@placetopay.com"
    },
    "payment": {
        "reference": "3110",
        "description": "Pago con suscripción 3110",
        "amount": {
            "currency": "COP",
            "total":10000
        }
    }
}

Permite realizar cobros sin la intervención del usuario usando medios de pago previamente suscritos.

ATRIBUTOS

Parámetro Tipo Descripción
payer Requerido Person Datos del titular del medio de pago almacenado.
payment Requerido PaymentRequest Objeto de pago cuando necesite solicitar un cobro.
instrument Requerido Instrument Datos asociados al medio de pago suscrito.

Items

Posee una colección de estructuras de elementos.

ATRIBUTOS

Nombre Tipo Descripción
item Opcional Item[] Arreglo de un elemento incluido.

Item

Estructura que contiene los detalles del elemento.

ATRIBUTOS

Nombre Tipo Descripción
sku Requerido string Unidad en stock correspondiente (SKU) al artículo.
name Opcional string Nombre del artículo.
category Opcional string Puede ser [digital, physical].
qty Opcional string Número de un artículo en particular.
price Opcional decimal Costo del artículo.
tax Opcional decimal Impuesto del artículo.

Instrument

Ejemplo que contiene una estructura instrument:

   {
     ...
        "instrument": {
           "token": {
               "token": "1b394089c97bc5f155b684c068806d858d9e4180c8643b5b29cf216c4b656d3e"
            }
       },
     ...               
    }

Estructura que contiene los detalles de un medio de pago suscrito.

ATRIBUTO

Nombre Tipo Descripción
token Requerido SimpleToken Datos asociados a una tarjeta de crédito tokenizada.

SimpleToken

Estructura que contiene los detalles de un token previamente obtenido mediante un proceso de suscripción, se debe enviar el token o el subtoken en los casos que se habilite, no es necesario enviar ambos.

ATRIBUTOS

Nombre Tipo Descripción
token Opcional string Token completo para tarjeta de crédito, debe ser usada para solicitar cualquier transacción a PlacetoPay.
subtoken Opcional string Representación numérica del Token para casos donde es requerido un número adicional que parece como una tarjeta de crédito, los últimos 4 dígitos son iguales a los últimos 4 dígitos de la tarjeta de crédito.
installments Opcional int Número de cuotas en las cuales se solicita el cobro (opcional).
cvv Opcional string Dígitos del código de seguridad de la tarjeta a usar en los casos en los que sea necesario, generalmente se deja en blanco si se tiene una terminal sin validación de CVV.

Pagos

Ejemplo para la petición de un pago:

POST /api/session

{
  "auth": {
    "login": "usuarioprueba",
    "tranKey": "jsHJzM3+XG754wXh+aBvi70D9/4=",
    "nonce": "TTJSa05UVmtNR000TlRrM1pqQTRNV1EREprWkRVMU9EZz0=",
    "seed": "2019-04-25T18:17:23-04:00"
  },

    "payment": {
        "reference": "3210",
        "description": "Pago de prueba 04032019",
        "amount": {
            "currency": "COP",
            "total": "10000"
        }
      },

    "expiration": "2019-03-05T00:00:00-05:00",
    "returnUrl": "https://mysite.com/response/3210",
    "ipAddress": "127.0.0.1",
    "userAgent": "PlacetoPay Sandbox"
}

Cuando el usuario selecciona pagar en tu sitio, inicia el flujo del servicio Web Checkout, donde su sitio envía al EndPoint de procesamiento mediante el método POST los parámetros necesarios para crear la sesión de pago.

En la estructura se deben tener en cuenta algunos parámetros para consumir el método CreateRequest los cuales están contenidos en la estructura de Autenticación y la estructura RedirectRequest.

Ejemplo de una estructura payment para un pago:

{
...
    "payment": {
        "reference": "3210",
        "description": "Pago de prueba 04032019",
        "amount": {
            "currency": "COP",
            "total": "10000"
        }
      },
...
}

Ejemplo de una estructura amount para un pago:

{
  ...
        "amount": {
            "currency": "COP",
            "total": "10000"
        }
  ...     
}

Pago mixto

Ejemplo de una petición para un pago mixto.

POST /api/session

{
  "auth": {
    "login": "usuarioprueba",
    "tranKey": "jsHJzM3+XG754wXh+aBvi70D9/4=",
    "nonce": "TTJSa05UVmtNR000TlRrM1pqQTRNV1EREprWkRVMU9EZz0=",
    "seed": "2019-04-25T18:17:23-04:00"
  },

   "payment": {
        "reference": "3210",
        "description": "Pago mixto de prueba",
        "amount": {
            "currency": "COP",
            "total": "10000"
        },
        "allowPartial": true
    },

    "expiration": "2019-03-05T00:00:00-05:00",
    "returnUrl": "https://mysite.com/response/3210",
    "ipAddress": "127.0.0.1",
    "userAgent": "PlacetoPay Sandbox"
}

Ejemplo aprobación de una transacción para un pago mixto:

{
    ...
    "status": {
        "status": "APPROVED",
        "reason": "P0",
        "message": "La petición está parcialmente aprobada",
        "date": "2019-04-01T11:13:27-05:00"
    },
    ...
}

Ejemplo aprobación parcial de una transacción para un pago mixto:

{
    ...
    "status": {
        "status": "APPROVED_PARTIAL",
        "reason": "P0",
        "message": "La petición está parcialmente aprobada",
        "date": "2019-04-01T11:13:27-05:00"
    },
    ...
}

Ejemplo de un pago mixto con saldo pendiente y el tiempo de expiración finalizado:

{
    ...
    "status": {
        "status": "PARTIAL_EXPIRED",
        "reason": "PX",
        "message": "La petición está expirada o cancelada y se han realizado pagos",
        "date": "2019-04-01T11:15:38-05:00"
    },
    ...
}

El pago mixto permite utilizar varios medios de pago al momento de pagar para una misma sesión.

Para hacer uso de esta funcionalidad, en la estructura payment del Pago es necesario enviar el atributo allowPartial como: TRUE.

Estados adicionales de una sesión de pago mixto

Al obtener el resultado de la operación, debe tener muy presente los siguiente dos estados:

Pago Recurrente

Ejemplo petición para un pago recurrente:

POST /api/session

{
  "auth": {
    "login": "usuarioprueba",
    "tranKey": "jsHJzM3+XG754wXh+aBvi70D9/4=",
    "nonce": "TTJSa05UVmtNR000TlRrM1pqQTRNV1EREprWkRVMU9EZz0=",
    "seed": "2019-04-25T18:17:23-04:00"
    },
    "payment": {
        "reference": "3210",
        "description": "Pago recurrente de prueba",
        "amount": {
            "currency": "COP",
            "total": "10000"
        },
        "recurring": {
            "periodicity": "M",
            "interval": "1",
            "nextPayment": "2019-04-04",
            "maxPeriods": "12"
        }
    },
    "expiration": "2019-03-05T00:00:00-05:00",
    "returnUrl": "https://mysite.com/response/3210",
    "ipAddress": "127.0.0.1",
    "userAgent": "PlacetoPay Sandbox"
}

Es un cobro periódico realizado por PlacetoPay para un mismo valor con un intervalo (diario, mensual, anual) según la indicación dada en la petición.

Para hacer uso de esta funcionalidad, en la estructura payment del Pago recurrente es necesario enviar en el objeto recurring los datos obligatorios para esta estructura, los cuales puede visualizar en la sesión de Campos usados por tipo de operación.

Suscripción

Ejemplo petición para una suscripción:

{
   "auth":| {
    "login": "usuarioprueba",
    "tranKey": "jsHJzM3+XG754wXh+aBvi70D9/4=",
    "nonce": "TTJSa05UVmtNR000TlRrM1pqQTRNV1EREprWkRVMU9EZz0=",
    "seed": "2019-04-25T18:17:23-04:00"
    },
    "subscription": {
        "reference": "3110",
        "description": "Una suscripción de prueba"
    },
    "expiration": "2019-08-02T00:00:00-05:00",
    "returnUrl": "https://mysite.com/response/3210",
    "ipAddress": "127.0.0.1",
    "userAgent": "PlacetoPay Sandbox"
}

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

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

Estructura que se utilizan para el método de pago con suscripción.

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. Ver Ejemplo de respuesta de una suscripción.

Recaudar usando suscripción

Ejemplo para recaudar un pago con suscripción

POST /api/collect
{
    "auth": {
        "login": "usuarioprueba",
        "tranKey": "YhmdBEZKTMAFsxkI1SrgS4SdBfE=",
        "nonce": "TlRoaE0yWTROMk0wWVRFellXUTVNVFUwWVRZNVpHRXpZbU16TWpJM01UWT0=",
        "seed": "2019-04-25T18:17:23-04:00"
  },
    "instrument": {
        "token": {
            "token": "1b394089c97bc5f155b684c068806d858d9e4180c8643b5b29cf216c4b656d3e"
        }
    },
    "payer": {
            "document": "911111111",
            "documentType": "CC",
            "name": "Prueba aliado",
            "surname": "JA",
            "email": "juan.jimenez@placetopay.com"
    },
    "payment": {
        "reference": "3110",
        "description": "Pago con suscripción 3110",
        "amount": {
            "currency": "COP",
            "total":10000
        }
    }
}

Para realizar el cobro de una suscripción es necesario usar el método Collet enviando el token obtenido en ésta.

Importante: Este proceso no necesita la intervención del usuario.

Pago recurrente vs Suscripción

Las principales diferencias entre estas dos funcionalidades son:

Notificación

Ejemplo de notificación para el estado de una sesión:

{
    "status": {
        "status": "APPROVED",
        "message": "",
        "reason": "",
        "date": "2016-09-15T13:49:01-05:00"
    },
    "requestId": 58,
    "reference": "ORDER-1000",
    "signature": "feb3e7cc76939c346f9640573a208662f30704ab"
}

Una notificación permite informar al comercio sobre el estado de las sesiones.

Configura en tu servidor una URL de notificación usando los puertos 80 o 443 y en caso de que la sesión se cancele o apruebe, reciba una notificación mediante POST.

Parametro Tipo Descripción
requestId Requerido Int Identificador único de la sesión.
reference Requerido String Reeferencia que acompañada con el requestId permite identificar la sesión de pago afectada.
signature Requerido String Firma que permite validar la petición recibida.

De manera asincrónica, una notificación del estado de la petición será enviada a una URL definida por configuración del comercio en PlacetoPay.

Al recibir la notificación su sitio debe:

Identificar operación:
Con el identificador de la sesión requestId y la referencia reference identifican la sesión notificada. Para esta sesión debe validar que el estado de la operación notificada están pendientes en su sistema.

Validar autenticidad de la notificación:
Puedes validar que se trate de una respuesta de PlacetoPay haciendo un SHA-1 con los datos requestId + status + date + secretKey.

Si este valor coincide con el valor proporcionado por el signature, puedes autenticar la respuesta y proceder a asentar en la base de datos.

Consulta

Ejemplo de la petición de consulta de la información de una transacción:

POST /api/session/181348

{
  "auth": {
    "login": "usuarioprueba",
    "tranKey": "NBV2D/QzFUMQi3G/bvkie/HMjdM=",
    "nonce": "WXpVME1tTXlNR1l3TVRJM01XUTJNREJqWlRGaU9Ua3hPVE0wT1dReU9EQT0=",
    "seed": "2019-04-25T18:17:23-04:00"
  }
}

Ejemplo respuesta consulta de un pago:

{
    "requestId": 181348,
    "status": {
        "status": "APPROVED",
        "reason": "00",
        "message": "La petición ha sido aprobada exitosamente",
        "date": "2019-03-04T17:27:59-05:00"
    },
    "request": {
        "locale": "es_CO",
        "payer": {
            "document": "98762729",
            "documentType": "CE",
            "name": "JD",
            "surname": "JA",
            "email": "juan.jimenez@placetopay.com",
            "mobile": "321000000"
        },
        "payment": {
            "reference": "3210",
            "description": "Pago de prueba 04/03/2019",
            "amount": {
                "currency": "COP",
                "total": "10000"
            },
            "allowPartial": false,
            "subscribe": false
        },
        "fields": [
            {
                "keyword": "_processUrl_",
                "value": "https://test.placetopay.com/redirection/session/181348/43d83d36aa46de5f993aafb9b3e0be48",
                "displayOn": "none"
            }
        ],
        "returnUrl": "https://mysite.com/response/3210",
        "ipAddress": "127.0.0.1",
        "userAgent": "PlacetoPay Sandbox",
        "expiration": "2019-03-05T00:00:00-05:00"
    },
    "payment": [
        {
            "status": {
                "status": "APPROVED",
                "reason": "00",
                "message": "Aprobada",
                "date": "2019-03-04T17:05:00-05:00"
            },
            "internalReference": 1468647381,
            "paymentMethod": "card",
            "paymentMethodName": "Visa",
            "issuerName": "BANCO DE PRUEBAS",
            "amount": {
                "from": {
                    "currency": "COP",
                    "total": "10000.00"
                },
                "to": {
                    "currency": "COP",
                    "total": "9800.00"
                },
                "factor": 1
            },
            "authorization": "000000",
            "reference": "3210",
            "receipt": "1551737100",
            "franchise": "CR_VS",
            "refunded": false,
            "discount": {
                "code": "DEMO_PROMOVISA",
                "type": "MERCHANT",
                "amount": "200",
                "base": "10000",
                "percent": 2
            },
            "processorFields": [
                {
                    "keyword": "merchantCode",
                    "value": "011271442",
                    "displayOn": "none"
                },
                {
                    "keyword": "terminalNumber",
                    "value": "00057742",
                    "displayOn": "none"
                },
                {
                    "keyword": "lastDigits",
                    "value": "1111",
                    "displayOn": "none"
                },
                {
                    "keyword": "id",
                    "value": "42337fd0ed2b037667ccabce3427f042",
                    "displayOn": "none"
                },
                {
                    "keyword": "bin",
                    "value": "411111",
                    "displayOn": "none"
                },
                {
                    "keyword": "installments",
                    "value": "1",
                    "displayOn": "none"
                },
                {
                    "keyword": "expiration",
                    "value": "0320",
                    "displayOn": "none"
                },
                {
                    "keyword": "cardType",
                    "value": "C",
                    "displayOn": "none"
                }
            ]
        }
    ],
    "subscription": null
}

Ejemplo de respuesta de una suscripción:

{
    "requestId": 183064,
    "status": {
        "status": "APPROVED",
        "reason": "00",
        "message": "La petición ha sido aprobada exitosamente",
        "date": "2019-03-08T10:33:09-05:00"
    },
    "request": {
        "locale": "es_CO",
        "payer": {
            "document": "911111111",
            "documentType": "CC",
            "name": "Prueba aliado",
            "surname": "JA",
            "email": "juan.jimenez@placetopay.com",
            "mobile": "321000000"
        },
        "subscription": {
            "reference": "3110",
            "description": "Una suscripción de prueba"
        },
        "returnUrl": "https://mysite.com/response/3110",
        "ipAddress": "127.0.0.1",
        "userAgent": "PlacetoPay Sandbox",
        "expiration": "2019-04-09T00:00:00-05:00"
    },
    "payment": null,
    "subscription": {
        "type": "token",
        "status": {
            "status": "OK",
            "reason": "00",
            "message": "Token generado exitosamente",
            "date": "2019-03-08T10:31:54-05:00"
        },
        "instrument": [
            {
                "keyword": "token",
                "value": "1b394089c97bc5f155b684c068806d858d9e4180c8643b5b29cf216c4b656d3e",
                "displayOn": "none"
            },
            {
                "keyword": "subtoken",
                "value": "2364106985941111",
                "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": "2021-03-31",
                "displayOn": "none"
            },
            {
                "keyword": "installments",
                "value": "1",
                "displayOn": "none"
            }
        ]
    }
}

La consulta de información de una transacción se puede dar cuando el usuario es retornado a su sitio ó mediante una tarea programada que diariamente ejecute un script en el cual se consulten todas las operaciones pendientes en su sitio.

Recomendación: Implementar en su sitio las dos alternativas, pues si algo falla en el proceso de retorno y notificación, la tarea programada puede ser usada como contingencia.

Para consultar la sesión debe enviar el identificador único de la sesión de pago requesId usando el método GetRequestInformation.

La respuesta de la transacción debe contener diferentes objetos:

Datos de la transacción:

Parámetro Tipo Descripción
internalReference Opcional Int Referencia interna en PlacetoPay.
paymentMethod Opcional String Código del método de pago utilizado.
paymentMethodName Opcional String Nombre del método de pago utilizado.
issuerName Opcional String Nombre del emisor o del procesador.

Información adicional

Campos usados por tipo de operación

Matriz con los campos disponibles para enviar por operación. Las convenciones son: R (requerida), O (opcional), A (recomendada), - (no aplica), R* (Es requerido, se debe enviar uno de ellos)

Payment Subscription Payment Partial Reverse Payment Recurrent payment Invalidate token Collect
locale O O O - O - O
payer O O O - O - R
documentType O O O - O - R
document O O O - O - R
name O O O - O - R
surname O O O - O - R
company O O O - O - O
email O O O - O - R
address O O O - O - A
mobile O O O - O - A
buyer A A A - A - O
documentType O O O - O - O
document O O O - O - O
name A A A - A - O
surname O O O - O - O
company O O O - O - O
email A A A - A - O
address O O O - O - O
mobile O O O - O - O
payment R - R - R - R
reference R - R - R - R
description R - R - R - R
amount R - R - R - R
currency R - R - R - R
total R - R - R - R
taxes O - O - O - O
details O - O - O - O
allowPartial - - R - - - -
shipping O - O - O - O
documentType O - O - O - O
document O - O - O - O
name O - O - O - O
surname O - O - O - O
company O - O - O - O
email O - O - O - O
address O - O - O - O
mobile O - O - O - O
items O - O - O - O
fields O - O - O - O
recurring - - - - R - O
periodicity - - - - R - O
interval - - - - R - O
nextPayment - - - - R - O
maxPeriods - - - - R - O
dueDate - - - - R - O
notificationUrl - - - - R - O
subscription - R - - - - -
reference - R - - - - -
description - R - - - - -
fields - O - - - - -
fields O O O - O - O
keyword O O O - O - O
value O O O - O - O
displayOn O O O - O - O
paymentMethod O O O - O - -
expiration R R R - R - -
returnUrl R R R - R - -
cancelUrl O O O - O - -
ipAddress R R R - R - -
userAgent R R R - R - -
requestId - - - R - R -
Instrument - - - - - - R
token - - - - - - R
token - - - - - - R*
subtoken - - - - - - R*
instalments - - - - - - O
cvv - - - - - - O

Tarjeta de pruebas

Franchise Card number Comportamiento
Visa 4005580000000040 Rechaza
Visa 4007000000027 Aprueba
Visa 4111111111111111 Aprueba
Visa 4212121212121214 Deja la operación pendiente como modo de captura, la operación debe ser autorizada o cancelada en el panel de Place to Pay o de otra manera por operaciones de VOID o SETTLE.
Visa 4666666666666669 Este toma 5 minutos para autorizar. La idea es simular un tiempo de espera en su autorización. Así que el servicio de consumo fallará por el tiempo, lo que obligará al uso del Webservice para verificar cuando la operación completa su proceso. Tenga en cuenta los tiempos de consumo de Webservice.
Visa 36545407032780 Deja la operación en estado Manual (se debe aprobar o rechazar desde la consola)
MasterCard 5424000000000015 Aprueba
MasterCard Credencial (BCO) 540625 10 00 00 00 08 Aprueba
AmericanExpress 370000000000002 Aprueba
Diners 36018623456787 Aprueba
BBVA Club Campestre 8130010000000000 Aprueba
Visa Electron (Debit card) 4027390000000006 Aprueba
Visa Electron (Debit card) 4215440000000001 Rechaza
Codensa 5907120000000009 Rechaza
Tarjeta RIS 6372000000000007 Rechaza

Métodos de Pago Códigos.

Esta es una lista de las franquicias disponibles en redirección.

País Franquicia Método de pago
Colombia AC_WU ath
AV_AV ath
AV_BB ath
AV_BO ath
AV_BP ath
BBVAC ath
BP_AM amex
BP_DN diners
BP_DS discover
BP_EL elo
BP_MC master
BP_VS visa
CAFAM cafam
CDNSA codensa
CMRFB falabella
CR_AM amex
CR_CR credencial
CR_DN diners
CR_VE visa_electron
CR_VS visa
DBTAC debito
DF_DN diners
DF_DS discover
DF_MC master
DF_VS visa
DISCO discover
DVVND ath
EFCTY efecty
ENPCT cooperativa
GNOFC gana
GNPIN gana
GNRIS ris
ID_DN diners
ID_DS discover
ID_MC master
ID_VS visa
MSTRP masterpass
PBBVA ath
PINVL Pin Valida
PYPAL PayPal
RM_MC master
SOMOS somos
SB_VS visa
SFPAY safetypay
SPGRS supergiros
T1_BC ath
T1_CV ath
TY_AK exito
TY_EX alkosto
VISAC visa_checkout
V_VBV Verified by visa
ATH ath
PPD ppd
PSE pse
Ecuador ID_VS Visa
ID_MC Mastercard
ID_DN Diners
ID_DS Discover

Tipos de documento

Ésta es una lista de los tipos de documentos aceptados por redirección.

País Código Tipo de documento
Internacional PPN Pasaporte
TAX TAX
LIC Labeler Identification Code
Colombia CC Cédula de ciudadanía
CE Cédula de extranjería
TI Tarjeta de identidad
RC Registro Civil
NIT Número de Identificación Tributaria
RUT Registro único tributario
Ecuador CI Cédula de identidad
RUC Registro Único de Contribuyentes
Panamá CIP Cédula de identidad personal
Brazil CPF Cadastro de Pessoas Físicas
USA SSN Social security number

Conexión medios de pago API

Este Webservice y su arquitectura permiten que cualquier aplicativo sin importar el lenguaje de desarrollo, puedan beneficiarse de un conjunto de reglas de negocio y servicios, debido al cumplimiento de estándares SOAP, WSDL y XML.

Para hacer uso de los Webservice, debe contar con un lenguaje de programación que pueda consumirlos, algunos lenguajes tienen mejor soporte que otros desde el punto de vista de facilidad de acceso; sin embargo, si no se cuenta con un lenguaje que encapsule la comunicación, siempre se puede hacer incluso a nivel de sockets usando el protocolo HTTP conjuntamente con la especificación SOAP.

Para aquellos lenguajes que tienen un buen soporte lo más aconsejable es ir a través del WSDL para el Webservice.

La integración directa al medio de pago en general NO es recomendada, pues dificulta otros servicios que pueden estar implementados en la interfaz de Placetopay, al tiempo que hace que cada nuevo medio de pago liberado requiera un nuevo desarrollo por parte del comercio. Así que solo tener en cuenta esta integración si:

¿Qué obligaciones tengo al usar esta integración?

Ten en cuenta que al usar este tipo de integración, se requiere de certificación y los tiempos de implementación pueden ser mucho más altos que cuando se integra por WebCheckOut.

Captura de la información

Al consumir el servicio de creación de la transacción, tu aplicación debe proveer información sobre el pagador, el comprador y la transacción. Si corresponden a la misma persona, solamente deberás especificar la información del pagador

Para proveer estos datos, tu aplicación deberá capturarlos directamente en el proceso o de alguna fuente de información previamente habilitada.

Authentication

Ejemplo generación de fecha en formato ISO 8601:


<?php
$seed = date('c');
?>

using System;
using System.Globalization;

String seed = DateTime.UtcNow.ToString("s",
    System.Globalization.CultureInfo.InvariantCulture);

Ejemplo generación Hash:

<?php
    $hashString = sha1($seed 
    . $tranKey, false);
?>
using System.Text;
using System.Security.Cryptography;

private string GetSHA1(string text)
{
    ASCIIEncoding UE = new ASCIIEncoding();
    byte[] hashValue;
    byte[] message = UE.GetBytes(text);
    SHA1 hashString = new SHA1CryptoServiceProvider();
    string hex = "";
    hashValue = hashString.ComputeHash(message);
    foreach (byte x in hashValue) {
        hex += String.Format("{0:x2}", x);
    }
    return hex;
}

string hashString = GetSHA1(seed
    + tranKey);

Ejemplo de autenticación con la estructura auth:

<?php
        $seed = date('c');
        $secretKey = '024h1IlD';
        $trankey = sha1($seed.$secretKey);

        $servicio = 'https://test.placetopay.com/soap/pse/v11/?wsdl'; //url del servicio

    $auth = array(
        'login' => '6dd490faf9cb87a9862245da41170ff2',
        'tranKey' => $trankey,
        'seed' => $seed,
    );

    $arguments = array(
                        'auth' => $auth
                    );
    $client = new nusoap_client($servicio,array('trace' => true)); // En lugar de SoapClient se utiliza nusoap_client
?>
    POST /api/session
    {
    "auth": 
    {
        "login": "usuarioprueba",
        "tranKey": "T0O+x3gNlQUf0iBxEuenPvBPlWs=",
        "seed": "2019-04-25T18:17:23-04:00",
     }
    }

La autenticación a los servicios web debe ser enviada sobre la estructura auth, compuesto como se muestra a continuación:

ATRIBUTOS

Nombre Tipo Descripción
login string Identificador del sitio.
tranKey string Llave transaccional, para el consumo del API: SHA-1(seed + trankey).
seed string Fecha actual, la cual se genera en formato ISO 8601. El sistema verificará que la petición no haya expirado, por ello es fundamental una sincronización del reloj del servidor
additional Attribute Datos adicionales a la estructura de autenticación.

Webservice efectivo

En esta sesión se describen cada una de los métodos y estructuras que se deben tener presentes para que una transacción por un sitio que integre el medio de pago efectivo se genere adecuadamente.

Flujo de integración efectivo

Ejemplo para integrar un pago en efectivo:

<?php

  class Pagos 
  {

      public function efectivo (){

         $seed = date('c');
         $secretKey = "024h1IlD";
         $trankey = SHA1($seed.$secretKey);

         $servicio="https://test.placetopay.com/soap/cashorder/?wsdl"; //url del servicio

    // CREACION DE LA AUTENTICACION
          $auth = array(
                'login' => '6dd490faf9cb87a9862245da41170ff2',
                'tranKey' => $trankey,
                'seed' => $seed,
            );

           $payer = array(
                        'documentType'=>"CC",
                        'document'=>"1037390240",
                        'firstName'=>"Juan",
                        'lastName'=>"Chavarria",
                        'emailAddress'=>"soporte9@placetopay.com",
                        'city'=>"Bello",
                        'province'=>"Colombia",
                        'country'=>"Antioquia",
                        'mobile'=>"3104317467"
                    );


           $transaction = array(
                        'reference'=>"123",
                        'description'=>"prueba efectivo",
                        'language'=>"ES",
                        'currency'=>"COP",
                        'totalAmount'=>1000,
                        'taxAmount'=>0,
                        'subtotalAmount'=>0,
                        'expiration'=>date('c', strtotime('+1 hour')),
                        'buyer'=>$payer,
                        'ipAddress'=>"192.168.1.12",
                        'notificationURL'=>"http://localhost/API_AIM/Controlador/Respuesta.php"
                    );

            $arguments = array(
                                'auth' => $auth,
                                'order'=>$transaction
                            );
            $client = new nusoap_client($servicio,array('trace' => true));
     // SE CREA LA ORDEN PARA EL PAGO EN EFECTIVO
        $resp = $client->call('addOrder', $arguments);
        var_dump($resp);
    }
  }
?>
  1. El establecimiento invoca el método addOrder para agregar una orden de pago en efectivo.
  2. Si se desea eliminar una orden de pago se puede invocar al método deleteOrder, se debe tener en cuenta que la orden no podrá ser eliminada si ya ha sido pagada.
  3. Eventualmente se puede invocar al método flushOrders que permite purgar las órdenes de pago que ya están vencidas y que no han sido pagadas.
  4. Para obtener el PDF con las instrucciones para pagar la orden de efectivo se debe invocar el método getOrderPDF que retorna un PDF codificado en Base64.
  5. Para consultar el estado de una transacción se puede invocar el método getOrder el cual brinda todos los datos de la orden incluyendo el estado y si está pagada la información de la transacción.

Métodos de interfaz efectivo

A continuación se describen cada una de los métodos de tipo entrada y salida expuestos por el Webservice efectivo, igualmente se muestran los parámetros de entrada a cada operación y vínculos a las estructuras de datos usadas.

addOrder

Ejemplo para agregar una orden para el pago en efectivo dentro de la integración del mismo:


<?php
...
    $transaction = array(
                    'reference'=>"123",
                    'description'=>"prueba efectivo",
                    'language'=>"ES",
                    'currency'=>"COP",
                    'totalAmount'=>1000,
                    'taxAmount'=>0,
                    'subtotalAmount'=>0,
                    'expiration'=>date('c', strtotime('+1 hour')),
                    'buyer'=>$payer,
                    'ipAddress'=>"192.168.1.12",
                    'notificationURL'=>"http://localhost/API_AIM/Controlador/Respuesta.php"
    );

    $arguments = array(
                        'auth' => $auth,
                        'order'=>$transaction
                    );
    $client = new nusoap_client($servicio,array('trace' => true));
    // SE CREA LA ORDEN PARA EL PAGO EN EFECTIVO
    $resp = $client->call('addOrder', $arguments);

    var_dump($resp);
...
?>

Agrega una orden de pago para efectivo.

PARÁMETROS

Nombre Tipo Descripción
auth Authentication datos de autenticación
order CashOrder datos de la orden de pago

Retorna
int. La referencia única de la orden de pago en Placetopay.

getOrder

Obtiene la información de una orden de pago en efectivo para conocer su estado.

PARÁMETROS

Nombre Tipo Descripción
auth Authentication Datos de autenticación.
id int Referencia única de la orden de pago a consultar.

Retorna
CashOrderInfo. Información de la orden, si la orden no existe el estado de la orden será NOT_FOUND, si hay un error al consultar el registro se retornará una excepción SoapFault.

deleteOrder

Elimina una orden de pago en Placetopay que no haya sido pagada.

PARÁMETROS

Nombre | Tipo | Descripción auth | Authentication | Datos de autenticación. id | int | Referencia única de la orden de pago a eliminar.

Retorno
int. Número de registros eliminados, si es un cero indicará que el registro no fue hallado, si hay un error al eliminar el registro se retornará una excepción SoapFault.

flushOrders

Purga todas las órdenes de pago no pagadas que ya han cumplido la fecha de corte en Placetopay.

PARÁMETROS

Nombre Tipo Descripción
auth Authentication Datos de autenticación.

Retorna
int. Número de órdenes de pago eliminadas.

getOrderPDF

Genera el PDF para el pago en efectivo en la red de corresponsales que actualmente se permita. Para la fecha de este documento esta red involucra a corresponsales del grupo AVAL/ATH, Baloto, Efecty, cajas de Almacenes Éxito, Carulla, Surtimax y Súper Inter. Así como cajeros electrónicos del grupo AVAL. Próximamente la red de oficinas de Bancolombia.

PARÁMETROS

Nombre Tipo Descripción
auth Authentication Datos de autenticación.
id int Referencia única de la orden de pago generada.

Retorno
base64Binary. PDF generado codificado como base64, si hay un error al generar el PDF se retornará una excepción SoapFault.

Estructuras de información efectivo

En este apartado se describen cada una de las estructuras de datos usadas por los métodos del Webservice efectivo.

Attribute

Estructura para almacenar información extendida.

ATRIBUTOS

Nombre Tipo Descripción
name string[30] Código para referenciar el atributo.
value string[255] Valor que asume el atributo.

Persona

Ejemplo de generación de una estructura Person dentro de la integración de pago en efectivo:

<?php
...
    $payer = array(
                        'documentType'=>"CC",
                        'document'=>"1037390240",
                        'firstName'=>"Juan",
                        'lastName'=>"Chavarria",
                        'emailAddress'=>"soporte9@placetopay.com",
                        'city'=>"Bello",
                        'province'=>"Colombia",
                        'country'=>"Antioquia",
                        'mobile'=>"3104317467"
                    );
...  
?>                  

Estructura para reflejar la información de una persona involucrada en una orden de pago.

ATRIBUTOS

Nombre Tipo Descripción
document string[12] Número de identificación de la persona.
documentType string[3] Tipo de documento de identificación de la persona.
CC = Cédula de ciudadanía colombiana
CE = Cédula de extranjería
TI = Tarjeta de identidad
PPN = Pasaporte
NIT = Número de identificación tributaria
SSN = Social Security Number
firstName string[60] Nombres
lastName string[60] Apellidos
company string[60] Nombre de la compañía en la cual labora o representa.
emailAddress string[80] Correo electrónico.
address string[100] Dirección postal completa.
city string[50] Nombre de la ciudad coincidente con la dirección.
province string[50] Nombre de la provincia o departamento coincidente con la dirección.
country string[2] Código internacional del país que aplica a la dirección física acorde a ISO 3166-1, mayúscula sostenida.
phone string[30] Número de telefonía fija.
mobile string[30] Número de telefonía móvil o celular.

CashOrder

Ejemplo de generación de una estructura CashOrder dentro de la integración de pago en efectivo:

<?php
...
    $transaction = array(
                    'reference'=>"123",
                    'description'=>"prueba efectivo",
                    'language'=>"ES",
                    'currency'=>"COP",
                    'totalAmount'=>1000,
                    'taxAmount'=>0,
                    'subtotalAmount'=>0,
                    'expiration'=>date('c', strtotime('+1 hour')),
                    'buyer'=>$payer,
                    'ipAddress'=>"192.168.1.12",
                    'notificationURL'=>"http://localhost/API_AIM/Controlador/Respuesta.php"
    );
...
?>

Estructura con la información de una orden de pago en efectivo.

ATRIBUTOS

Nombre Tipo Descripción
reference string[32] Referencia única de pago.
description string[255] Descripción o detalle de la orden de pago.
language string[2] Idioma esperado para las transacciones acorde a ISO 631-1, usar ES.
currency string[3] Código de la moneda acorde a ISO 4217 en la cual está expresado el cobro, usar COP.
totalAmount decimal Valor total a recaudar.
taxAmount decimal Discriminación del impuesto aplicado.
subtotalAmount decimal Valor base antes de impuestos.
expiration datetime Fecha y hora máxima hasta la cual se recibe el pago [AAAA-MM-DDTHH:NN:SS]
buyer Person Información del comprador.
ipAddress string Dirección IP desde la cual realiza la solicitud el pagador.
userAgent string Agente de navegación utilizado por el pagador al hacer la solicitud.
additionalData Attribute[] Datos adicionales para ser almacenados con la transacción.
notificationURL string[255] URL de notificación una vez la transacción es realizada.

Transaction

Estructura con la información de la transacción asociada a la orden de pago.

ATRIBUTOS

Nombre Tipo Descripción
paymentMethod string[5] Código del medio de pago.
paymentMethodName string[128] Nombre del medio de pago.
amount decimal Valor recaudado.
authorization string[40] Número de autorización.
receipt string[40] Número de recibo en la red.

CashOrderInfo

Estructura con la información de una orden de pago en efectivo y la información de la transacción si existe. Hereda todos los atributos de CashOrder y agrega las propiedades que se enuncian a continuación.

ATRIBUTOS

Nombre Tipo Descripción
status string Estado actual de la orden: NOT_FOUND, PENDING, EXPIRED, PAYED, PAYED_PARTIAL, REFUNDED
status_date dateTime Fecha y hora desde la cual se encuentra en el estado.
transaction Transaction Información de la transacción cuando el estado es pagado.

Webservice PSE

A continuación se describen cada uno de los elementos y posibles situaciones que se deben tener presentes para que una transacción por tu sitio con el medio de pago PSE sea exitosa.

Flujo de integración PSE

Ejemplo para integrar un pago con PSE:

<?php
     class Pagos
       {
       public function bancos()
       {
              $seed = date('c');
              $secretKey = '024h1IlD';
              $trankey = sha1($seed.$secretKey);

              $servicio = 'https://test.placetopay.com/soap/pse/v11/?wsdl'; //url del servicio
              //AUTENTICACION
              $auth = array(
              'login' => '6dd490faf9cb87a9862245da41170ff2',
              'tranKey' => $trankey,
              'seed' => $seed,
              );

              $arguments = array(
                     'auth' => $auth,
                     );
              $client = new nusoap_client($servicio, array('trace' => true)); // en lugar de SoapClient  se utiliza nusoap_client
              // LAMADA AL METODO GETBANKLIST DE PSE
              $resp = $client->call('getBankList', $arguments);

              $resp1 = $resp['getBankListResult']['item'];

              echo '<h5>Seleccione su banco </h5><br>
               <select name="banco" id="bank" class="form-control" onchange ="r();">';
              // SE RECORRE EL ARRAY PARA LISTAR BANCOS
              foreach ($resp1 as $key => $valor) {
              echo '<option value="'.$valor['bankCode'].'">'.$valor['bankName'].'</option>';
              }
              echo '</select>';
       }

       public function RealizarPago()
       {
              $seed = date('c');
              $secretKey = '024h1IlD';
              $trankey = sha1($seed.$secretKey);
              //PAGO POR PSE
              if (isset($_POST['banco']) && $_POST['banco'] != '') {
              $banco = $_POST['banco'];
              $servicio = 'https://test.placetopay.com/soap/pse/v11/?wsdl'; //url del servicio

              $auth = array(
              'login' => '6dd490faf9cb87a9862245da41170ff2',
              'tranKey' => $trankey,
              'seed' => $seed,
              );
              $payer = array(
                     'documentType' => $_POST['tipdoc'],
                     'document' => $_POST['cedula'],
                     'firstName' => $_POST['nombre'],
                     'lastName' => $_POST['apellido'],
                     'emailAddress' => $_POST['correo'],
                     'city' => $_POST['ciudad'],
                     'province' => $_POST['pais'],
                     'country' => 'Antioquia',
                     'mobile' => $_POST['telefono'],
                     );

              $transaction = array(
                     'bankCode' => $banco,
                     'bankInterface' => 0,
                     'returnURL' => 'http://localhost/API_AIM/Controlador/RespuestaPSE.php',
                     'reference' => $reference = time(),
                     'description' => 'Pago',
                     'language' => 'ES',
                     'currency' => $_POST['moneda'],
                     'totalAmount' => $_POST['total'],
                     'taxAmount' => 0,
                     'devolutionBase' => 0,
                     'tipAmount' => 0,
                     'payer' => $payer,
                     'ipAddress' => '192.168.1.12',
                     );
              $arguments = array(
                     'auth' => $auth,
                     'transaction' => $transaction,
                     );
              $client = new nusoap_client($servicio, array('trace' => true));
              // SE CREA LA TRANSACCION PARA PAGO POR PSE
              $resp = $client->call('createTransaction', $arguments);

              var_dump($resp);

              $_SESSION['transactionId'] = $resp['createTransactionResult']['transactionID'];
              //REDIRECCION AL PSE
              echo '<script>
              window.location = "'.$resp['createTransactionResult']['bankURL'].'";
       </script>';
       }
    }
 }

?>

¿Cómo funciona la implementación?

  1. Se muestra como opción de pago PSE (Débitos a cuentas de ahorro y corriente en Colombia).
  2. Una vez el usuario la selecciona, se presenta la lista de bancos (debe estar cacheada localmente y su refrescamiento debe ser 1 vez por día) y el tipo de banca a desplegar (personas o empresas).
  3. Al tiempo que el cliente confirma la operación, debe consumirse el servicio para realizar la petición de la transacción.
  4. Si la petición es exitosa se retorna la URL a la cual debe enviarse al cliente para que realice la operación en el banco. En caso contrario se retorna el motivo del rechazo de la transacción.
  5. Almacenar los datos de la transacción retornados por el servicio (identificador de la transacción, autorización/cus, identificador sesión de placetopay).
  6. Redirigir el navegador a la URL retornada en caso de éxito.
  7. Una vez la transacción retorna a la URL especificada en el consumo de crear transacción, se debe preguntar por el estado de la transacción mediante el consumo un servicio.
  8. Dependiendo de la respuesta del servicio, la transacción puede haber sido aprobada, rechazada o seguir pendiente de procesamiento.
  9. Informar al usuario el estado de la transacción.
  10. Si la transacción está pendiente, o si el cliente al abandonar el portal no ha regresado, se debe tener una sonda que pregunte por el estado de la transacción.

Despliegue de bancos disponibles

Una vez el cliente ha determinado que desea pagar con débito a una cuenta corriente o de ahorros, deberá presentarle la lista de los bancos que en el momento están disponibles para la transacción. Esta lista de bancos se obtiene mediante el consumo del método getBankList el cual debe ser consumido una vez por día, lo que exige que se disponga de un mecanismo de caché que permita recuperar la lista de este si ya ha sido consumido el servicio en el día.

Adicional a darle a escoger con qué banco realizar la transacción, el usuario también debe indicar qué tipo de interfaz del banco desea desplegar, es decir, si la de personas o la de empresas.

Si por algún motivo la lista de bancos no pudo ser obtenida, deberá mostrarse un mensaje “No se pudo obtener la lista de Entidades Financieras, por favor intente más tarde” y, consumir nuevamente el servicio de lista de bancos para intentar obtener dicha lista y poderla almacenar en el caché.

Tenga en cuenta que en operaciones de Multicrédito se debe utilizar el código de servicio para multicrédito y que siempre deberá pasar todas las cuentas dependientes (entidad, servicio) para los créditos así algunas de ellas vayan con valores en cero. Es requerido que la lista de créditos corresponda con todos los subcódigos dependientes.

Confirmación y redirección al banco

Una vez se poseen los datos del pagador y/o comprador, así como la información de qué banco y qué tipo de interfaz debe mostrar el banco deberá entonces consumir el servicio de createTransaction para obtener la URL a la cual deberá redirigir al cliente para finalizar la transacción.

Debe tener en cuenta que en los datos solicitados para crear la transacción se requiere la dirección IP desde la cual el cliente está realizando la transacción, así como la información del agente de navegación usado. Si lo desea, también puede proveer datos adicionales con la transacción, los cuales le permitirán tener esta información disponible en la consola de consulta de transacciones de Placetopay.

Si la respuesta del servicio es SUCCESS, entonces deberá almacenar la información retornada en su base de datos, de vital importancia el transactionId pues es con este identificador que podrá consultar el estado final de la transacción.

Tenga en cuenta que una respuesta SUCCESS en este punto sólo implica que la transacción ha sido aprovisionada por el banco y está en espera que el cliente llegue a la interfaz del banco, se autentique y autorice la operación iniciada.

Al crear la transacción, esta puede fallar; algunos motivos incluyen montos por fuera del rango permitido, no disponibilidad del banco, problemas de configuración de la cuenta recaudadora, entre otros. Utilice la propiedad responseReasonText para obtener el mensaje de por qué falló la creación de la transacción. Algunos códigos no relacionados con el pagador pueden indicarle que genere una alerta sobre problemas con la disponibilidad del servicio, particularmente los relacionados con mala configuración.

Una vez ha almacenado la información en su base de datos y ha confirmado que es exitosa la petición, se redirigirá al cliente a la URL del banco. Tenga en cuenta que la redirección a la interfaz del banco no debe realizarse en un frame o cualquier otro mecanismo que oculte la URL en la cual el cliente ingresará sus datos de autenticación.

Reingreso del cliente

Una vez el cliente ha finalizado la transacción en la interfaz del banco, el banco redirige al cliente a la URL especificada al crear la transacción, en este punto de entrada a su aplicativo, usted deberá consumir el servicio getTransactionInformation que le permite determinar el estado de la transacción. Solo si la transacción tiene como estado OK es porque la transacción fue autorizada, si por el contrario obtiene un estado PENDING es porque aún no tiene respuesta final del banco acerca de la transacción.

Ya sea que el cliente retorne al punto de reingreso y que la transacción esté pendiente, o que haya abandonado la operación y haya roto el flujo normal, se deberá consumir el servicio getTransactionInformation para todas las operaciones que desde que fue invocado el createTransaction llevan más de 7 minutos sin un estado final de operación.

Métodos de interfaz PSE

A continuación se describen cada una de los métodos de tipo petición respuesta expuestas por el Webservice, se muestran los parámetros de entrada a cada operación y vínculos a las estructuras de datos usadas.

getBankList

Ejemplo para realizar una llamada al método getBankList:

<?php
       public function bancos()
       {
              $seed = date('c');
              $secretKey = '024h1IlD';
              $trankey = sha1($seed.$secretKey);

              $servicio = 'https://test.placetopay.com/soap/pse/v11/?wsdl'; //url del servicio
              //AUTENTICACION
              $auth = array(
              'login' => '6dd490faf9cb87a9862245da41170ff2',
              'tranKey' => $trankey,
              'seed' => $seed,
              );

              $arguments = array(
                     'auth' => $auth,
                     );
              $client = new nusoap_client($servicio, array('trace' => true)); // en lugar de SoapClient  se utiliza nusoap_client
              // LAMADA AL METODO GETBANKLIST DE PSE
              $resp = $client->call('getBankList', $arguments);

              $resp1 = $resp['getBankListResult']['item'];

              echo '<h5>Seleccione su banco </h5><br>
               <select name="banco" id="bank" class="form-control" onchange ="r();">';
              // SE RECORRE EL ARRAY PARA LISTAR BANCOS
              foreach ($resp1 as $key => $valor) {
              echo '<option value="'.$valor['bankCode'].'">'.$valor['bankName'].'</option>';
              }
              echo '</select>';
       }
?>

Obtiene la lista de bancos disponibles para el establecimiento de comercio en el sistema PSE de ACH Colombia.

PARÁMETROS

Nombre Tipo Descripción
auth Authentication Datos de autenticación

Retorna
Bank[]. Un arreglo con la lista de bancos habilitados.

createTransaction

Solicita la creación de una transacción. En los datos de la solicitud se especifica quién es el pagador, el comprador y el despacho. Así mismo para cuál de los bancos habilitados se hace la petición y a que URL de retorno debe el banco redirigir al cuentahabiente.

PARÁMETROS

Nombre Tipo Descripción
auth Authentication Datos de autenticación
transaction PSETransactionRequest Datos de la solicitud

Retorna
PSETransactionResponse. Respuesta de la creación de la transacción, tenga en cuenta que la URL del banco se entrega solo si la propiedad returnCode es SUCCESS.

createTransactionMultiCredit

Solicita la creación de una transacción con dispersión de fondos. En los datos de la solicitud se especifica quién es el pagador, el comprador y el despacho. Así mismo para cuál de los bancos habilitados se hace la petición y a que URL de retorno debe el banco redirigir al cuentahabiente. Así como cada uno de los créditos a aplicar para cada uno de los servicios asociados. Tenga en cuenta que un servicio multicrédito tiene asociado unos servicios dependientes. Siempre deberá cobrar a todos los servicios dependientes así el valor para una de los créditos sea cero.

PARÁMETROS

Nombre Tipo Descripción
auth Authentication Datos de autenticación
transaction PSETransactionMultiCreditRequest Datos de la solicitud

Retorna
PSETransactionResponse. Respuesta de la creación de la transacción, tenga en cuenta que la URL del banco se entrega solo si la propiedad returnCode es SUCCESS.

getTransactionInformation

Ejemplo para generar una respuesta de una transacción PSE utilizando el método getTransactionInformation:

  <?php
       if (!isset($_SESSION))
       {
       session_start();
       }
              if (isset($_SESSION["transactionId"])) 
              {
              require_once('../nusoap/lib/nusoap.php');

              $id = $_SESSION["transactionId"]; //'1476515432' $_SESSION["transactionId"]

              $seed = date('c');
              $secretKey = "024h1IlD";
              $trankey = SHA1($seed.$secretKey);
              $servicio="https://test.placetopay.com/soap/pse/v11/?wsdl"; //url del servicio

              $auth = array(
                     'login' => '6dd490faf9cb87a9862245da41170ff2',
                     'tranKey' => $trankey,
                     'seed' => $seed,
                     );

              $arguments = array(
                            'auth' => $auth,
                            'transactionID'=>$id
                            );
              $client = new nusoap_client($servicio, array('trace' => true));

              $resp = $client->call('getTransactionInformation', $arguments);
              //var_dump($resp);
              foreach ($resp as $key => $valor) 
              {
                     $reason = $valor["responseReasonText"];
                     $reference = $valor["reference"];
                     $estado  =  $valor["transactionState"];
              }
              echo '<div class="card m-t-25 ">
                                   <div class="card-body">
                                          <div class="row">
                                                 <div class="col-md-6">
                                                 <h4>Referencia :'.$reference.' </h4>

                                                 <h4>Estado :'.$estado.' </h4>

                                                 <h4>Razon :'.$reason.' </h4>
                                                 </div>
                                          </div>
                                   </div>
                            </div>';

              session_destroy();
              }
<?php

Obtiene la información de una transacción, debe ser consultado para cualquier operación previamente creada con el método createTransaction o createTransactionMultiCredit ya sea cuando regresa del banco o cuando al menos han transcurrido 7 minutos desde que el cliente fue redirigido a la interfaz del banco. Deberá consumirse en intervalos de al menos cada 12 minutos hasta que tenga un estado de transacción diferente a PENDING.

PARÁMETROS

Nombre Tipo Descripción
auth Authentication Datos de autenticación
transactionID int Identificador único de la transacción en Placetopay, equivale al retornado en la creación de la transacción.

Retorna
TransactionInformation. Información del estado de la transacción.

Estructuras de datos PSE

Las estructuras de datos utilizadas por los métodos del servicio web se describen a continuación:

Attribute

Estructura para almacenar información extendida.

ATRIBUTOS

Nombre Tipo Descripción
name string[30] Código para referenciar el atributo
value string[128] Valor que asume el atributo

Persona

Ejemplo de generación de una estructura Person dentro de la integración de pago con PSE:

  <?php
       $payer = array(
                    'documentType' => 'CC',
                    'document' => '1037390240',
                    'firstName' => 'Juan',
                    'lastName' => 'Chavarria',
                    'emailAddress' => 'soporte9@placetopay.com',
                    'city' => 'Bello',
                    'province' => 'Colombia',
                    'country' => 'Antioquia',
                    'mobile' => '3104317467',
                );
  ?>

Estructura para reflejar la información de una persona involucrada en una transacción.

ATRIBUTOS

Nombre Tipo Descripción
document string[12] Número de identificación de la persona.
documentType string[3] Tipo de documento de identificación de la persona.
CC = Cédula de ciudadanía colombiana
CE = Cédula de extranjería
TI = Tarjeta de identidad
PPN = Pasaporte
NIT = Número de identificación tributaria
SSN = Social Security Number
firstName string[60] Nombres
lastName string[60] Apellidos
company string[60] Nombre de la compañía en la cual labora o representa.
emailAddress string[80] Correo electrónico.
address string[100] Dirección postal completa.
city string[50] Nombre de la ciudad coincidente con la dirección.
province string[50] Nombre de la provincia o departamento coincidente con la dirección.
country string[2] Código internacional del país que aplica a la dirección física acorde a ISO 3166-1, mayúscula sostenida.
phone string[30] Número de telefonía fija.
mobile string[30] Número de telefonía móvil o celular.

Bank

Estructura para reflejar la información de una entidad bancaria.

ATRIBUTOS

Nombre Tipo Descripción
bankCode string[4] Código de la entidad financiera.
bankName string[60] Nombre de la entidad financiera.

CreditConcept

Estructura que representa el concepto del crédito a favor de un tercero.

ATRIBUTOS

Nombre Tipo Descripción
entityCode string[12] Código de la entidad del tercero para dispersión.
serviceCode string[12] Código del servicio del tercero.
amountValue double Valor total a recaudar a favor de la entidad.
taxValue double Discriminación del impuesto aplicado a favor de la entidad.
description string[60] Descripción el concepto cobrado.

PSETransactionRequest

Ejemplo de generación de una estructura PSETransactionRequest dentro de la integración de pago con PSE:

  <?php
              $transaction = array(
                     'bankCode' => $banco,
                     'bankInterface' => 0,
                     'returnURL' => 'http://localhost/API_AIM/Controlador/RespuestaPSE.php',
                     'reference' => $reference = time(),
                     'description' => 'Pago',
                     'language' => 'ES',
                     'currency' => $_POST['moneda'],
                     'totalAmount' => $_POST['total'],
                     'taxAmount' => 0,
                     'devolutionBase' => 0,
                     'tipAmount' => 0,
                     'payer' => $payer,
                     'ipAddress' => '192.168.1.12',
              );
  ?>

Estructura que representa una solicitud de transacción con débitos a cuenta PSE.

ATRIBUTOS

Nombre Tipo Descripción
bankCode string[4] Código de la entidad financiera con la cual realizar la transacción.
bankInterface string[1] Tipo de interfaz del banco a desplegar 0 = PERSONAS, 1 = EMPRESAS]
returnURL string[255] URL de retorno especificada para la entidad financiera.
reference string[32] Referencia única de pago.
description string[255] Descripción del pago.
language string[2] Idioma esperado para las transacciones acorde a ISO 631-1, mayúscula sostenida.
currency string[3] Moneda a usar para el recaudo acorde a ISO 4217.
totalAmount double Valor total a recaudar.
taxAmount double Discriminación del impuesto aplicado.
devolutionBase double Base de devolución para el impuesto.
tipAmount double Propina u otros valores exentos de impuesto (tasa aeroportuaria) y que deben agregarse al valor total a pagar.
payer Person Información del pagador.
buyer Person Información del comprador.
shipping Person Información del receptor.
ipAddress string[15] Dirección IP desde la cual realiza la transacción el pagador.
userAgent string[255] Agente de navegación utilizado por el pagador.
additionalData Attribute[] Datos adicionales para ser almacenados con la transacción.

PSETransactionMultiCreditRequest

Estructura que representa una solicitud de transacción con débitos a cuenta PSE.

ATRIBUTOS

Nombre Tipo Descripción
bankCode string[4] Código de la entidad financiera con la cual realizar la transacción.
bankInterface string[1] Tipo de interfaz del banco a desplegar [0 = PERSONAS, 1 = EMPRESAS]
returnURL string[255] URL de retorno especificada para la entidad financiera.
reference string[32] Referencia única de pago.
description string[255] Descripción del pago.
language string[2] Idioma esperado para las transacciones acorde a ISO 631-1, mayúscula sostenida.
currency string[3] Moneda a usar para el recaudo acorde a ISO 4217.
totalAmount double Valor total a recaudar.
taxAmount double Discriminación del impuesto aplicado.
devolutionBase double Base de devolución para el impuesto.
tipAmount double Propina u otros valores exentos de impuesto (tasa aeroportuaria) y que deben agregarse al valor total a pagar.
payer Person Información del pagador.
buyer Person Información del comprador.
shipping Person Información del receptor.
ipAddress string[15] Dirección IP desde la cual realiza la transacción el pagador.
userAgent string[255] Agente de navegación utilizado por el pagador.
additionalData Attribute[] Datos adicionales para ser almacenados con la transacción.
credits CreditConcept Detalle de la dispersión a realizar.

PSETransactionResponse

Estructura con la información de respuesta para la creación de una transacción.

ATRIBUTOS

Nombre Tipo Descripción
transactionID int Identificador único de la transacción en Placetopay.
sessionID string[32] Identificador único de la sesión en Placetopay.
returnCode string[30] Código de respuesta de la transacción, uno de los siguientes valores:
SUCCESS
FAIL_ENTITYNOTEXISTSORDISABLED
FAIL_BANKNOTEXISTSORDISABLED
FAIL_SERVICENOTEXISTS
FAIL_INVALIDAMOUNT
FAIL_INVALIDSOLICITDATE
FAIL_BANKUNREACHEABLE
FAIL_NOTCONFIRMEDBYBANK
FAIL_CANNOTGETCURRENTCYCLE
FAIL_ACCESSDENIED
FAIL_TIMEOUT
FAIL_DESCRIPTIONNOTFOUND
FAIL_EXCEEDEDLIMIT
FAIL_TRANSACTIONNOTALLOWED
FAIL_RISK
FAIL_NOHOST
FAIL_NOTALLOWEDBYTIME
FAIL_ERRORINCREDITS
trazabilityCode string[40] Código único de seguimiento para la operación dado por la red ACH
transactionCycle int Ciclo de compensación de la red
bankCurrency string[3] Moneda aceptada por el banco acorde a ISO 4217.
bankFactor float Factor de conversión de la moneda.
bankURL string[255] URL a la cual remitir la solicitud para iniciar la interfaz del banco, sólo disponible cuando returnCode = SUCCESS.
responseCode int Estado de la operación en Placetopay 0 = FAILED, 1 = APPROVED, 2 = DECLINED, 3 = PENDING.
responseReasonCode string[3] Código interno de respuesta de la operación en Placetopay.
responseReasonText string[255] Mensaje asociado con el código de respuesta de la operación en Placetopay.

TransactionInformation

Estructura con la respuesta a una solicitud de información de transacción.

ATRIBUTOS

Nombre Tipo Descripción
transactionID int Identificador único de la transacción en Placetopay.
sessionID string[32] Identificador único de la sesión en Placetopay.
reference string[32] Referencia única de pago.
requestDate string Fecha de solicitud o creación de la transacción acorde a ISO 8601(https://www.iso.org/iso-8601-date-and-time-format.html).
bankProcessDate string Fecha de procesamiento de la transacción acorde a ISO 8601(https://www.iso.org/iso-8601-date-and-time-format.html).
onTest boolean Indicador de si la transacción esta o no en modo de pruebas.
returnCode string[30] Código de respuesta de la transacción, uno de los siguientes:
SUCCESS
FAIL_INVALIDTRAZABILITYCODE
FAIL_ACCESSDENIED
FAIL_INVALIDSTATE
FAIL_INVALIDBANKPROCESSINGDATE
FAIL_INVALIDAUTHORIZEDAMOUNT
FAIL_INCONSISTENTDATA
FAIL_TIMEOUT
FAIL_INVALIDVATVALUE
FAIL_INVALIDTICKETID
FAIL_INVALIDSOLICITEDATE
FAIL_INVALIDAUTHORIZATIONID
FAIL_TRANSACTIONNOTALLOWED
FAIL_ERRORINCREDITS
FAIL_EXCEEDEDLIMIT
trazabilityCode string[40] Código único de seguimiento para la operación dado por la red ACH.
transactionCycle int Ciclo de compensación de la red.
transactionState string[20] Información del estado de la transacción OK, NOT_AUTHORIZED, PENDING, FAILED.
responseCode int Estado de la operación en Placetopay.
responseReasonCode string[3] Código interno de respuesta de la operación en Placetopay.
responseReasonText string[255] Mensaje asociado con el código de respuesta de la operación en Placetopay.

Webservice Tuya

A continuación se describe el flujo, metodos e interfaces básicas con las cuales debe contar su desarrollo para poder lograr exitosamente la revisión del proceso.

Flujo de integración Tuya

Ejemplo para integrar un pago con tarjeta TUYA O EXITO:

<?php
     class Pagos
       {
       public function RealizarPago()
       {
              $seed = date('c');
              $secretKey = '024h1IlD';
              $trankey = sha1($seed.$secretKey);

              $servicio = 'https://test.placetopay.com/soap/tuya/v11/?wsdl'; //url del servicio

              $auth = array(
              'login' => '6dd490faf9cb87a9862245da41170ff2',
              'tranKey' => $trankey,
              'seed' => $seed,
              );
               $payer = array(
                    'documentType' => 'CC',
                    'document' => '1037390240',
                    'firstName' => 'Juan',
                    'lastName' => 'Chavarria',
                    'emailAddress' => 'soporte9@placetopay.com',
                    'city' => 'Bello',
                    'province' => 'Colombia',
                    'country' => 'Antioquia',
                    'mobile' => '3104317467',
                );

                $transaction = array(
                    'franchise' => $tarjetaTuya, //TY_AK,TY_EX
                    'returnURL' => 'http://localhost/API_AIM/Controlador/Respuesta.php',
                    'reference' => '123',
                    'description' => 'prueba venta',
                    'language' => 'ES',
                    'currency' => 'COP',
                    'totalAmount' => 1000,
                    'taxAmount' => 0,
                    'devolutionBase' => 0,
                    'tipAmount' => 0,
                    'payer' => $payer,
                    'buyer' => $payer,
                    'ipAddress' => '192.168.1.12',
                  );
                 $arguments = array(
                    'auth' => $auth,
                    'transaction' => $transaction,
                     );
              $client = new nusoap_client($servicio, array('trace' => true));
             // SE CREA TRANSACCION PARA PAGO POR TARJETAS TUYA
             $resp = $client->call('createTransaction', $arguments);
             echo '<div class="container">
              <div class="card m-t-25 ">
                  <div class="card-body">
                    <br>
                        <strong>ESTADO: </strong>'.$resp['createTransactionResult']['returnCode'].'
                          <br>
                          <strong>RAZON: </strong>'.$resp['createTransactionResult']['responseReasonText'].'
                          <br>
                          <strong>BANCO: </strong>'.$resp['createTransactionResult']['bankName'].'
                          <br>
                          <strong>ID TRANSACCION: </strong>'.$resp['createTransactionResult']['transactionID'].'
                          <br>
                          <strong>URL DEL BANCO: </strong>'.$resp['createTransactionResult']['bankURL'].'
                  <div/>
              <div/>
          <div/>';
      }
  }
?>

¿Cómo funciona la implementación?

  1. Se muestra como opción de pago Tarjeta Éxito y Tarjeta Alkosto (dependerá de si se tiene convenio para cada uno de los medios de pago).
  2. Una vez el usuario la selecciona el medio de pago y confirma la operación, debe consumirse el servicio para realizar la petición de la transacción.
  3. Si la petición es exitosa se retorna la URL a la cual debe enviarse al cliente para que realice la operación en en medio de pago. En caso contrario se retorna el motivo del rechazo de la transacción.
  4. Almacenar los datos de la transacción retornados por el servicio (identificador de la transacción, autorización, identificador sesión de placetopay).
  5. Redirigir el navegador a la URL retornada en caso de éxito.
  6. Una vez la transacción retorna (retorna a la URL especificada en el consumo del crear transacción), se debe preguntar por el estado de la transacción mediante el consumo un servicio.
  7. Dependiendo de la respuesta del servicio, la transacción puede haber sido aprobada, rechazada o seguir pendiente de procesamiento.
  8. Informar al usuario el estado de la transacción.
  9. Si la transacción está pendiente, o si el cliente al abandonar el portal no ha regresado, se debe tener una sonda que pregunte por el estado de la transacción.

Confirmación y redirección a banco

Una vez ya se tengan los datos del pagador y comprador, así como la información de qué medio de pago usará, deberá entonces consumir el servicio de createTransaction para obtener la URL a la cual deberá redirigir al cliente para finalizar la transacción.

Debe tener en cuenta que en los datos solicitados para crear la transacción se requiere la dirección IP desde la cual el cliente estará realizando la transacción, así como la información del agente de navegación usado. Si lo desea, también puede proveer datos adicionales con la transacción, los cuales le permitirán tener esta información disponible en la consola de consulta de transacciones de Placetopay. Tenga en cuenta que el documento del pagador es el documento del dueño de la tarjeta y que no podrá ser modificado posteriormente en la interfaz de TUYA para ese medio de pago.

Si la respuesta del servicio es SUCCESS, entonces deberá almacenar la información retornada en su base de datos, de vital importancia el transactionID pues es con este identificador que podrá consultar el estado final de la transacción.

Tenga en cuenta que una respuesta SUCCESS en este punto sólo implica que la transacción ha sido aprovisionada por TUYA y está en espera que el cliente llegue a la interfaz del medio de pago, se autentique y autorice la operación iniciada.

Al crear la transacción, esta puede fallar; algunos motivos incluyen montos por fuera del rango permitido, no disponibilidad del medio de pago, problemas de configuración de la cuenta recaudadora, entre otros. Utilice el parametro responseReasonText para obtener el mensaje de por qué falló la creación de la transacción. Algunos códigos no relacionados con el pagador pueden indicarle que genere una alerta sobre problemas con la disponibilidad del servicio, particularmente los relacionados con mala configuración.

Una vez ha almacenado la información en su base de datos y ha confirmado que es exitosa la petición, se redirigirá al cliente a la URL del medio de pago. Tenga en cuenta que la redirección a la interfaz del medio de pago no debe realizarse en un frame o cualquier otro mecanismo que oculte la URL en la cual el cliente ingresará sus datos de autenticación.

Reingreso cliente

Una vez el cliente ha finalizado la transacción en la interfaz del banco, el banco redirige al cliente a la URL especificada al crear la transacción, en este punto de entrada a su aplicativo, usted deberá consumir el servicio getTransactionInformation que le permite determinar el estado de la transacción. Solo si la transacción tiene como estado OK es porque la transacción fue autorizada, si por el contrario obtiene un estado PENDING es porque aún no tiene respuesta final del banco acerca de la transacción.

Ya sea que el cliente retorne al punto de reingreso y que la transacción esté pendiente, o que haya abandonado la operación y haya roto el flujo normal, se deberá consumir el servicio getTransactionInformation para todas las operaciones que desde que fue invocado el createTransaction llevan más de 7 minutos sin un estado final de operación.

Métodos de interfaz Tuya

Los métodos son las operaciones expuestas por el webservice de tipo petición respuesta, donde se muestran los parámetros de entrada y vinculos a las estructuras de datos usadas.

createTransaction

Ejemplo para utilizar el metodo createTransaction:

<?php
      ...  
        $arguments = array(
              'auth' => $auth,
              'transaction' => $transaction,
          );
        $client = new nusoap_client($servicio, array('trace' => true));
       // SE CREA TRANSACCION PARA PAGO POR TARJETAS TUYA
        $resp = $client->call('createTransaction', $arguments);
       ...
?>

Solicita la creación de una transacción. En los datos de la solicitud se especifica quien es el pagador, el comprador y el despacho. Así mismo para cuál de los medios de pago habilitados se hace la petición y a que URL de retorno debe el medio de pago redirigir al tarjeta habiente.

PARÁMETROS

Nombre Tipo Descripción
auth Authentication Datos de autenticación
transaction TuyaTransactionRequest Datos de la solicitud

Retorna
TuyaTransactionResponse. Respuesta de la creación de la transacción, tenga en cuenta que la URL del medio de pago se entrega solo si la propiedad returnCode es SUCCESS.

getTransactionInformation

Obtiene la información de una transacción, debe ser consultado para cualquier operación previamente creada con el método createTransaction ya sea cuando regresa del medio de pago o cuando al menos han transcurrido 7 minutos desde que el cliente fue redirigido a la interfaz del medio de pago. Deberá consumirse en intervalos de al menos cada 12 minutos hasta que tenga un estado de transacción transactionState diferente a PENDING.

PARÁMETROS

Nombre Tipo Descripción
auth Authentication Datos de autenticación
transactionID int Identificador único de la transacción en Placetopay, equivale al retornado en la creación de la transacción.

Retorna
TransactionInformation. Información del estado de la transacción.

Estructuras de datos Tuya

Cada una de las estructuras de datos usadas por los métodos del Webservice se describen a continuación.

Attribute

Estructura para almacenar información extendida.

ATRIBUTOS

Nombre Tipo Descripción
name string[30] Código para referenciar el atributo
value string[128] Valor que asume el atributo

Persona

Ejemplo de generación de una estructura Person dentro de la integración de pago con tarjeta TUYA:

  <?php
       $payer = array(
                    'documentType' => 'CC',
                    'document' => '1037390240',
                    'firstName' => 'Juan',
                    'lastName' => 'Chavarria',
                    'emailAddress' => 'soporte9@placetopay.com',
                    'city' => 'Bello',
                    'province' => 'Colombia',
                    'country' => 'Antioquia',
                    'mobile' => '3104317467',
                );
  ?>

Estructura para reflejar la información de una persona involucrada en una transacción.

ATRIBUTOS

Nombre Tipo Descripción
document string[12] Número de identificación de la persona.
documentType string[3] Tipo de documento de identificación de la persona.
CC = Cédula de ciudadanía colombiana
CE = Cédula de extranjería
TI = Tarjeta de identidad
PPN = Pasaporte
NIT = Número de identificación tributaria
SSN = Social Security Number
firstName string[60] Nombres
lastName string[60] Apellidos
company string[60] Nombre de la compañía en la cual labora o representa.
emailAddress string[80] Correo electrónico.
address string[100] Dirección postal completa.
city string[50] Nombre de la ciudad coincidente con la dirección.
province string[50] Nombre de la provincia o departamento coincidente con la dirección.
country string[2] Código internacional del país que aplica a la dirección física acorde a ISO 3166-1, mayúscula sostenida.
phone string[30] Número de telefonía fija.
mobile string[30] Número de telefonía móvil o celular.

TuyaTransactionRequest

Ejemplo de una estructura TuyaTransactionRequest:

<?php
  ...
      $transaction = array(
        'franchise' => $tarjetaTuya, //TY_AK,TY_EX
        'returnURL' => 'http://localhost/API_AIM/Controlador/Respuesta.php',
        'reference' => '123',
        'description' => 'prueba venta',
        'language' => 'ES',
        'currency' => 'COP',
        'totalAmount' => 1000,
        'taxAmount' => 0,
        'devolutionBase' => 0,
        'tipAmount' => 0,
        'payer' => $payer,
        'buyer' => $payer,
        'ipAddress' => '192.168.1.12',
      );
  ...
?>

Estructura que representa una solicitud de transacción con tarjetas expedidas por TUYA.

ATRIBUTOS

Nombre Tipo Descripción
franchise string[4] Código del medio de pago TY_EX = Tarjeta Éxito, TY_AK = Tarjeta Alkosto
returnURL string[255] URL de retorno especificada para la entidad financiera.
reference string[32] Referencia única de pago.
description string[255] Descripción del pago.
language string[2] Idioma esperado para las transacciones acorde a ISO 631-1, mayúscula sostenida.
currency string[3] Moneda a usar para el recaudo acorde a ISO 4217.
totalAmount double Valor total a recaudar.
taxAmount double Discriminación del impuesto aplicado.
devolutionBase double Base de devolución para el impuesto.
tipAmount double Propina u otros valores exentos de impuesto (tasa aeroportuaria) y que deben agregarse al valor total a pagar.
payer Person Información del pagador.
buyer Person Información del comprador.
shipping Person Información del receptor.
ipAddress string[15] Dirección IP desde la cual realiza la transacción el pagador.
userAgent string[255] Agente de navegación utilizado por el pagador.
additionalData Attribute[] Datos adicionales para ser almacenados con la transacción.

TuyaTransactionResponse

Estructura con la información de respuesta para la creación de una transacción.

ATRIBUTOS

Nombre Tipo Descripción
transactionID int Identificador único de la transacción en Placetopay.
sessionID string[32] Identificador único de la sesión en Placetopay.
returnCode string[30] Código de respuesta de la transacción, uno de los siguientes valores:
SUCCESS
FAIL_INVALIDGATEWAYID
FAIL_INVALIDFRANCHISE
FAIL_INVALIDRETAILCODE
FAIL_INVALIDCURRENCY
FAIL_INVALIDAMOUNT
FAIL_TIMEOUT
FAIL_TRANSACTIONNOTALLOWED
FAIL_RISK
FAIL_NOHOST
trazabilityCode string[64] Código único de seguimiento para la operación dado por la red TUYA
bankCurrency string[3] Moneda aceptada por el banco acorde a ISO 4217.
bankFactor float Factor de conversión de la moneda.
bankURL string[255] URL a la cual remitir la solicitud para iniciar la interfaz del banco, sólo disponible cuando returnCode = SUCCESS.
responseCode int Estado de la operación en Placetopay 0 = FAILED, 1 = APPROVED, 2 = DECLINED, 3 = PENDING.
responseReasonCode string[3] Código interno de respuesta de la operación en Placetopay.
responseReasonText string[255] Mensaje asociado con el código de respuesta de la operación en Placetopay.

TransactionInformation

Estructura con la respuesta a una solicitud de información de transacción.

ATRIBUTOS

Nombre Tipo Descripción
transactionID int Identificador único de la transacción en Placetopay.
sessionID string[32] Identificador único de la sesión en Placetopay.
reference string[32] Referencia única de pago.
requestDate string Fecha de solicitud o creación de la transacción acorde a ISO 8601(https://www.iso.org/iso-8601-date-and-time-format.html).
franchise string[5] Franquicia con la cual se procesó la transacción.
bankName string[80] Nombre del banco o entidad financiera.
bankProcessDate string Fecha de procesamiento de la transacción acorde a ISO 8601(https://www.iso.org/iso-8601-date-and-time-format.html).
onTest boolean Indicador de si la transacción esta o no en modo de pruebas.
returnCode string[30] Código de respuesta de la transacción, uno de los siguientes:
SUCCESS
FAIL_INVALIDGATEWAYID
FAIL_INVALIDFRANCHISE
FAIL_INVALIDRETAILCODE
FAIL_INVALIDCURRENCY
FAIL_INVALIDAMOUNT
FAIL_TIMEOUT
FAIL_TRANSACTIONNOTALLOWED
authCode string[40] Código de autorización asignado a la transacción.
trazabilityCode string[64] Código único de seguimiento para la operación dado por la red TUYA.
lastDigits string[6] Últimos dígitos de la tarjeta de crédito usada
transactionState string[20] Información del estado de la transacción OK, NOT_AUTHORIZED, PENDING, FAILED.
responseCode int Estado de la operación en Placetopay.
responseReasonCode string[3] Código interno de respuesta de la operación en Placetopay.
responseReasonText string[255] Mensaje asociado con el código de respuesta de la operación en Placetopay.