# External consultation

The external consultation service can have two types of integration: its own agreement code or reference with a prefix (prefix + identification).

Integration with your own agreement is possible only with the baloto collection network. 

And the reference integration with prefix must follow the prefix + number format and guarantee a minimum length to be considered of 9 digits and a maximum of 16 digits. 

It is up to each merchant to decide how to fill in the missing digits, but it is recommended to use the number 0, for example: 326000034567

The external consultation service allows the merchant to be the one who has control of the order to be collected and the means of payment that will be used to make the payment.

<div align="left"><img src="https://3114594506-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MNsmrOb2q0SiO670iPn%2F-Mht-dA6Df5lV3elnNOQ%2F-Mht-pWU97SS7EsayHTc%2FCaptura%20de%20Pantalla%202021-08-24%20a%20la(s)%2011.34.10%20a.%C2%A0m..png?alt=media&#x26;token=c71b5a28-06ef-4fbf-9814-df665ffa1a4b" alt=""></div>

{% tabs %}
{% tab title="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](https://docs.payvalida.com/api-cashin-plus/api-cashin-plus-en/codigos-de-pais-y-monedas)) |
| timestamp\_start | Si        | Numérico     | 10       | Tiempo de inicio de la transacción en formato Unix Timestamp (Segundos) UTC                                                                         |
| checksum         | si        | Alfanumérico | 512      | Cadena de comprobación SHA512(reference + currency + netname + timestamp\_start +  FIXED\_HASH)                                                     |
| {% endtab %}     |           |              |          |                                                                                                                                                     |

{% tab title="Request (ejemplo)" %}

```go
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"
 }'
 

```

{% endtab %}

{% tab title="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) UTC                                                                                    |
| 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)                                            |
| {% endtab %}   |           |            |              |          |                                                                                                                                                                      |

{% tab title="Response (ejemplo)" %}

```
{
  "CODE":"0000", 
  "TEXT":"OK", 
  "DATA":{
     "order":"123456789",
     "amount":"0", 
     "description":"Orden de compra", 
     "email":"example@example.com", 
     "timestamp_end":"1581370646",
     "min":"0",
     "max":"10000", 
     “checksum”:”c07f779252b735c67df2c1945b68ca93f72100ece73dac778964aca...”
  }  
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Los montos mix y max son obligatorios si el monto es CERO.
{% endhint %}

{% hint style="info" %}
Es de suma importancia garantizar un tiempo de respuesta del servicio menor a 5 segundos, de lo contrario, nuestro sistema cerrará la conexión.
{% endhint %}

{% hint style="danger" %}
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.
{% endhint %}

## 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:&#x20;

Sin límites: order + amount + timestamp\_end + FIXED\_HASH                                                   &#x20;

Con límites: order + amount + min + max + timestamp\_end + FIXED\_HASH