# Payment structure

The `Payments` entity represents all transactions processed through the `conomy_hq` platform. This includes:

* Local payments
* Cross-border payments
* Mass (bulk) payments
* Internal transfers (e.g., P2P or Collect)

All payments involve at least one **internal account**, either as the origin or the destination of funds.

{% hint style="info" %}
Think of a payment as: `origins` + `destinations` + `type` + `product`.
{% endhint %}

{% columns fullWidth="true" %}
{% column %}
{% content-ref url="payment-types" %}
[payment-types](https://developers.conomyhq.com/payments/payment-types)
{% endcontent-ref %}
{% endcolumn %}

{% column %}
{% content-ref url="origins-and-destinations/nodes" %}
[nodes](https://developers.conomyhq.com/payments/origins-and-destinations/nodes)
{% endcontent-ref %}
{% endcolumn %}
{% endcolumns %}

***

### Core Fields

Below are the key fields used in the Payment object:

| Field              | Description                                                                                                                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accountNumber`    | The internal account number receiving or executing the payment.                                                                                                                                         |
| `identityId`       | The entity (e.g., `USER` or `ORGANIZATION`) initiating the payment. This may be a user selling on behalf of an organization, topping up their own balance, or authorized to withdraw funds.             |
| `totalAmount`      | The final transaction amount after all fees and currency conversions have been applied.                                                                                                                 |
| `currency`         | The currency associated with `totalAmount`. Check the [currency page](https://developers.conomyhq.com/home/currencies) for more info.                                                                   |
| `purchaseAmount`   | The original amount before any fees or currency exchange were applied.                                                                                                                                  |
| `purchaseCurrency` | The currency in which the original `purchaseAmount` was initiated. Check the [currency page](https://developers.conomyhq.com/home/currencies) for more info.                                            |
| `product`          | Represents the payment product format, structured as `purchaseCurrency:currency`.                                                                                                                       |
| `status`           | The current status of the transaction, [see lifecycle below](#transaction-lifecycle).                                                                                                                   |
| `type`             | The payment type (e.g., `PURCHASE`, `TOPUP_ACCOUNT`, etc.). Check the [payment type page](https://developers.conomyhq.com/payments/payment-types) for more info.                                        |
| `fees`             | An array containing all fee transactions applied to this payment.                                                                                                                                       |
| `origins`          | Array of origin nodes — either an internal `ACCOUNT` or an external payment rail (e.g., `ETPAY`, `PIX`, `PCT`). See [Nodes](https://developers.conomyhq.com/payments/origins-and-destinations/nodes).   |
| `destinations`     | Array of destination nodes — either an internal `ACCOUNT` or a payout rail (e.g., `BANK_ACCOUNT`, `SPEI`, `ACH`). See [Nodes](https://developers.conomyhq.com/payments/origins-and-destinations/nodes). |

***

### Required Fields

To initiate a payment, the following fields are **mandatory**:

* `origins` (must contain at least one origin)
* `destinations` (must contain at least one destination)
* `product` (e.g., `CLP:USD`)
* `type` (one of the supported payment types)
* Either `purchaseAmount` or `totalAmount` must be provided
* Either `purchaseCurrency` or `currency` must be provided

For **bulk payments**, the `amount` field must also be defined at the origin or destination level. Check the [Origins and Destinations page](https://developers.conomyhq.com/payments/origins-and-destinations) for more information.

{% hint style="warning" %}
Provide either `purchaseAmount` or `totalAmount` (not both) and ensure `product` matches `purchaseCurrency:currency`.
{% endhint %}

***

### Transaction Lifecycle

The step of a payment evolves through the following lifecycle stages. For more information check the [payment status page](https://developers.conomyhq.com/payments/transaction-status).

| Status       | Description                                                                                          |
| ------------ | ---------------------------------------------------------------------------------------------------- |
| `CREATED`    | Transaction created. For rail-based pay-ins, the QR code or redirect URL is generated at this stage. |
| `AUTHORIZED` | Funds reserved. Applies to flows where pre-authorization is required before capture.                 |
| `CAPTURED`   | Funds captured from the origin. Call `POST /payments/{id}/captured` to trigger this step.            |
| `RECEIVED`   | Payment provider confirms the fund transfer. Triggered via webhook or sandbox simulation.            |
| `SETTLED`    | The transaction amount is fully validated and available in the destination account.                  |
| `DISPUTED`   | A dispute has been opened before settlement.                                                         |
| `REVERSED`   | The transaction was cancelled before settlement.                                                     |
| `FAILED`     | The transaction failed — the provider rejected the payment or an error occurred.                     |

***

### Settlement

The execution flow and expected processing time of a payment depend on the **combination of origins and destinations**. For example:

* External origins (e.g., card, bank transfer) may involve delays depending on the provider.
* Internal transactions (e.g., P2P, Collect) are instant.
* Cross-border payments may require currency conversion and sometimes additional processing time.

This entity serves as the **core model for all payment operations** within `conomy_hq`. A correct understanding and setup of this structure is essential for building reliable and traceable financial workflows.