# Consulta
Permite a la red obtener información acerca de la transacción que el cliente desea realizar, proporcionando la referencia.
{% hint style="success" %}
Sandbox: [**https://api-test.payvalida.com/v4/recaudo/dinamico/recaudoconsulta**](https://api-test.payvalida.com/v4/recaudo/dinamico/recaudoconsulta)
{% endhint %}
{% hint style="warning" %}
*Los campos marcados con asteriscos (\*) son **obligatorios**.*
{% endhint %}
`POST` `https://api.payvalida.com/v4/recaudo/dinamico/recaudoconsulta`
Como criterios de búsqueda, la Red de recaudo tendrá las siguientes opciones que el API soporta: Reference, reference\_aux, request\_type y key\_value.
\
Con base en este criterio, Payválida retornará un listado de referencias para pago, es posible que dentro de las opciones solo haya una opción con la misma referencia de consulta, o que haya un listado de más referencias disponibles.\
\
En la respuesta, cada referencia de pago cuenta con una de las tres posibles opciones para pago:\
\&#xNAN;**- 1, Monto abierto**: El valor entregado a la Red es cero ($0), el cliente puede hacer un pago por un valor que se encuentra dentro de un rango definido por el comercio y que el cliente debe conocer.\
\&#xNAN;**- 2, Monto fijo**: Se retorna un valor asociado a la referencia, es el único valor que el cliente puede pagar.\
\&#xNAN;**- 3, Monto sugerido**: Se retorna un valor asociado a la referencia, sin embargo el cliente puede pagar un valor mayor o menor, dependiendo de un rango definido por el comercio y que el cliente debe conocer.\
\
La referencia del pago y con la cual se debe realizar el proceso de conciliación con la Red es la utilizada en la transacción financiera, el campo "*reference*" de este API es para efectos de consulta.
#### Request Body
| Name | Type | Description |
| -------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| netname\* | string | Nombre de identificación única de la Red de Recaudo. |
| request\_type\* | number | Valor debe ser 1. En caso de que por el contexto la red necesite definir opciones que permitan definir criterios podemos usar este valor, por ejemplo definir: 1-Abono capital, 2-Reducción cuota |
| reference\* | string | Referencia principal de la consulta |
| reference\_aux | string | Referencia opcional. Aplica para convenios que requieran una referencia adicional. |
| teller\* | string | Código de la tienda/punto en dónde se realiza la transacción (ip o punto de venta) |
| checksum\* | string | Cadena de comprobación, calculada con SHA512(netname + reference + FIXED\_HASH) |
| timestamp\* | number | La fecha y hora de la consulta, en formato Unix (segundos) |
| terminal\_code | string | Código de la terminal en dónde se realiza la transacción |
| geographic\_code\* | string | Hace referencia al código postal de la localidad en dónde se realiza la transacción, depende de la red/país que lo invoque. En Colombia se conoce como código DANE. |
| key\_value\* | string | Valor debe ser 1. En caso de que por el contexto la red necesite incluir posible configuración o condición especial que se deba tener en cuenta en la transacción se puede enviar una cadena con estructura llave-valor. |
{% tabs %}
{% tab title="200 code: 0000 cuando la respuesta sea exitosa.
text: Descripción del error, "OK" cuando la respuesta sea exitosa
name: Nombre del cliente
lastname1: Primer apellido del cliente
lastname2: Segundo apellido del cliente
description: Descripción general de la orden
di\_type: Tipo documento de identificación del cliente
di: Número de documento de identificación del cliente
commerce: Nombre del comeercio al cual está asociado el pago
payment\_options: Listado de referencias para pago (por lo menos una opción)
payment\_type: Tipo de valor a recaudar, 1-Monto abierto, 2-Monto fijo, 3-Monto sugerido.
payment\_reference: Referencia de pago, la que se debe enviar al momento de registrar la transacción financiera.
payment\_amount: Valor de la orden asociada a la referencia.
payment\_descip: Descripcíon específica para la referencia de pago.
timestamp: Tiempo en segundos formato Unix.
transaction\_cost: Costo de la transacción, informativo, no afecta el valor de la transacción.
checksum: Cadena de comprobación, calculada con SHA512(timestamp + sum(payment\_amount) + FIXED\_HASH). Solo se calcula cuando Body/data no está vacío. Para este calculo el campo "payment\_amount" debe estar sin decimales." %}
```
{
"CODE":"0000",
"DESC": "OK",
"DATA": {
"name":"Juan",
"lastname1":"Perez",
"lastname2":"",
"description":"Servicios financieros",
"di_type":"CC"
"di":"15987895",
"commerce":"kuanto",
"payment_options": [
{
"payment_type": 1,
"payment_reference": "902882727241",
"payment_amount": 0,
"payment_descrip": "Credito consumo 9989"
},
{
"payment_type": 2,
"payment_reference": "902882727242",
"payment_amount": 25000,
"payment_descrip": "Credito Hipotecario 8766"
},
{
"payment_type": 3,
"payment_reference": "902882727242",
"payment_amount": 56000,
"payment_descrip": "Credito rotativo 8788"
}
],
"timestamp": 1619649378,
"transaction_cost": 3000,
"checksum": "a5a43bfb7e2t6971062303f0a70722c8b6a2d5973a1c1e9f90ee74a9651e79410e4c04c384cffe406077d426070e070a1149e136bb035288b7c6ad0f957eff49"
}
}
```
{% endtab %}
{% endtabs %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.payvalida.com/cashin-redes/api/consulta.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.