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

# Quickstart Guide

> Get started quickly with Cashii API: account setup and basic payment requests.

This guide walks you through the essential first steps to integrate with Cashii: setting up your accounts and making your first API calls to create and check payments.

For a deeper understanding, refer to:

* [Authentication](./authentication): Generating and using API keys.
* [Core Concepts](./core-concepts): Understanding Remote Payments and workflows.
* [Payment Flow](./payment-flow): Handling user redirection and callbacks.

***

## 1. Account Setup

Before you can use the API, you need the correct Cashii accounts.

<AccordionGroup>
  <Accordion title="Creating a personal account" icon="user">
    First, ensure you have a verified Cashii personal account. Follow the steps outlined in the [account creation video](https://www.facebook.com/app.cashi/videos/563796253186277) if you don't have one.
  </Accordion>

  <Accordion title="Request a commercial account" icon="shop">
    Next, you need a commercial account to generate API keys. Request one from your personal account using this guide:

    <video controls className="w-full aspect-video" src="https://f003.backblazeb2.com/file/cashii-docs/videos/requesting-comercial-account.mp4" />
  </Accordion>
</AccordionGroup>

Once your commercial account is approved, you can proceed to generate an API key as described in the [Authentication](./authentication) guide.

***

## 2. Basic API Calls

With your [API key](./authentication), you can now interact with the Remote Payments API.

### Create a Remote Payment

This is the fundamental step to initiate a payment request.

**Endpoint:** [`POST /api/v1/remote-payments`](/api-reference/endpoint/Create%20a%20Remote%20Payment)

**Host:** `https://api.cashii.app`

**Headers:** `Authorization: Bearer YOUR_API_KEY`

**Request Body:**

```json
{
  "amount": 10098, // 100.98 in the specified currency (smallest unit)
  "currency": "SYP", // e.g., SYP, USD, TRY, EUR
  "note": "Payment for Order #ORD-12345",
  "metadata": { // Optional: Store your internal references
    "orderId": "ORD-12345",
    "customerId": "CUST-678"
  }
}
```

<RequestExample>
  ```bash cURL Example
  curl -X POST https://api.cashii.app/api/v1/remote-payments \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "amount": 10098,
          "currency": "SYP",
          "note": "Payment for Order #ORD-12345",
          "metadata": {
            "orderId": "ORD-12345",
            "customerId": "CUST-678"
          }
        }'
  ```

  ```json request-body.json
  {
    "amount": 10098, // 100.98
    "currency": "SYP",
    "note": "Payment for Order #ORD-12345",
    "metadata": {
      "orderId": "ORD-12345",
      "customerId": "CUST-678"
    }
  }
  ```
</RequestExample>

**Successful Response (201 Created):**

Cashii returns the unique `id` for this payment request.

```json
{
  "data": {
    "id": "1234567890123456" // Store this ID!
  }
}
```

<ResponseExample>
  ```json response-body.json
  {
    "data": {
      "id": "1234567890123456"
    }
  }
  ```
</ResponseExample>

You'll use this `id` to redirect the user. See [Payment Flow](./payment-flow).

### Retrieve Remote Payment Information

Use this endpoint to check the status and details of a payment request, especially after the user returns to your site.

**Endpoint:** [`GET /api/v1/remote-payments/{paymentId}`](/api-reference/endpoint/Retrieve%20Remote%20Payment%20Information)

**Host:** `https://api.cashii.app`

**Headers:** `Authorization: Bearer YOUR_API_KEY`

**Path Parameter:**

* `paymentId`: The 16-digit ID obtained when creating the payment.

<RequestExample>
  ```bash cURL Example
  curl https://api.cashii.app/api/v1/remote-payments/1234567890123456 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>

**Successful Response (200 OK):**

Returns the full details of the Remote Payment, including the crucial `status`.

```json
{
  "data": {
    "_id": "1234567890123456",
    "amount": 10098,
    "currency": "SYP",
    "status": "paid", // Check this status!
    "to": "YOUR_COMMERCIAL_ACCOUNT_NUMBER",
    "from": "CUSTOMER_ACCOUNT_NUMBER", // Populated after payment
    "note": "Payment for Order #ORD-12345",
    "metadata": {
      "orderId": "ORD-12345",
      "customerId": "CUST-678"
    },
    // ... other fields like timestamps
  }
}
```

<ResponseExample>
  ```json response-body.json
  {
    "data": {
      "_id": "1234567890123456",
      "amount": 10098,
      "currency": "SYP",
      "status": "paid",
      "to": "YOUR_COMMERCIAL_ACCOUNT_NUMBER",
      "from": "CUSTOMER_ACCOUNT_NUMBER",
      "note": "Payment for Order #ORD-12345",
      "metadata": {
        "orderId": "ORD-12345",
        "customerId": "CUST-678"
      }
    }
  }
  ```
</ResponseExample>

This call is essential for server-side verification of the payment status. See [Payment Flow](./payment-flow#verifying-payment-status-server-side).

***

## Next Steps

* Explore the full [API Reference](/api-reference) for all available endpoints and details.
* Review the [Payment Flow](./payment-flow) guide for handling user redirection.
* Consult the [Glossary](./glossary) for term definitions.