# Notificación

{% hint style="warning" %}
Se debe construir un servicio REST para ser consumido por Payvalida. A través de este servicio se hace el proceso de notificación. 
{% endhint %}

{% hint style="info" %}
La URL de notificación se configura en nuestro [módulo de comercios](https://docs.payvalida.com/guia-del-modulo-comercial/), en el perfil de cuenta. Puedes encontrar los pasos a seguir [aquí](https://docs.payvalida.com/guia-del-modulo-comercial/configuraciones/perfil-de-cuenta).
{% endhint %}

Al momento de registrar una orden, ésta se crea en estado **PENDIENTE**. La orden puede cambiar de estado por diversas razones:

1. Se ha recibido el pago correspondiente -> Cambia de **PENDIENTE** a **APROBADA** y se notifica con estatus ***approved.***
2. No se ha recibido el pago correspondiente antes de la fecha de vencimiento -> Cambia de **PENDIENTE** a **VENCIDA** y se notifica con estatus ***cancelled.***
3. El comercio *elimina* la orden (usando el API) -> Cambia de **PENDIENTE** a **CANCELADA**. No se notifica
4. El cliente realiza un reclamo de devolución del pago realizado -> Cambia de **APROBADA** a **ANULADA** y se notifica con estatus ***cancelled.***
5. El comercio solicita devolución del pago de un cliente -> Cambia de **APROBADA** a **ANULADA**, no se notifica.

El sistema notifica de forma automática en el momento del cambio de estado de la orden, pero es posible que exista más de una notificación de la misma orden.

{% hint style="danger" %}
Es responsabilidad del comercio evitar entregar mas de una vez el producto adquirido por el cliente en caso de que haya más de una notificación.
{% endhint %}

![](/files/-MNPposKz-mMucN9yBG0)

{% hint style="success" %}
Esta notificación se realizara a la **URL** proporcionada por el comercio.
{% endhint %}

{% tabs %}
{% tab title="Request (Realiza Payvalida)" %}

| Campo         | tipo   | Descripción                                                                       |
| ------------- | ------ | --------------------------------------------------------------------------------- |
| pv\_po\_id    | int    | Identificación de la orden de Payvalida                                           |
| po\_id        | string | Identificación de la orden del comercio                                           |
| status        | string | Estado de la orden. Puede ser ***approved** o **cancelled.***                     |
| pv\_checksum  | string | Cadena de comprobación calculada con SHA256(po\_id + status + NOTIFICATION\_HASH) |
| amount        | string | Monto de la orden                                                                 |
| iso\_currency | string | Moneda con la que se registra la orden                                            |
| pv\_payment   | string | Medio de pago con el que se registra ó se aprueba la orden                        |
| {% endtab %}  |        |                                                                                   |

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

```bash
curl --location --request POST 'https://url-comercio.com/notificacion/payvalida' \
--header 'Content-Type: application/json' \
--data-raw '{
    "pv_po_id":1934480,
    "po_id":"999999991",
    "status":"approved",
    "pv_checksum":"0C08309AE28D15E8D337344E88668E2047947F653B126B7F62B0EACC4B1A30FD680DBE25BD8B38413032A219B86BDAE52D9554D45A892CA4B5C5103597876EAD",
    "amount":"10500.0",
    "iso_currency":"COP",
    "pv_payment":"PSE"
}'
```

{% endtab %}

{% tab title="Respuesta (Esperada)" %}

```java
//Para este caso se puede responder en el body con texto claro y el mensaje
OK

//Adicionalmente se puede responder en el body una estructura json
{"status":"OK"}
```

{% endtab %}

{% tab title="Cabeceras" %}

| Cabecera      | Valor            |
| ------------- | ---------------- |
| Content-Type  | application/json |
| {% endtab %}  |                  |
| {% endtabs %} |                  |

{% hint style="warning" %}
De lado del comercio por motivos de seguridad se recomienda hacer la construcción del **pv\_checksum** con la credencial **NOTIFICATION\_HASH** entregada en el registro. Para validar que sea payvalida la que realiza la notificación al compararlas. 
{% endhint %}

{% hint style="info" %}
Cuando se notifica una orden aprobada, el valor del campo **pv\_payment** corresponde al medio de pago por el cual se paga la orden.

Cuando se notifica una orden vencida, el valor del campo **pv\_payment** corresponde al medio de pago indicado al momento de registrar la orden, en caso de no especificar el medio de pago, este campo no se envía en la petición.
{% endhint %}

El sistema registra la respuesta obtenida al momento de la notificación, por ello es recomendable enviar como respuesta un texto adecuado al proceso de notificación, por ejemplo, **OK** en caso afirmativo y **ERROR** en caso contrario, también se recomienda acompañar la respuesta de una breve descripción, como por ejemplo: **“OK. Pago registrado”**, **“ERROR. Orden no reconocida”**.

En sandbox (ambiente de pruebas) es posible simular pagos para recibir notificaciones al webhook. Para saber cómo simular pagos haz clic [aquí](https://docs.payvalida.com/guia-del-modulo-comercial/simular-pagos/simular-pagos-en-sandbox).


---

# 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/api-recaudo/notificacion.md?ask=<question>
```

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.