Request the token

To bring a cardholder to PAR, your server requests a token with an XML message that includes your credentials, the cardholder's document and the cards you issued to them. PAR answers, also in XML, with the single-use token.

Credentials

Placetopay gives you the credentials when it registers you as a PAR issuer partner, and records your issuer's configuration with them:

  • Name
    Username
    Type
    string
    is Required
    REQUIRED
    Description

    Identifies your issuer. It travels in the message, in Perfil.NombreUsuario.

  • Name
    Password
    Type
    string
    is Required
    REQUIRED
    Description

    Authenticates your request. It travels in the message, in Perfil.ContrasenaUsuario.

  • Name
    Authorized IPs
    Type
    list
    is Required
    REQUIRED
    Description

    The list of your servers' IP addresses that Placetopay registers for your issuer. In each request you declare a single one, in the message IP field, and it must be on that list.

  • Name
    Document type
    Type
    string
    is Required
    REQUIRED
    Description

    The identity document type of your cardholders. PAR validates the document you send against the format of that type.

PAR runs in separate environments, and each one has its own base URL and its own credentials. In this documentation, {BASE_URL} stands for the URL of the environment you are working in.

Send the request

POST {BASE_URL}/nuevopat/SolicitaTkn

The XML message travels as a form field named TBKPatData, with the application/x-www-form-urlencoded content type. Its root element is also named TBKPatData:

TBKPatData

<TBKPatData>
  <Perfil>
    <NombreUsuario>{YOUR_USERNAME}</NombreUsuario>
    <ContrasenaUsuario>{YOUR_PASSWORD}</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>

Message fields

  • Name
    Perfil.NombreUsuario
    Type
    string
    is Required
    REQUIRED
    Description

    Your issuer's username. Up to 20 characters.

  • Name
    Perfil.ContrasenaUsuario
    Type
    string
    is Required
    REQUIRED
    Description

    Your issuer's password. Up to 15 characters.

  • Name
    DatosUsuario.RutUsuario
    Type
    string
    is Required
    REQUIRED
    Description

    The cardholder's identity document, in the format of your issuer's document type. Up to 15 characters. If it belongs to a person already registered in PAR, the session opens with their account.

  • Name
    DatosTarjetas.NumeroTarjeta
    Type
    string
    is Required
    REQUIRED
    Description

    A card number of the cardholder, digits only and up to 20. Repeat the element for each card, up to a maximum of 5. Each number must be a valid card number.

  • Name
    IP
    Type
    string
    is Required
    REQUIRED
    Description

    Your server's IP address. It must be one of the IPs authorized for your issuer. Up to 20 characters.

  • Name
    DuracionToken
    Type
    integer
    is optional
    Description

    Token validity, in seconds. If you do not send it, PAR applies its default validity. It cannot exceed the maximum PAR allows.

  • Name
    DataAuditoriaUsuario
    Type
    string
    is optional
    Description

    Audit data of your own issuer, for example the session identifier on your site. PAR keeps it with the session. Up to 40 characters.

Example

Request

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

Response

PAR always answers with an XML message whose root element is Mensaje. If the request is valid, Coderror is 0 and the message includes the token:

Response

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

    Result code. 0 means success; any other value, an error. The catalog is in Errors.

  • Name
    Descerror
    Type
    string
    is Required
    REQUIRED
    Description

    Informative text that accompanies the code, up to 80 characters. It may change, so do not use it to make decisions.

  • Name
    Token
    Type
    string
    is Required
    REQUIRED
    Description

    Single-use token the cardholder will start the session with. Only present when Coderror is 0.

Errors also answer with HTTP 200. Always read Coderror to know whether you got a token.

What PAR validates

Before issuing the token, PAR checks:

  1. That TBKPatData is present and is valid XML.
  2. That all required fields are present, with their formats and lengths.
  3. That the username and password belong to an active issuer.
  4. That the declared IP is one of the IPs authorized for your issuer.
  5. That the document has the format of your issuer's document type.

With the token in hand, the next step is to start the session of the cardholder.