# 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 %}

<mark style="color:green;">`POST`</mark> `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<mark style="color:red;">\*</mark>          | string | Nombre de identificación única de la Red de Recaudo.                                                                                                                                                                     |
| request\_type<mark style="color:red;">\*</mark>    | 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<mark style="color:red;">\*</mark>        | string | Referencia principal de la consulta                                                                                                                                                                                      |
| reference\_aux                                     | string | Referencia opcional. Aplica para convenios que requieran una referencia adicional.                                                                                                                                       |
| teller<mark style="color:red;">\*</mark>           | string | Código de la tienda/punto en dónde se realiza la transacción (ip o punto de venta)                                                                                                                                       |
| checksum<mark style="color:red;">\*</mark>         | string | Cadena de comprobación, calculada con SHA512(netname + reference + FIXED\_HASH)                                                                                                                                          |
| timestamp<mark style="color:red;">\*</mark>        | 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<mark style="color:red;">\*</mark> | 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<mark style="color:red;">\*</mark>       | 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 %}