Solicitar el token

Para llevar a un tarjetahabiente a PAR, tu servidor solicita un token con un mensaje XML que incluye tus credenciales, el documento del tarjetahabiente y las tarjetas que le emitiste. PAR responde, también en XML, con el token de un solo uso.

Credenciales

Placetopay te entrega las credenciales al darte de alta como socio emisor de PAR, y registra con ellas la configuración de tu emisor:

  • Name
    Usuario
    Type
    string
    is Required
    REQUERIDO
    Description

    Identifica a tu emisor. Viaja en el mensaje, en Perfil.NombreUsuario.

  • Name
    Contraseña
    Type
    string
    is Required
    REQUERIDO
    Description

    Autentica tu solicitud. Viaja en el mensaje, en Perfil.ContrasenaUsuario.

  • Name
    IP autorizadas
    Type
    list
    is Required
    REQUERIDO
    Description

    La lista de direcciones IP de tus servidores que Placetopay registra para tu emisor. En cada solicitud declaras una sola, en el campo IP del mensaje, y debe estar en esa lista.

  • Name
    Tipo de documento
    Type
    string
    is Required
    REQUERIDO
    Description

    El tipo de documento de identidad de tus tarjetahabientes. PAR valida el documento que envías contra el formato de ese tipo.

PAR opera en ambientes separados, y cada uno tiene su propia URL base y sus propias credenciales. En esta documentación, {URL_BASE} representa la URL del ambiente en el que estés trabajando.

Enviar la solicitud

POST {URL_BASE}/nuevopat/SolicitaTkn

El mensaje XML viaja como un campo de formulario llamado TBKPatData, con el tipo de contenido application/x-www-form-urlencoded. Su elemento raíz también se llama TBKPatData:

TBKPatData

<TBKPatData>
  <Perfil>
    <NombreUsuario>{TU_USUARIO}</NombreUsuario>
    <ContrasenaUsuario>{TU_CONTRASENA}</ContrasenaUsuario>
  </Perfil>
  <DuracionToken>300</DuracionToken>
  <DatosUsuario>
    <RutUsuario>11.111.111-1</RutUsuario>
  </DatosUsuario>
  <DataAuditoriaUsuario>session-0001</DataAuditoriaUsuario>
  <DatosTarjetas>
    <NumeroTarjeta>4111111111111111</NumeroTarjeta>
    <NumeroTarjeta>5180300000000005</NumeroTarjeta>
  </DatosTarjetas>
  <IP>203.0.113.10</IP>
</TBKPatData>

Campos del mensaje

  • Name
    Perfil.NombreUsuario
    Type
    string
    is Required
    REQUERIDO
    Description

    Usuario de tu emisor. Máximo 20 caracteres.

  • Name
    Perfil.ContrasenaUsuario
    Type
    string
    is Required
    REQUERIDO
    Description

    Contraseña de tu emisor. Máximo 15 caracteres.

  • Name
    DatosUsuario.RutUsuario
    Type
    string
    is Required
    REQUERIDO
    Description

    Documento de identidad del tarjetahabiente, en el formato del tipo de documento de tu emisor. Máximo 15 caracteres. Si corresponde a una persona ya registrada en PAR, la sesión se abre con su cuenta.

  • Name
    DatosTarjetas.NumeroTarjeta
    Type
    string
    is Required
    REQUERIDO
    Description

    Número de una tarjeta del tarjetahabiente, solo con dígitos y máximo 20. Repite el elemento por cada tarjeta, hasta un máximo de 5. Cada número debe ser un número de tarjeta válido.

  • Name
    IP
    Type
    string
    is Required
    REQUERIDO
    Description

    Dirección IP de tu servidor. Debe ser una de las IP autorizadas para tu emisor. Máximo 20 caracteres.

  • Name
    DuracionToken
    Type
    integer
    is optional
    Description

    Vigencia del token, en segundos. Si no lo envías, PAR aplica su vigencia por defecto. No puede superar el máximo que permite PAR.

  • Name
    DataAuditoriaUsuario
    Type
    string
    is optional
    Description

    Dato de auditoría propio de tu emisor, por ejemplo el identificador de la sesión en tu sitio. PAR lo conserva con la sesión. Máximo 40 caracteres.

Ejemplo

Solicitud

POST
/nuevopat/SolicitaTkn
curl --request POST \
  --url '{URL_BASE}/nuevopat/SolicitaTkn' \
  --data-urlencode 'TBKPatData=<TBKPatData><Perfil><NombreUsuario>{TU_USUARIO}</NombreUsuario><ContrasenaUsuario>{TU_CONTRASENA}</ContrasenaUsuario></Perfil><DatosUsuario><RutUsuario>11.111.111-1</RutUsuario></DatosUsuario><DatosTarjetas><NumeroTarjeta>4111111111111111</NumeroTarjeta></DatosTarjetas><IP>203.0.113.10</IP></TBKPatData>'

Respuesta

PAR responde siempre con un mensaje XML con el elemento raíz Mensaje. Si la solicitud es válida, Coderror vale 0 y el mensaje incluye el token:

Respuesta

<?xml version="1.0" encoding="UTF-8"?>
<Mensaje>
  <Coderror>0</Coderror>
  <Descerror>EXITO</Descerror>
  <Token>{TOKEN}</Token>
</Mensaje>
  • Name
    Coderror
    Type
    string
    is Required
    REQUERIDO
    Description

    Código del resultado. 0 indica éxito; cualquier otro valor, un error. El catálogo está en Errores.

  • Name
    Descerror
    Type
    string
    is Required
    REQUERIDO
    Description

    Texto informativo que acompaña al código, de hasta 80 caracteres. Puede cambiar, así que no lo uses para tomar decisiones.

  • Name
    Token
    Type
    string
    is Required
    REQUERIDO
    Description

    Token de un solo uso con el que el tarjetahabiente iniciará la sesión. Solo viene cuando Coderror es 0.

Los errores también responden con HTTP 200. Lee siempre Coderror para saber si obtuviste un token.

Qué valida PAR

Antes de emitir el token, PAR comprueba:

  1. Que TBKPatData llegue y sea un XML válido.
  2. Que estén todos los campos obligatorios, con sus formatos y longitudes.
  3. Que el usuario y la contraseña correspondan a un emisor activo.
  4. Que la IP declarada sea una de las IP autorizadas para tu emisor.
  5. Que el documento tenga el formato del tipo de documento de tu emisor.

Con el token en la mano, el siguiente paso es iniciar la sesión del tarjetahabiente.