> For the complete documentation index, see [llms.txt](https://developer.citypay.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.citypay.io/endpoint/payment-callback.md).

# Payment Callback

## Description

The callback URL will be used for sending updates and statuses of payments. The callback URL is indicated from the customer's cabinet on the configuration page.

### The order callback

The information about order status changes and new transactions will be sent to the callback URL.

{% hint style="warning" %}
 Callback data is sent in the **POST** method in JSON format.
{% endhint %}

CityPay callback sends data as it is described below:

| Name                        | Value                                                                                                    |
| --------------------------- | -------------------------------------------------------------------------------------------------------- |
| type                        | order callback                                                                                           |
| action                      | The information about the type of change: receive new transaction, order creation, receive confirmation. |
| status                      | CityPay Order [status ](/endpoint/order-status.md)for the moment you received the callback.              |
| order\_id                   | Unique ID of order, given by CityPay.                                                                    |
| client\_order\_id           | Custom order ID of the merchant. Should be used to identify order or invoice number.                     |
| transaction\_id             | Transaction id of the last transaction of this order.                                                    |
| received\_amount\_in\_coins | Amount of the last transaction in coins                                                                  |
| received\_amount\_in\_fiat  | Amount of the last transaction in fiat                                                                   |
| fiat\_currency              | Order's fiat currency.                                                                                   |
| crypto\_currency            | Order's cryptocurrency.                                                                                  |
| created\_at                 | Invoice creation time.                                                                                   |
| order\_token                | Unique token created by the customer.                                                                    |
| order\_expiration           | The time in minutes from order creation to its expiration.                                               |
| exchange\_rate              | The exchange rate for the moment transaction was received                                                |

You will receive calls in the three cases. First when an order will be generated and currency is chosen. Second when payment is received, and third when the status is changed. Note you won't receive calls for expired status.

### The deposit callback

The information about deposit transactions and their confirmation status are sent using this callback.

| Name             | Value                                                                |
| ---------------- | -------------------------------------------------------------------- |
| type             | deposit callback                                                     |
| action           | receive\_transaction/confirmation                                    |
| transaction\_id  | unique identification of the transaction                             |
| received\_amount | the amount received during the transaction                           |
| status           | Pending (0-5 confirmations); Confirmed (5+ confirmations)            |
| crypto\_currency | cryptocurrency id                                                    |
| exchange\_rate   | The exchange rate at the moment of transactions                      |
| crated\_at       | date transaction was sent                                            |
| deposit\_token   | the unique string which is given by the customer to the transaction. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://developer.citypay.io/endpoint/payment-callback.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.