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": "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 Descripción
Colombia AC_WU ath Wester Union
AV_AV ath Banco AV Villas Recaudos
AV_BB ath Banco de Bogotá Recaudos
AV_BO ath Banco de Occidente Recaudos
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 Codensa
CMRFB falabella
CR_AM amex American Express
CR_CR credencial Credencial Banco de Occidente
CR_DN diners Diners Club
CR_VE visa_electron Visa Electron
CR_VS visa Visa
DBTAC debito Registro cuentas débito
DF_DN diners
DF_DS discover
DF_MC master
DF_VS visa
DISCO discover Disvover
DVVND ath
EFCTY efecty Efecty
ENPCT cooperativa
GNOFC gana
GNPIN gana GanaPIN
GNRIS ris Tarjeta RIS
ID_DN diners
ID_DS discover
ID_MC master
ID_VS visa
MSTRP masterpass Masterpass
PBBVA ath
PINVL Pin Valida
PYPAL PayPal PayPal
RM_MC master MasterCard
SOMOS somos
SB_VS visa
SFPAY safetypay Safety Pay
SPGRS supergiros
T1_BC ath Bancolombia Recaudos
T1_CV ath
TY_AK Alkosto Alkosto
TY_EX Exito Tarjeta Éxito
VISAC visa_checkout Visa Checkout
V_VBV Verified by visa
ATH ath Corresponsales bancarios Grupo Aval
PPD ppd Débito pre-autorizado (PPD)
PSE pse Débito a cuentas corrientes y ahorros (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 Credito Colombia

Aquí se describe un método de conexión a Placetopay basado en el envío de datos por método POST a la plataforma en una comunicación servidor servidor bajo un esquema REST.

Este mecanismo sólo debe ser usado por aquellos clientes de la plataforma que requieren capturar la información del tarjeta habiente incluyendo los datos sensibles. Este tipo de integración sólo está pensado para soportar la operación de tarjetas no presenciales que no requieran PIN para su operación.

Descripción del método

El método de integración avanzado o AIM, contempla las operaciones básicas para el procesamiento de tarjetas no presenciales, esto es la autorización, captura, reverso, asiento, anulación. A continuación se describirán cada uno de los usos y los datos requeridos en la trama para cada uno de los casos. La respuesta para cada operación está unificada en un solo tipo de trama resultante. La implementación de este método se hizo pensando en minimizar el ancho de banda requerido para la comunicación así como la facilidad de implementación en cualquier lenguaje de programación que sea capaz de establecer una comunicación por sockets a través del protocolo HTTPS.

Flujo de integración AIM

Cómo funciona la implementación?

  1. Se hace una compilación de los datos a ser enviados a la plataforma, incluyendo los datos sensibles de la tarjeta (número, expiración, CVV2).
  2. Se prepara la petición POST a nivel de servidor, tenga en cuenta que el servicio espera los datos en codificación ISO-8859-1. Los datos a ser remitidos a Placetopay dependerán de la operación que desea realizar.
  3. Se hace el POST a Placetopay, y se espera por la respuesta. Normalmente los tiempos de respuesta son de 2 a 3 segundos, sin embargo tenga en cuenta que dependiendo de congestión de la red u otros factores, el tiempo puede incrementarse. Verifique que en la implementación su script espera al menos hasta 15 o 20 segundos antes de dar un timeout.
  4. Si obtuvo una respuesta de la plataforma entonces proceda a desglosarla (la respuesta se entrega como una cadena de caracteres separados por coma) y a identificar los datos relevantes para su sistema, normalmente serán el estado de la transacción, el motivo asociado al estado, la franquicia, el banco emisor, la autorización, el recibo y la identificación de la transacción en Placetopay.
  5. Si por el contrario no obtuvo una respuesta válida u obtuvo un timeout deberá seguir el proceso de consulta de la transacción para determinar el estado de la misma.
  6. Presente al usuario el resultado de la transacción y active las otras rutas de flujo en su sistema.

¿En qué casos es mejor usar este tipo de integración?

La integración AIM se recomienda únicamente en los casos que no sea factible que el usuario realice la transacción ingresando los datos sensibles en Placetopay o en donde se requiere un control particular de la operación. Algunos ejemplos son: * Cobros recurrentes desde una base de datos propietaria. * Integración con un sistema de audiorespuesta. * Múltiples transacciones a diferentes recaudadores con la misma información del tarjetahabiente. * Interfaz móvil propietaria, no basada en HTML. * Integración con sistemas cuya entrada de los datos sensibles no la realice directamente el tarjetahabiente.

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

Tenga en cuenta que al usar este tipo de integración, usted está suministrando todos los datos del comprador incluyendo los datos sensibles de la tarjeta, este solo hecho requiere que la captura de la información sea por un mecanismo seguro que no ponga en peligro los datos del tarjetahabiente. Si la información la captura por una página Web, el punto donde se capturan estos datos debe estar sobre protocolo seguro HTTPS usando certificados de seguridad expedidos por una entidad certificadora acreditada.

Si la captura la realiza por un Call Center, quien obtiene los datos sensibles debe ser un mecanismo de IVR (Interactive Voice Response) o audiorespuesta; esto implicaría un rompimiento en el proceso entre el proceso que realiza el operador con su CRM y el IVR quien captura los datos sensibles. Finalmente el CRM consolida los dos conjuntos de datos y los remite a Placetopay.

Si la captura proviene de una base de datos de tarjetas previamente inscritas, asegúrese que esta información está encriptada por un mecanismo seguro de encriptación como AES o 3DES, desencripte solo en el momento en que construye la trama a ser enviada a Placetopay.

Tenga en cuenta que como regla general usted no debe almacenar el número de tarjeta, fecha de vencimiento y CVV2. Estos solo pueden tener persistencia durante la solicitud de la autorización, una vez procesada no deben ser almacenados.

Como cualquier proceso de integración, este requerirá una certificación del personal de soporte de Placetopay para revisar temas de funcionamiento, mejores prácticas y usabilidad.

Metodos de interfaz credito Colombia

A continuación se describen las tramas que deben ser enviadas a Placetopay para que la plataforma procese una operación, de igual forma la trama de respuesta entregada por la plataforma.

Solicitud de autorización

Este tipo de solicitud permite realizar un cobro en línea. Esta operación se logra remitiendo el valor AUTH_ONLY en la variable x_type.

Solicitud de captura

Este tipo de operación preprocesa la transacción y la deja en estado pendiente. Posteriormente se deberá realizar una operación de asiento o de anulación. Esta operación se logra remitiendo el valor CAPTURE_ONLY en la variable x_type.

Solicitud de asiento o anulación de captura

Operación complementaria a la de captura. Tiene como objetivo terminar el cobro de la operación o en su defecto cancelar la solicitud. Esta operación se logra remitiendo los valores de SETTLE o VOID en la variable x_type dependiendo de si se desea asentar o anular.

Solicitud de reversa

Una operación de reversa tiene sentido sobre una transacción previamente aprobada. Tenga en cuenta que actualmente hay una restricción para la reversa, y esta solo puede solicitarse el mismo día de la transacción aprobada con un límite de las 10:00pm hora colombiana. Tenga en cuenta que una transacción de reversa puede declinar y que dependerá del banco emisor dar o no la autorización, igual que lo hace con una autorización.

Estructura de datos credito

Desde aquí se describen cada uno de los campos que son usados en las diferentes tramas. Se han categorizado acorde al tipo de información que representan; la columna valor posible determina en algunos casos el único valor permitido para el campo.

Datos de la especificación

ATRIBUTOS

Campo Tipo Valor posible Descripción
x_version String[3] 2.0 Versión de la trama a ser usada para comunicarse con Placetopay.
x_delim_data String[5] TRUE Indicador de que los datos de respuesta van delimitados (el delimitador es la coma).
x_relay_response String[5] FALSE Indicador de si no espera la respuesta.
x_language String[2] Código del idioma acorde a ISO 631-1 en que se dan las notificaciones en la plataforma. Por defecto es ES (español).

Datos del comercio y operación

ATRIBUTOS

Campo Tipo Valor posible Descripción
x_login String[32] Identificador del sitio del comercio en la Plataforma.
x_tran_key String[16] Clave para poder enviar una transacción.
x_test_request String[5] TRUE / FALSE Indicador de si la transacción va en modo de prueba o no. Por defecto es FALSE (producción).
x_type String[12] AUTH_ONLY / CAPTURE_ONLY / CREDIT / SETTLE / VOID Tipo de operación a realizar.
x_method String[2] CC Método usado para el procesamiento.
x_email_merchant String[5] TRUE / FALSE Indicador de si debe enviarse un correo electrónico al comercio cuando haya una transacción exitosa.
x_email_customer String[5] TRUE / FALSE Indicador de si debe enviarse un correo electrónico al pagador cuando haya una transacción exitosa.
x_customer_ip String[15] Dirección IP desde la cual está realizando el pago el usuario pagador.

Datos del cobro

ATRIBUTOS

Campo Tipo Valor posible Descripción
x_invoice_num String[32] Número de referencia, orden de pedido o factura relacionada.
x_description String[255] Descripción de la compra.
x_currency_code String[3] Código de la moneda acorde a ISO 4217 en la cual está expresado el cobro.
x_amount Decimal [9.2] Valor total de la compra incluyendo impuestos.
x_tax Decimal [9.2] Valor total de los impuestos.
x_amount_base Decimal [9.2] Valor base de devolución de impuestos (solo aplica para Colombia en los casos en que el impuesto sea del 16% o 10%). Se define como el valor sobre el cual fue calculado el impuesto. Por lo tanto si no hay impuesto, no hay base de devolución.
x_token String[64] Token a ser usado, en el caso de que haya tokenizado los datos de la tarjeta.
x_card_num String[16] Número de la tarjeta, no requerido si usa token.
x_card_type String[1] C / A / R Tipo de la tarjeta, no requerido si usa token.
C = crédito
A = débito ahorros
R = débito corriente
x_exp_date String[12] Fecha de vencimiento de la tarjeta, no requerido si usa token, se aceptan los siguientes formatos: MMAA, MMAAAA, AAAAMMDD, AAAA/MM/DD, AAAA-MMDD.
x_card_code String[4] Dígitos de verificación de la tarjeta (CVV2).
x_differed Integer 1 - 36 Número de cuotas a las cuales difiere el pago. En su ausencia se supone a una cuota.

Datos para cobros recurrentes

Tenga en cuenta que los valores de recurrencia son todos requeridos si el valor del campo x_recurring_bill es TRUE. Estos datos no tienen sentido en otro caso.

ATRIBUTOS

Campo Tipo Valor posible Descripción
x_recurring_bill String[5] TRUE / FALSE Indicador de si la transacción es recurrente. En su ausencia se supone FALSE.
x_recurring_periodicity String [1] Y / M / D Periodicidad para volver a enviar la transacción.
Y = anual
M = mensual
D = diaria
x_recurring_interval Integer El intervalo aplicado a la periodicidad, por ejemplo si el intervalo es 3 y la periodicidad es M, entonces se estará haciendo el cobro trimestralmente. En su ausencia se supone uno (1).
x_recurring_max_periods Integer
x_recurring_due_date String[10] Parte del control de número de veces que se realiza el cobro, corresponde a la fecha hasta la cual se sucederá la recurrencia.Debe establecerse como una fecha en formato AAAA-MM-DD. Si no se desea establecer un máximo debe indicarse UNLIMITED. Debe especificarse este parámetro o en su defecto x_recurring_max_periods.

Datos para cobros con Split

Tenga en cuenta que para pago con dispersión de fondos el comercio debe estar marcado en Placetopay para soportar este tipo de operaciones. De igual forma el x_airline debe llegar en la trama con un código de convenio válido, de lo contrario no hay dispersión y solo se realiza el cobro del valor especificado en x_amount.

ATRIBUTOS

Campo Tipo Valor posible Descripción
x_airline Int Código del convenio, cuando se especifica; los valores dados en x_amount serán cobrados a favor de la entidad del convenio. Así mismo se habilita el cobro del valor dado en el x_service_fee.
x_airport_tax Decimal [8,2] Valor de la tasa aeroportuaria, solo aplica cuando el convenio es una aerolínea.
x_service_fee_code Int 99 Código de compensación para cuando hay dispersión de fondos. Identifica que el valor del x_service_fee será a favor del establecimiento que solicitó la transacción.
x_service_fee Decimal [8,2] Valor total de la tasa administrativa incluyendo impuestos, este será el valor recaudado a nombre del establecimiento.
x_service_fee_tax Decimal [8,2] Valor total del impuesto de la tasa administrativa.
x_service_fee_base Decimal [8,2] Valor base de devolución de impuestos para la TA (solo aplica para Colombia en los casos en que el impuesto sea del 16% o 10%).

Datos del pagador

ATRIBUTOS

Campo Tipo Valor posible Descripción
x_cust_id String [20] Identificación del pagador, está conformado por el tipo de documento y el documento, separados entre ellos por un espacio. Los tipos de documento válidos son:
CC: Cédula de ciudadanía colombiana
CE: Cédula de extranjería
TI: Tarjeta de identidad
NIT: Número de identificación tributaria
PPN: Pasaporte
SSN: Social security number
Un ejemplo del dato puede ser:
CC 71000000.
x_first_name String[30] Nombres completos.
x_last_name String[30] Apellidos completos.
x_company String[50]
x_address String[80] Dirección de correspondencia.
x_city String[30] Ciudad.
x_state String[30] Estado, departamento o provincia.
x_zip String[10] Código postal.
x_country String[2] Código del país acorde a ISO 3166-1.
x_phone String[30] Número de telefonía fija.
Prefereriblemente: +indicativo (zona) teléfono.
x_fax String[30] Número de fax.
Prefereriblemente: +indicativo (zona) teléfono
x_mobile String[30] Número de fax / móvil.
Prefereriblemente: +indicativo (zona) teléfono
x_email String[50] Dirección de correo electrónico.

Datos del comprador o beneficiario receptor del bien o servicio

ATRIBUTOS

Campo Tipo Valor posible Descripción
x_ship_to_id String [20] Identificación del comprador, está conformado por el tipo de documento y el documento, separados entre ellos por un espacio. Los tipos de documento válidos son:
CC: Cédula de ciudadanía colombiana
CE: Cédula de extranjería
TI: Tarjeta de identidad
NIT: Número de identificación tributaria
PPN: Pasaporte
SSN: Social security number
TAX: Numero generico impositivo
RC: Registro civil
Un ejemplo del dato puede ser: CC 71000000.
x_ship_to_first_name String[30] Nombres completos.
x_ship_to_last_name String[30] Apellidos completos.
x_ship_to_company String[50] Compañía para la cual labora.
x_ship_to_address String[80] Dirección de correspondencia.
x_ship_to_city String[30] Ciudad.
x_ship_to_state String[30] Estado, departamento o provincia.
x_ship_to_zip String[10] Código postal.
x_ship_to_country String[2] Código del país acorde a ISO 3166-1.
x_ship_to_phone String[30] Número de telefonía fija.
Prefereriblemente: +indicativo (zona) teléfono
x_ship_to_mobile String[30] Número de celular / móvil.
Prefereriblemente: +indicativo (zona) teléfono
x_ship_to_email String[50] Dirección de correo electrónico.

Datos para operaciones sobre transacciones

ATRIBUTOS

Campo Tipo Valor posible Descripción
x_franchise String[5] Código de la franquicia con la cual se hizo el pago.
x_approval_code String[10] Código de aprobación entregado por la entidad financiera en la transacción

original. | x_transaction_id | String[10] | | Número único de la transacción proveniente de la transacción original. | x_parent_session | String[32] | | Identificador interno de la transacción que se desea asentar o anular, corresponde al x_placetopay_id.

Datos adicionales para almacenar con la transacción

ATRIBUTOS

Campo Tipo Valor posible Descripción
x_additional_data Array Utilice esta estructura para enviar datos adicionales a Placetopay que desea almacenar conjuntamente con la transacción. Básicamente este campo actua como un diccionario de datos tipo clave => valor.
La clave tiene restricciones de forma, no puede iniciar con un número y solo debe contener letras no acentuadas, números, guiones medios o guiones de piso. Tiene una longitud máxima de 30 caracteres. El valor tiene una longitud máxima de 255 caracteres.
Ej:
x_additional_data[dato1] = “Hola”
x_additional_data[otroDato] = “Mundo”

Información adicional Credito Colombia

Estos son datos que se remiten a la plataforma, y no son tomados en cuenta en la transacción. Pero se retornan en la respuesta.

Campos por tipo de operación

Las convenciones para los campos disponibles por tipo de operación son: R (requerido), O (opcional), C (condicionado a otro campo), - (no aplica). Cuando se especifica condicionado a otro campo por favor vea el detalle de la descripción de campos para entender de cual depende.

CAMPOS/OPERACIÓN AUTH_ONLY CAPTURE_ONLY CREDIT SETTLE VOID
x_version R R R R R
x_delim_data R R R R R
x_relay_response R R R R R
x_language O O - - -
x_login R R R R R
x_tran_key R R R R R
x_test_request O O - - -
x_type R R R R R
x_method O O - - -
x_email_merchant O O - - -
x_email_customer R O - - -
x_customer_ip R R - R R
x_invoice_num R R - - -
x_description O O - - -
x_currency_code O O - - -
x_amount R R - - -
x_tax R R - - -
x_amount_base R R - - -
x_token C C
x_card_num C C - - -
x_card_type C C - - -
x_exp_date C C - - -
x_card_code C C - - -
x_differed R R - - -
x_recurring_bill O O - - -
x_recurring_periodicity C C - - -
x_recurring_interval C C - - -
x_recurring_max_periods C C - - -
x_recurring_due_date C C - - -
x_airline O O - - -
x_airport_tax C C - - -
x_service_fee_code O O - - -
x_service_fee C C - - -
x_service_fee_tax C C - - -
x_service_fee_base C C - - -
x_cust_id R R - - -
x_first_name R R - - -
x_last_name O O - - -
x_company O O - - -
x_address O O - - -
x_city O O - - -
x_state O O - - -
x_zip O O - - -
x_country O O - - -
x_phone O O - - -
En la medida de lo posible se recomienda enviarlo por control de fraude
x_fax O O - - -
x_mobile O O - - -
x_email O O - - -
x_ship_to_id O O - - -
x_ship_to_first_name O O - - -
x_ship_to_last_name O O - - -
x_ship_to_company O O - - -
x_ship_to_address O O - - -
x_ship_to_city O O - - -
x_ship_to_state O O - - -
x_ship_to_zip O O - - -
x_ship_to_country O O - - -
x_ship_to_phone O O - - -
x_ship_to_mobile O O - - -
x_ship_to_email O O - - -
x_additional_data O O - - -
x_franchise - - R R R
x_approval_code - - R - -
x_transaction_id - - R - -
x_parent_session - - - R R

Trama de respuesta

A continuación se detalla la trama de respuesta para cualquiera de las operaciones definidas por el servicio AIM.

La trama de respuesta consiste en una cadena de caracteres separados por coma en el siguiente orden posicional.

Número Campo Tipo Observaciones
1 x_response_code Integer Respuesta a la transacción solicitada.
0: Error
1: Aprobada
2: Declinada
3: Pendiente
2 x_response_subcode String[5] Código interno que acompaña la respuesta.
3 x_response_reason_code String[3] Código de la razón que por la cual se dió la respuesta.
4 x_response_reason_text String[255] Mensaje de la razón por la cual se dio la respuesta.
5 x_approval_code String[10] Código de aprobación entregado por la entidad financiera.
6 x_avs_result_code String[1] Resultado de la validación de los datos de dirección del comprador.
Actualmente se retorna
S: Servicio no soportado
7 x_transaction_id String[10] Identificador de la transacción establecido por la red.
8 x_invoice_num Copia del dato recibido
9 x_description Copia del dato recibido
10 x_amount Copia del dato recibido
11 x_method Copia del dato recibido
12 x_type Copia del dato recibido
13 x_cust_id Copia del dato recibido
14 x_first_name Copia del dato recibido
15 x_last_name Copia del dato recibido
16 x_company Copia del dato recibido
17 x_address Copia del dato recibido
18 x_city Copia del dato recibido
19 x_state Copia del dato recibido
20 x_zip Copia del dato recibido
21 x_country Copia del dato recibido
22 x_phone Copia del dato recibido
23 x_fax Copia del dato recibido
24 x_email Copia del dato recibido
25 x_ship_to_first_name Copia del dato recibido
26 x_ship_to_last_name Copia del dato recibido
27 x_ship_to_company Copia del dato recibido
28 x_ship_to_address Copia del dato recibido
29 x_ship_to_city Copia del dato recibido
30 x_ship_to_state Copia del dato recibido
31 x_ship_to_zip Copia del dato recibido
32 x_ship_to_country Copia del dato recibido
33 x_tax Copia del dato recibido
34 x_duty Mantenido por compatibilidad
35 x_freight Mantenido por compatibilidad
36 x_tax_exempt Mantenido por compatibilidad
37 x_po_num Mantenido por compatibilidad
38 x_md5_hash String[32] MD5 del valor de md5HashKey + x_login + x_transaction_id + x_amount; el amount va formateado con dos decimales. El hash es un valor establecido en la plataforma. Sirve para comprobar la estabilidad de la trama.
39 x_CVV2_response String[1] Indicador de comprobación del CVV2.
P: No procesado
40 x_CAVV_response String[1] Indicador de comprobación del CAVV.
41 x_bank_currency String[3] Código de la moneda con la cual se hizo el recaudo.
42 x_bank_factor Decimal Tasa de conversión de la moneda original vs la moneda de recaudo.
43 x_bank_amount Decimal Valor recaudado convertido a la moneda esperada por la entidad financiera.
44 x_franchise String[5] Código de la franquicia con la cual se hizo el pago.
CR_CR => Credencial
CR_DN => Diners
CR_AM => AMEX
CR_VS => Visa
CR_MC => Mastercard
45 x_bank_name String[30] Nombre del banco que autorizó la transacción (no siempre disponible)
46 x_placetopay_id String[32] Identificador único de la transacción retornado por Placetpay
47 x_ta_response_code
48 x_ta_response_reason_code
49 x_ta_approval_code
50 x_ta_transaction_id
51 x_placetopay_internal_reference Int Referencia interna en Placetopay enviada a la red como referencia de la transacción
52 x_response_reason_code_b24 String[3] Código BASE24 equivalente al código ISO que llega en x_response_reason_code
53 x_truncated_pan String[16] Número de tarjeta de crédito truncado admisible para ser visualizado
54 x_discount_code String[32] Código de descuento aplicado. Un valor en blanco en este campo hace que los datos descuento de los demás campos tampoco deban tenerse en cuenta.
55 x_discount_type String[20] Tipo de descuento aplicado.
MERCHANT => Provisto por el comercio
FRANCHISE => Provisto por el medio de pago
OTHER => Provisto por otro actor
56 x_discount_amount Decimal Valor total del descuento en la misma moneda de la solicitud
57 x_discount_base Decimal Valor base sobre el cual fue aplicado el descuento
58 x_discount_percent Decimal Valor porcentual equivalente del descuento
59 De la posición 59 a 68 se reserva para usos futuros.
69 A partir de esta posición se retransmiten los datos adicionales recibidos del comercio.

Envío de transacciones de prueba

En la plataforma, los comercios pueden estar en pruebas o producción. Dependiendo de este modo preconfigurado tiene sentido el parámetro x_test_request; así mismo como las respuestas obtenidas.

Configuración del comercio Configuración del x_test_request Modo de transacción
pruebas TRUE pruebas
pruebas FALSE pruebas
producción TRUE pruebas
producción FALSE producción

En modo de pruebas únicamente son aceptados los siguientes números de tarjetas:

Franquicia Tarjeta Comportamiento
Visa 4005580000000040 Rechaza
Visa 4007000000027 Autoriza
Visa 4111111111111111 Autoriza
Visa 4212121212121214 Deja la operación pendiente como si fuera modo captura, la operación se debe asentar o anular por el panel de Placetopay o en su defecto mediante una operación SETTLE o VOID.
Visa 4666666666666669 Se demora en autorizar 3 minutos. La idea es simular un timeout en su autorización. Así que el consumo del servicio fallará por tiempo, lo cual obligará al consumo de la sonda para verificar cuando la operación culmina su procesamiento. Tenga en cuenta los tiempos de consumo del webservice.
MasterCard 5424000000000015 Autoriza
MasterCard 5406251000000008 Autoriza
AmericanExpress 370000000000002 Autoriza
Diners 36018623456787 Autoriza
BBVA Club Campestre 8130010000000000 Autoriza

Consumo del Webservice de sonda

Para aquellas transacciones que presentan una falla en los tiempos de respuesta, o que no puede ser verificado el x_md5_hash, se deberá consumir un Webservice para obtener de primera mano la información de la transacción.

En los casos que la transacción tiene respuesta pendiente, la regla general es que debe consumirse el servicio cada 12 minutos para las operaciones que tengan al menos 7 minutos de antigüedad. Esto implica que debe existir un proceso automático solicitando al webservice las operaciones que llevan más de 7 minutos pendientes y que el barrido debe hacerse cada 12 minutos.

QueryTransaction

Consulta el estado de una transacción acorde a los parámetros usados, tenga en cuenta que la respuesta es un arreglo de transacciones.

URL del servicio: Pruebas: https://test.placetopay.com/soap/placetopay/v11/ Producción: https://api.placetopay.com/soap/placetopay/v11/

PARÁMETROS

Nombre Tipo Descripción
auth Authentication Datos de autenticación.
request QueryRequest Parámetros para buscar la transacción.

Retorna
Transaction[]. Transacciones que concuerdan con la solicitud.

QueryRequest

Estructura para solicitar la búsqueda de una transacción.

PARÁMETROS

Nombre Tipo Descripción
reference String[32] Número de referencia, orden de compra o factura relacionada. (x_invoice_num usado).
currency String[3] Moneda utilizada en la solicitud acorde a ISO 4217.
totalAmount double Valor total de la operación, si es de aerolinea con TA debe ser la suma del valor del tiquete, la tasa aeroportuaria y la tarifa administrativa.
requestDate String Fecha de solicitud o creación de la transacción acorde a ISO 8601, se obvia la hora de la solicitud

Transaction (Credito)

Estructura con la información de una transacción.

PARÁMETROS

Nombre Tipo Descripción
transactionID int El ID de referencia pasado al procesador.
sessionID string Identificador único de la sesión en Placetopay.
reference string La referencia de la transacción.
requestDate string Fecha de solicitud o creación de la transacción acorde a ISO 8601.
bankProcessDate string Fecha de procesamiento de la transacción acorde a ISO 8601.
onTest boolean Indicador de si la transacción es en modo de pruebas o no.
description string El dato pasado como x_description.
currency string El dato pasado como x_currency.
totalAmount double Valor total de la compra.
taxAmount double Impuesto asociado a la compra.
devolutionBase double Base de devolución del IVA.
tipAmount double El valor de la tasa aeroportuaria: x_airport_tax.
airline int Código de la aerolínea.
serviceFee double Valor total de la tasa administrativa.
serviceFeeTax double Impuesto asociado a la tasa administrativa.
serviceFeeBase double Base de devolución del IVA asociado a la tasa administrativa.
payer Person Información del pagador.
buyer Person Información del comprador (x_shipping_fields)
shipping Person Información del receptor, no usado actualmente.
ipAddress string Dirección IP desde la cual realiza la transacción el pagador.
userAgent string Agente de navegación (browser) utilizado por el pagador.
franchise string El código de la franquicia usada.
franchiseName string Nombre de la franquicia.
bankName string Nombre del banco del tarjeta o cuenta habiente.
bankCurrency string Moneda aceptada por el banco.
bankFactor float Factor de conversión de la moneda.
authorization string Número de autorización.
receipt string Número de recibo.
refunded boolean Indicador de si la transacción fue reversada.
transactionState string Información del estado de la transacción [OK, NOT_AUTHORIZED, PENDING, FAILED]
responseCode int Estado de la operación:
0 = Fallida
1 = Aprobada
2 = Rechazada
3 = Pendiente
responseReasonCode string Código interno de respuesta de la operación en Placetopay.
responseReasonText string Mensaje asociado con el código de respuesta de la operación en Placetopay.
serviceFeeTransactionState string Información del estado de la transacción de la tasa administrativa [OK, NOT_AUTHORIZED, PENDING, FAILED]
serviceFeeResponseCode int Estado de la operación de tasa administrativa:
0 = Fallida
1 = Aprobada
2 = Rechazada
3 = Pendiente
serviceFeeResponseReasonCode string Código interno de respuesta de la operación en Placetopay para la tasa administrativa.
serviceFeeResponseReasonText string Mensaje asociado con el código de respuesta de la operación en Placetopay para la tasa administrativa.
serviceFeeAuthorization string Número de autorización de la tasa administrativa.
serviceFeeReceipt string Número de recibo de la tasa administrativa.
additional Attribute[] Datos adicionales proporcionados con la transacció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.