Introduction

This service allows you to use Account Validator to get tokenized accounts, ensuring a higher level of security in the handling of sensitive information.

POST/gateway/account-validator/session

Create Session

This endpoint allows you to create a session for account verification.

Request

  • Name
    auth
    Type
    Autenticación
    is Required
    REQUIRED
    Description

    Structure that contains the site authentication information generated according to the WSSE UsernameToken Profile 1.1

  • Name
    user
    Type
    object
    is Required
    REQUIRED
    Description

    User owner of the account to validate

  • Name
    returnUrl
    Type
    string
    is Required
    REQUIRED
    Description

    Return URL once the account validation process is completed

    Example:https://www.placetopay.com/return
    Max length:255
  • Name
    locale
    Type
    string
    is optional
    Description

    Determines the language of the response

    Example:es_CO
    Max length:5
  • Name
    isAuthenticated
    Type
    boolean
    is optional
    Description

    Determines if an external authentication process has already been completed. The intention is not to validate the user's email twice. By default it is false, meaning that an OTP will be sent to validate the user if they have already validated accounts with microdeposits in the system

    Example:true

Solicitud

POST
/api/session
curl -X "POST" https://api-co-dev.placetopay.ws/gateway/account-validator/session \
  -H "Content-Type: application/json" \
  -d '{
      "locale": "es_CO",
      "auth": {
        "login":"aabbccdd1234567890aabbccdd123456",
        "tranKey":"ABC123example456trankey+789abc012def3456ABC=",
        "nonce":"NjE0OWVkODgwYjNhNw==",
        "seed": "2024-04-19T12:06:56-05:00"
      },
      "user": {
        "name": "John",
        "surname": "Doe",
        "email": "[email protected]"
      },
      "returnUrl": "https://www.placetopay.com",
      "locale": "es_PR"
  }'

Response

Session created successfully

  • Name
    data
    Type
    object
    is optional
    Description

    Structure containing the response to the request in the case of a successful status

  • Name
    status
    Type
    Status
    is optional
    Description

    Structure that contains information about a request or payment, informing its current status.


Respuesta

{
  "status": {
    "status": "OK",
    "reason": "00",
    "message": "string",
    "date": "2021-09-21T09:34:48-05:00"
  },
  "data": {
    "requestId": "9bd89c8d-6097-4d69-8ce9-d9b5ec35d8ea",
    "redirectUrl": "https://account-validator.placetopay.com/verification/redirect/9bd89c8d-6097-4d69-8ce9-d9b5ec35d8ea",
    "expiresAt": "2024-04-19 17:36:57"
  }
}
POST/gateway/account-validator/query

Check Session Status

This endpoint allows you to consult the status of the created session.

Possible statuses

Name
Description
APPROVED
La cuenta fue verificada exitosamente.
REJECTED
La verificación de cuenta fue rechazada.
FAILED
Ha ocurrido un error en el sistema.
PENDING
La verificación de cuenta está en proceso.

Status reasons

Code
Description
?C
The verification has been canceled by the user.
05
The verification has been rejected for general reasons.
BR
The data of the request is incorrect.
00
The verification has been successfully completed.
?-
The verification is in the process of validation.
38
Number of attempts exhausted.
HX
An error has occurred in the service.
X3
The information provided is invalid.
X5
Invalid social security number.
XN
Invalid account number.
?*
Pending validation by microdeposit.

Request

  • Name
    auth
    Type
    Autenticación
    is Required
    REQUIRED
    Description

    Structure that contains the site authentication information generated according to the WSSE UsernameToken Profile 1.1

  • Name
    requestId
    Type
    string
    is Required
    REQUIRED
    Description

    Unique identifier of the session you want to consult.

    Example:1f630ff7-9c02-4da4-82d4-d676709acb21
    Format:regex
    Pattern:^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
    Max length:36

Solicitud

