> For the complete documentation index, see [llms.txt](https://docs.payvalida.com/api-recaudo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payvalida.com/api-recaudo/notificacion.md).

# 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).