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


---

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