POST
/api/query
curl -X "POST" https://api-co-dev.placetopay.ws/gateway/account-validator/query \
  -H "Content-Type: application/json" \
  -d '{
      "locale": "es_CO",
      "auth": {
        "login": "aabbccdd1234567890aabbccdd123456",
        "tranKey": "ABC123example456trankey+789abc012def3456ABC=",
        "nonce": "NjE0OWVkODgwYjNhNw==",
        "seed": "2024-04-19T12:06:56-05:00"
      },
      "requestId": "9bd89c8d-6097-4d69-8ce9-d9b5ec35d8ea"
  }'

Response

Session status checked successfully

  • Name
    status
    Type
    Status
    is optional
    Description

    Structure that contains information about a request or payment, informing its current status.

  • Name
    data
    Type
    object
    is optional
    Description

    Structure containing the response to the request in the case of a successful status


Respuesta

{
  "status": {
    "status": "OK",
    "reason": "00",
    "message": "string",
    "date": "2021-09-21T09:34:48-05:00"
  },
  "data": {
    "requestId": "9bd89c8d-6097-4d69-8ce9-d9b5ec35d8ea",
    "isAuthenticated": false,
    "token": {
        "token": "faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891",
        "subtoken": "fakesubtoken00005",
        "franchise": "fakeFranchise",
        "franchiseName": "fakeFranchiseName",
        "issuerName": "fakeIssuerName",
        "lastDigits": "1111",
        "validUntil": "2026-07-31"
    }
  }
}
POST/gateway/account-validator/validate

Validate Existing Account

Once the initial session creation is successfully completed, you can perform validations to the account as many times as you consider necessary, you only need to have the account information and the verification code delivered in the previous process.

Validations performed:

Currently, the result of the validations is based on the following rules:

  1. Account validation: It is verified that the account exists and has passed through a session creation process from the account verifier interface and additionally the generated token belongs to the merchant with which authentication is being made.
  2. Account validation: It is verified that the account exists and is active in the account verification provider, (PLAID, VaulPopular, Cuentas Comerciales, or the MOCK according to the case).
  3. Account validation: It is verified that the account to validate has a balance greater than or equal to the amount sent in the request.

Status reasons

Code
Description
05
The verification has been rejected for general reasons.
BR
The data of the request is incorrect.
00
The verification has been successfully completed.
XA
The amount is not available for this account.
HX
An error has occurred in the service.
X3
The information provided is invalid.
X5
Invalid social security number.
XN
Invalid account number.

Possible statuses

Name
Description
APPROVED
The account was successfully verified.
REJECTED
The account verification was rejected.
FAILED
An error has occurred in the system.

Request

  • Name
    auth
    Type
    Autenticación
    is Required
    REQUIRED
    Description

    Structure that contains the site authentication information generated according to the WSSE UsernameToken Profile 1.1

  • Name
    instrument
    Type
    object
    is Required
    REQUIRED
    Description

    Token a la que se le realizará la validación.

  • Name
    payment
    Type
    object
    is optional
    Description

    Structure containing payment information.

  • Name
    locale
    Type
    string
    is optional
    Description

    Language of the payment.

    Default value:en
    Example:es_CO

Solicitud

POST
api/verification/validate
curl -X "POST" https://api-co-dev.placetopay.ws/gateway/account-validator/validate \
  -H "Content-Type: application/json" \
  -d '{
        "auth": {
          "login": "aabbccdd1234567890aabbccdd123456",
          "tranKey": "ABC123example456trankey+789abc012def3456ABC=",
          "nonce": "NjE0OWVkODgwYjNhNw==",
          "seed": "2024-04-19T12:06:56-05:00"
        },
        "instrument": {
          "token": {
              "token": "faketoken12f233bd8f5d42138d681bf07ea8295429df07a4af287703e30c891",
              "subtoken": "fakesubtoken00005"
          }
        },
        "payment": {
          "amount": {
            "currency": "USD",
            "total": 100
          }
        },
        "locale": "es_ES"
  }'

Response

Validation status response

  • Name
    status
    Type
    Status
    is Required
    REQUIRED
    Description

    Structure that contains information about a request or payment, informing its current status.


Respuesta

{
    "status": "APPROVED",
    "reason": "00",
    "message": "The verification has been successfully completed",
    "date": "2024-04-19T20:51:52+00:00"
}