# Purchasing In-Game Items

## Direct Purchase with SHARD

* This API limited to 100,000 SHARD per transaction
* This API does not need user interaction to confirm the purchase, if you want to have user confirmation, you will need to do it from the game

## Pay Transaction with SHARD

<mark style="color:green;">`POST`</mark> `[endpoint]/v3/transaction/pay-with-shard`

#### Headers

| Name                                            | Type   | Description  |
| ----------------------------------------------- | ------ | ------------ |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer token |
| X-Api-Key<mark style="color:red;">\*</mark>     | String | API key      |

#### Request Body

| Name                                           | Type    | Description                                                             |
| ---------------------------------------------- | ------- | ----------------------------------------------------------------------- |
| description<mark style="color:red;">\*</mark>  | String  | Description of purchase, can be transaction ID generated from your game |
| shard\_price<mark style="color:red;">\*</mark> | Integer | Price to purchase in SHARD                                              |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "status": "success",
    "message": "Payment with SHARD Success",
    "data": {
        "KOMO_TX_ID": "48CBD65AC89E4D62260DD95A0A5680F7",
        "shard_price": "100",
        "description": "TEST1"
    }
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

```json
{
    "status": "error",
    "messages": "Insufficient SHARD"
}
```

{% endtab %}
{% endtabs %}

## Create Item Purchase Transaction

Another method to purchase game item with SHARD is using this API

1. Create transaction using `/v3/cashier/create` API. Notes: when you set callback\_url to your own server, you will receive webhook notification when user completed the payment. Otherwise, you will need to check if the payment has been done via `/v3/cashier/check` API.
2. After creating the transaction, you will be given URL to KOMO Cashier
3. Your game need to open this URL either with webview or open on the browser
4. If the user does not have enough SHARD to pay, then user can use other payment method to fulfill the transaction

## Create Transaction

<mark style="color:green;">`POST`</mark> `[endpoint]/v3/cashier/create`

#### Request Body

| Name                                                    | Type   | Description                                                                               |
| ------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------- |
| game\_transaction\_id<mark style="color:red;">\*</mark> | String | Transaction ID for your own purpose                                                       |
| list\_items<mark style="color:red;">\*</mark>           | JSON   | JSON array for list of purchased items [see below format](#example-of-list_items-payload) |
| callback\_url                                           | String | Your own webhook URL to receive confirmation callback                                     |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "status": "success",
    "messages": "Transaction created. Please open the URL below.",
    "data": {
        "game_tx_id": "KC-XXXXXX",
        "komo_tx_id": "A5B08BC5A5EA2645AE506E34DF56B03A",
        "webview_url": "https://cashier.komoverse.io?tx_id=A5B08BC5A5EA2645AE506E34DF56B03A"
    }
}
```

{% endtab %}
{% endtabs %}

## Check Transaction Status

<mark style="color:blue;">`GET`</mark> `[endpoint]/v3/cashier/check`

#### Query Parameters

| Name                                           | Type   | Description              |
| ---------------------------------------------- | ------ | ------------------------ |
| komo\_tx\_id<mark style="color:red;">\*</mark> | String | Komoverse Transaction ID |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "status": "success",
    "data": {
        "komo_tx_id": "A5B08BC5A5EA2645AE506E34DF56B03A",
        "game_tx_id": "KC-XXXXXX",
        "total_price": 40000,
        "payment_status": "pending"
    }
}
```

{% endtab %}
{% endtabs %}

#### Example of list\_items payload

```json
[
  {
    "item_image_url": "https://via.placeholder.com/200",
    "item_name": "Booster Item",
    "quantity": 2,
    "price": 5000
  },
  {
    "item_image_url": "https://via.placeholder.com/200",
    "item_name": "Booster XP",
    "quantity": 3,
    "price": 10000
  }
]
```

{% hint style="warning" %}
Please serialize / stringify the JSON array if you are sending payload as json instead of form-data
{% endhint %}