Consulta externa

Permite realizar una consulta de orden de pago al comercio

El servicio de consulta externa puede tener dos tipos de integración: código de convenio propio o referencia con prefijo (prefijo + identificación).

La integración con convenio propio es posible sólo con la red de recaudo baloto. Y la integración de referencia con prefijo debe de seguir el formato prefijo + número y garantizar una longitud mínima para ser considerada de ​9 dígitos y​ una máxima de ​16 dígitos​. Queda a disposición de cada comercio decidir cómo rellenar los dígitos faltantes, pero se recomienda utilizar el número 0, por ejemplo: 326000034567

El servicio de consulta externa, permite que el comercio sea quien tenga el control de la orden a recaudar y el medio de pago que se utilizará para realizar el pago.

Request
Request (ejemplo)
Response
Response (ejemplo)
Request

Campo

Requerido

Tipo

Longitud

Descripción

reference

Si

Numérico

16

Número de referencia proporcionado por el usuario

netname

Si

Alfanumérico

40

Nombre del medio de recaudo

currency

Si

Numérico

1

Moneda asociada al monto de la orden de compra (Monedas)

timestamp_start

Si

Numérico

10

Tiempo de inicio de la transacción en formato Unix Timestamp (Segundos)

checksum

si

Alfanumérico

512

Cadena de comprobación SHA512(reference + currency + netname + timestamp_start + FIXED_HASH)

Request (ejemplo)
curl --location --request POST '<Endpoint de cada comercio>' \
--header 'Content-Type: application/json' \
--data-raw '{
"reference":"123456789",
"netname":"VIA",
"currency":1,
"timestamp_start":1581370328,
"checksum":"71ff0ca3ffa49f0d13c7de5c661c6f8fddcab38004a195718e3d89d330005ee 34623959e93893cc2ff5f451b89b43dcc514c5767a2415066578adecbd4ef8242"
}'
Response

Campo

Requerido

Estructura

Tipo

Longitud

Descripción

CODE

si

-

Alfanumérico

4

Código de respuesta de errores "0000" para respuesta OK

TEXT

si

-

Alfanumérico

2

Descripción de respuesta "OK" para ejecución correcta.

DATA

si

-

estructura

-

Estructura json que contiene los datos de respuesta

order

si

DATA

Alfanumérico

200

Número de orden registrada en el sistema del comercio debe ser única. A este campo se le realiza una validación por expresión regular (^[a-zA-Z0-9_-]{1,200}$)

amount

si

DATA

Alfanumérico

20

Monto de la orden (puede ser cero)

description

si

DATA

Alfanumérico

40

Descripción corta de la orden. A este campo se le realiza una validación por expresión regular (^[\w -]+$)

email

si

DATA

Alfanumérico

100

Correo electrónico del usuario

timestamp_end

si

DATA

Alfanumérico

10

Tiempo de finalización de la transacción en formato Unix Timestamp (Segundos)

min

no*

DATA

Alfanumérico

20

Monto mínimo a pagar, default 0

max

no*

DATA

Alfanumérico

20

Monto máximo a pagar, default 999999999

checksum

si

DATA

Alfanumérico

512

Cadena de comprobación, calculada con SHA512(Revisar apartado de Checksum para conocer como realizar el cálculo correcto)

Response (ejemplo)
{
"CODE":"0000",
"TEXT":"OK",
"DATA":{
"order":"123456789",
"amount":"0",
"description":"Orden de compra",
"email":"[email protected]",
"timestamp_end":"1581370646",
"min":"0",
"max":"10000",
“checksum”:”c07f779252b735c67df2c1945b68ca93f72100ece73dac778964aca...”
}
}

Los montos mix y max son obligatorios si el monto es CERO.

Es de suma importancia garantizar un tiempo de respuesta del servicio menor a 5 segundos, de lo contrario, nuestro sistema cerrará la conexión.

Es potestad de cada comercio realizar la validación del medio de recaudo, es decir, de rechazar o no la petición de detalles de la orden de compra de acuerdo al medio que se envía.

Checksum

Si los montos min y max no son enviados, el checksum se calcula sin tener estos campos en cuenta. Los dos escenarios para el cálculo de checksum son:

Sin límites: order + amount + timestamp_end + FIXED_HASH

Con límites: order + amount + min + max + timestamp_end + FIXED_HASH