> 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/api-recaudo-en/notification.md).

# Notification

{% hint style="warning" %}
A REST service needs to be developed for consumption by Payvalida, as it serves as the communication channel for the notification process.
{% endhint %}

{% hint style="info" %}
The notification URL is configured within our [merchant module](https://docs.payvalida.com/guia-del-modulo-comercial/) (Spanish), specifically in the account profile. You can find the detailed steps to follow [here](https://docs.payvalida.com/guia-del-modulo-comercial/configuraciones/perfil-de-cuenta) (Spanish).
{% endhint %}

When you register an order, the order its created with a **PENDING (PENDIENTE)** state. The order can change state depending on certain scenarios:

1. Payment is received -> Changes from **PENDING (PENDIENTE)** to **APPROVED (APROBADA)** and its notified with an ***approved*** status***.***
2. The order expires because it wasn't paid before the expiration date -> Changes from **PENDING (PENDIENTE)** to **EXPIRED (VENCIDA)** and its notified with a ***cancelled*** status.
3. The commerce *eliminates* the order (Using the API) -> Changes from **PENDING (PENDIENTE)** to **CANCELLED (CANCELADA)**, doesn't notify.
4. The customer asks for a refund of the payment -> Changes from **APPROVED (APROBADA)** to **NULLIFIED (ANULADA)** and its notified with a ***cancelled*** status.
5. The commerce asks for a refund of the payment -> Changes from **APPROVED (APROBADA)** to **NULLIFIED (ANULADA)**, doesn't notify.

| Name          | Parameter                                                        |
| ------------- | ---------------------------------------------------------------- |
| pv\_po\_id    | Order ID in Payvalida                                            |
| po\_id        | Order ID in the commerce                                         |
| status        | Order status                                                     |
| pv\_checksum  | Checksum encoded in SHA256(po\_id + status + NOTIFICATION\_HASH) |
| amount        | Order amount                                                     |
| iso\_currency | Currency of the order                                            |
| pv\_payment   | Payment method of the order                                      |

The system automatically notifies when the order changes its status, but its posible to send multiple notifications of the same order. ***It is responsibility of the commerce to avoid delivering the acquired product more than once in case of multiple notifications.***

The system registers the response that got on the notification process, it is advised to send an adequate response according to the process, for example, **OK** in a successful case and **ERROR** on an unsuccessful one, it is also recommended to attach a brief description with the response, for example: **"OK. Payment registered**", **"ERROR. Order not recognized"**

## Example

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

In the sandbox environment, it is possible to simulate payments to receive notifications at the webhook. To learn how to simulate payments, click [here](https://docs.payvalida.com/guia-del-modulo-comercial/simular-pagos/simular-pagos-en-sandbox) (spanish).