> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cashii.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understand the fundamental concepts behind Cashii's Remote Payment system.

This section explains the core concepts you'll encounter when working with Cashii's Remote Payments API.

## Remote Payments

A **Remote Payment** is the primary mechanism for integrations. It represents a payment request initiated by your application (e.g., your backend server) and fulfilled by a user through the Cashii ecosystem (either via the Cashii app or a supported bank card).

Think of it as creating a payment order that a user can then act upon.

### Attributes of a Remote Payment

A Remote Payment object contains the following key attributes:

* **`id`**: A unique 16-digit identifier automatically generated by Cashii for the payment request.
* **`amount`**: The payment amount specified in the smallest currency unit (cents for USD/EUR, kuruş for TRY, etc.). For example, `10098` represents `100.98`.
* **`currency`**: The three-letter ISO currency code (e.g., `USD`, `EUR`, `SYP`, `TRY`).
* **`note`**: A brief description or memo for the payment, visible to the involved parties.
* **`metadata`**: A flexible JSON object where you can store additional information relevant to your application (e.g., `{"orderId": "ORD-12345", "customerId": "CUST-678"}`). This is useful for tracking and reconciliation.
* **`status`**: Indicates the current state of the payment. See [Payment Statuses](#payment-statuses) for details.
* **`from`**: (Available after payment) The Cashii account number from which the payment was made.
* **`to`**: The Cashii account number (associated with your commercial account/API key) to which the payment is credited.
* **`payable_to`**: (Optional) You can restrict the payment to be fulfilled only by a specific Cashii account number.

### Payment Statuses

A Remote Payment progresses through several statuses:

* **`pending`**: The initial state after creation. The payment request has been generated but not yet acted upon by the user.
* **`paid`**: The user has successfully completed the payment.
* **`canceled`**: The payment was explicitly canceled (either by the user or potentially via API in future implementations).
* **`rejected`**: The payment attempt was rejected (e.g., insufficient funds, security checks).
* **`refunded`**: The payment was successfully made but later refunded.

### Standard Workflow

The following diagram illustrates the typical flow of information when a user initiates a payment via Cashii in your application:

![](https://cashii.notion.site/image/attachment%3A6c178327-267a-4b99-ac51-472511923ae6%3Aimage.png?table=block\&id=18881665-9b54-802a-a01b-fe0493d20431\&spaceId=f966c55f-0b52-48aa-950e-0d425035ab1d\&width=1120\&userId=\&cache=v2)

1. **User Action:** User clicks "Pay with Cashii" in your application (frontend).
2. **Request to Backend:** Your application sends payment details (amount, currency, etc.) to your backend server.
3. **Create Remote Payment:** Your backend server authenticates with the Cashii API (using your [API key](./authentication)) and sends a request to create a Remote Payment.
4. **Receive Payment ID:** Cashii API validates the request and responds with a unique `id` for the new Remote Payment (status is `pending`).
5. **Return ID to Frontend:** Your backend server returns the `paymentId` to your application.
6. **Redirect User:** Your application redirects the user to the Cashii Payment Page, including the `paymentId`. See [Payment Flow](./payment-flow) for details.
7. **User Pays:** The user completes the payment on the Cashii page/app.
8. **User Redirected Back:** Cashii redirects the user back to the `redirectUrl` you specified, appending payment status information. Your application should verify this status with your backend.

### Technical Workflow Detail

This diagram shows more backend interactions, including database updates:

![](https://cashii.notion.site/image/attachment%3A193a2e67-5aad-46a4-bc64-d2845e02987f%3Aimage.png?table=block\&id=18881665-9b54-803f-b271-f2a9a0077fb0\&spaceId=f966c55f-0b52-48aa-950e-0d425035ab1d\&width=710\&userId=\&cache=v2)

Key steps include:

* Storing the `paymentId` in your database after creation (Step 5) to track the order and potentially prevent duplicate requests.
* Verifying the final payment status by having your application query your backend (Step 10), which in turn queries the Cashii API (Step 11) using the `paymentId` before confirming success to the user (Step 12).